DCIM Metric Data Feed API

  • Release version: Australia
  • Updated March 12, 2026
  • 8 minutes to read

    • The DCIM Metric Data Feed API provides an endpoint to accept Data Center Infrastructure Management (DCIM) metric data from an external system and store the data in a MetricBase database.

    This API receives near real-time metric data such as temperature, humidity, and power usage.

    This API can be extended for use with a chosen external system by implementing the scripted extension point TNIDCIMFeedParser. The default implementation TNIDCIMFeedParserImpl can be used as an example. For more information about extension points, see Using extension points to extend application functionality.

    This API is included in the Network Inventory Advanced application, which is available on the ServiceNow Store. This API also requires the MetricBase plugin (com.snc.clotho).

    The calling user must have the sn_ni_adv.metric_integrator role.

    DCIM Metric Data Feed - POST /sn_ni_adv/dcim/feed/{vendorname}

    Stores metric data such as temperature, humidity, and power usage into MetricBase.

    By default, this endpoint can be used to store data about the following types of configuration items (CIs):
    • Circuit [cmdb_ci_circuit]
    • Cabinet [cmdb_ci_container_cabinet]
    • Cage [cmdb_ci_cage]
    • Data Center [cmdb_ci_datacenter]
    • Data Center Zone [cmdb_ci_zone]

    To use this endpoint with additional CI types, create metric definitions and implement the scripted extension point TNIDCIMFeedParser.

    URL format

    Default URL: /api/sn_ni_adv/dcim/feed/{vendorname}

    Supported request parameters

    Table 1. Path parameters
    Name Description
    vendorname Name of the external system to receive metric data from.

    When using the default implementation of this API, this value is equinix. When using this API with other external systems, the vendorname used here must be included in your implementation of the TNIDCIMFeedParser extension point.

    Data type: String
    Table 2. Query parameters
    Name Description
    None
    Table 3. Request body parameters (JSON)
    Name Description
    data Required. The data to store in MetricBase.

    Data type: Object

    Note:
    The elements that must included in this object vary based on the type parameter and the configuration item type, such as datacenter or circuit.
    "data": {
   "apparentPower": {Object},
   "asset": {Object},
   "cabinet": "String",
   "cabinetRating": {Object},
   "cage": "String",
   "contractualPower": {Object},
   "ibx": "String",
   "kilowattHour": {Object},
   "peakLastSevenDays": {Object},
   "peakLastSevenDaysRatio": {Object},
   "powerConsumptionToContractual": {Object},
   "powerFactor": {Object},
   "reading": {Object},
   "readingTime": "String",
   "realPower": {Object},
   "soldCurrent": {Object},
   "tag": {Object}
}
    data.apparentPower Apparent power data in kilovolt-amperes. Required when the type parameter is power.

    Data type: Object

    "apparentPower": {      
   "unit": "String",
   "value": "String"  
}
    data.apparentPower.unit Unit of measurement. The only accepted value is kVA.

    Data type: String
    data.apparentPower.value The recorded kilovolt-amperes reading.

    Data type: String
    data.asset Asset data. Required for circuits when the type parameter is metered-power or power. Required for cabinets, cages, and zones when the type parameter is environmental.

    Data type: Object

    "asset": {
   "id": "String",
   "level": "String",
   "type": "String"
}
    data.asset.id Name of the asset.

    Table: Circuit [cmdb_ci_circuit], Cabinet [cmdb_ci_container_cabinet], Cage [cmdb_ci_cage], or Data Center Zone [cmdb_ci_zone]

    Field: Name

    Data type: String
    data.asset.level Type of asset. Used for cabinets, cages, and zones.
    Possible values:
    • CABINET
    • CAGE
    • ZONE

    Data type: String
    data.asset.type Type of asset. Used for circuits. The only accepted value is CIRCUIT.

    Data type: String
    data.cabinet Name of the cabinet. Required for cabinets when the type parameter is metered-power or power.

    Table: Container Cabinet [cmdb_ci_container_cabinet]

    Field: Name

    Data type: String
    data.cabinetRating Power usage the cabinet is rated for in kilovolt-amperes. Required when the type parameter is power.

    Data type: Object

    "cabinetRating": {      
   "unit": "String",
   "value": "String"  
}
    data.cabinetRating.unit Unit of measurement. The only accepted value is kVA.

    Data type: String
    data.cabinetRating.value The power usage rating for the cabinet.

    Data type: String
    data.cage Name of the cage. Required for cages when the type parameter is metered-power or power.

    Table: Cage [cmdb_ci_cage]

    Field: Name

    Data type: String
    data.contractualPower Power usage allotted by the contract in kilovolt-amperes. Required when the type parameter is power.

    Data type: Object

    "contractualPower": {      
   "unit": "String",
   "value": "String"  
}
    data.contractualPower.unit Unit of measurement. The only accepted value is kVA.

    Data type: String
    data.contractualPower.value The power usage allotted by the contract.

    Data type: String
    data.ibx Name of the datacenter.

    Required when storing metric data for a datacenter.

    Table: Data Center [cmdb_ci_datacenter]

    Data type: String
    data.kilowattHour Power usage data in kilowatt-hours. Required when the type parameter is metered-power.

    Data type: Object

    "kilowattHour": {      
   "unit": "String",
   "value": "String"  
}
    data.kilowattHour.unit Unit of measurement. The only accepted value is kWh.

    Data type: String
    data.kilowattHour.value The recorded kilowatt-hours reading.

    Data type: String
    data.peakLastSevenDays The maximum power usage within the last week in kilovolt-amperes. Required when the type parameter is power.

    Data type: Object

    "peakLastSevenDays": {      
   "unit": "String",
   "value": "String"  
}
    data.peakLastSevenDays.unit Unit of measurement. The only accepted value is kVA.

    Data type: String
    data.peakLastSevenDays.value The maximum power usage value from the last week.

    Data type: String
    data.peakLastSevenDaysRatio The maximum percentage of power used out of the amount allotted by the contract within the last week. Required when the type parameter is power.

    Data type: Object

    "peakLastSevenDaysRatio": {      
   "unit": "String",
   "value": "String"  
}
    data.peakLastSevenDaysRatio.unit Unit of measurement. The only accepted value is PERCENT.

    Data type: String
    data.peakLastSevenDaysRatio.value The maximum percent of power used.

    Data type: String
    data.powerConsumptionToContractual Percentage of power used out of the amount allotted by the contract. Required when the type parameter is power.

    Data type: Object

    "powerConsumptionToContractual": {      
   "unit": "String",
   "value": "String"  
}
    data.powerConsumptionToContractual.unit Unit of measurement. The only accepted value is PERCENT.

    Data type: String
    data.powerConsumptionToContractual.value The percent of power used.

    Data type: String
    data.powerFactor Power factor data. Required when the type parameter is power.

    Data type: Object

    "powerFactor": {      
   "unit": "String",
   "value": "String"  
}
    data.powerFactor.unit Unit of measurement. The only accepted value is pf.

    Data type: String
    data.powerFactor.value The power factor value.

    Data type: String
    data.reading The collected environmental data. Required when the type parameter is environmental.

    Data type: Object

    "reading": {      
   "unit": "String",
   "value": "String"  
}
    data.reading.unit Unit of measurement.
    Possible values:
    • CELSIUS: Used when data.tag.id is temperature.
    • PERCENT: Used when data.tag.id is humidity.

    Data type: String
    data.reading.value The recorded value.

    Data type: String
    data.readingTime Required. Date and time the data was collected.

    This value must be in UTC in ISO 8601 format. For example, 2025-07-03T16:22:15.000Z.

    Data type: String
    data.realPower Power usage data in kilowatts. Required when the type parameter is power.

    Data type: Object

    "realPower": {      
   "unit": "String",
   "value": "String"  
}
    data.realPower.unit Unit of measurement. The only accepted value is kW.

    Data type: String
    data.realPower.value The recorded kilowatts reading.

    Data type: String
    data.soldCurrent Electric current allotted by the contract in amps. Required when the type parameter is power.

    Data type: Object

    "soldCurrent": {      
   "unit": "String",
   "value": "String"  
}
    data.soldCurrent.unit Unit of measurement. The only accepted value is A.

    Data type: String
    data.soldCurrent.value The electric current allotted by the contract.

    Data type: String
    data.tag Object containing the type of environmental data. Required when the type parameter is environmental.

    Data type: Object

    "tag": {
   "id": "String"
}
    data.tag.id The type of environmental data.
    Possible values:
    • humidity
    • temperature

    Data type: String
    type Required. Type of metric data.
    Possible values:
    • environmental: Used for humidity or temperature.
    • metered-power: Used for power usage in kilowatt-hours (kWh).
    • power: Used for power usage in kilowatts (kW) and kilovolt-amperes (kVA).

    Data type: String

    Headers

    The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

    Table 4. Request headers
    Header Description
    Accept Data format of the response body. Only supports application/json;charset=UTF-8.
    Authorization Basic.
    Content-Type Data format of the request body. Only supports application/json.
    Table 5. Response headers
    Header Description
    Content-Type Data format of the response body. Only supports application/json;charset=UTF-8.

    Status codes

    The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

    Table 6. Status codes
    Status code Description
    200 Successful. The request was successfully processed.
    400 Bad Request. A bad request type or malformed request was detected.
    401 Unauthorized. The user credentials are incorrect or have not been passed.
    403 Forbidden. The user doesn't have access rights to the specified record.
    404 Not found. The requested item wasn't found.
    429 Too many requests.
    500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

    Response body parameters (JSON)

    Name Description
    result Details about the request.

    Data type: Object

    "result": {
   "status": "String",
   "sys_id": "String"
}
    result.status Status of the request.

    Data type: String
    result.sys_id Sys_id of the CI updated with the metric data.

    Table: Circuit [cmdb_ci_circuit], Cabinet [cmdb_ci_container_cabinet], Cage [cmdb_ci_cage], Data Center [cmdb_ci_datacenter], or Data Center Zone [cmdb_ci_zone]

    Data type: String

    cURL request

    Stores metered power data for a datacenter.

    curl "https://instance.service-now.com/api/sn_ni_adv/dcim/feed/vendorname" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
    "type": "metered-power",
    "data": {
        "ibx": "Datacenter Name",
        "kilowattHour": {
            "value": "40509.323",
            "unit": "kWh"
        },
        "readingTime": "2025-07-03T16:22:15.000Z"
    }
}" \
--user 'username':'password'

    Response body.

    {
    "result": {
        "status": "success",
        "sys_id": "c88dde85ff2662109cb9ffffffffffcc"
    }
}

    cURL request

    Stores power data for a circuit.

    curl "https://instance.service-now.com/api/sn_ni_adv/dcim/feed/vendorname" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
    "type": "power",
    "data": {
        "asset": {
            "id": "Circuit Name",
            "type": "CIRCUIT"
        },
        "realPower": {
            "value": "0.522",
            "unit": "kW"
        },
        "apparentPower": {
            "value": "1.070",
            "unit": "kVA"
        },
        "contractualPower": {
            "value": "60.000",
            "unit": "kVA"
        },
        "powerFactor": {
            "value": "0.48",
            "unit": "pf"
        },
        "soldCurrent": {
            "value": "15.000",
            "unit": "A"
        },
        "powerConsumptionToContractual": {
            "value": "32.151",
            "unit": "PERCENT"
        },
        "cabinetRating": {
            "value": "123.300",
            "unit": "kVA"
        },
        "peakLastSevenDays": {
            "value": "1.146",
            "unit": "kVA"
        },
        "peakLastSevenDaysRatio": {
            "value": "34.424",
            "unit": "PERCENT"
        },
        "readingTime": "2025-07-03T16:22:15.000Z"
    }
}" \
--user 'username':'password'

    Response body.

    {
    "result": {
        "status": "success",
        "sys_id": "c67dbe45fc2662109cb9ffffffffffcd"
    }
}

    cURL request

    Stores temperature data for a zone.

    curl "https://instance.service-now.com/api/sn_ni_adv/dcim/feed/vendorname" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
    "type": "environmental",
    "data": {
        "asset": {
            "id": "Zone Name",
            "level": "ZONE"
        },
        "reading": {
            "value": "23.300",
            "unit": "CELSIUS"
        },
        "tag": {
            "id": "temperature"
        },
        "readingTime": "2025-07-03T16:22:15.000Z"
    }
}" \
--user 'username':'password'

    Response body.

    {
    "result": {
        "status": "success",
        "sys_id": "c64dbc42fe2862109cb9ffffffffffed"
    }
}

    cURL request

    Stores humidity data for a cabinet.

    curl "https://instance.service-now.com/api/sn_ni_adv/dcim/feed/vendorname" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
    "type": "environmental",
    "data": {
        "asset": {
            "id": "Test Cabinet",
            "level": "CABINET"
        },
        "reading": {
            "value": "66.120",
            "unit": "PERCENT"
        },
        "tag": {
            "id": "humidity"
        },
        "readingTime": "2025-07-03T16:22:15.000Z"
    }
}" \
--user 'username':'password'

    Response body.

    {
    "result": {
        "status": "success",
        "sys_id": "c24dbc82fe3862107cb9ffffffffffbc"
    }
}