Skip to main content

Effective 10 September 2024, API Documentation can be found on our Equinix Product Documentation site.
The content on this page will not be updated after 1 Oct 2024 and will be inaccessible after 31st Dec 2024.


Near Real-Time Feeds

Event Types​

alarm_updated

An alarm was updated. The alarm_active event is sent when an alarm is activated. It is sent to all user - accounts connected to the alarm. The alarm property is an alarm object containing information about the alarm.

{
    "name": "alarm_active",
    "alarm": { ... }
}

heartbeat notifications
Heartbeat events are sent weekly and offer details of heartbeat notifications on all subscribed alerts. They create awareness of effective communication between the streaming client and Equinix Streaming event provider.

Sample heartbeat notification - system alert

‌‌"@type" : "Alarm",
  "data" : {
    "sysAlertDefinitionId" : "PA4.Generator-C:summary:Multi-State:Alarm:3",
    "assetid" : "PA4.Generator-C",
    "ibx" : "PA4",
    "tagdisplayname" : "Summary",
    "sysAlertTriggerRule" : "STOPPED, NOT IN AUTO, ALARM",
    "heartbeat" : "true"
  },
  "name" : "alarm_updated"
}

Sample heartbeat notification - custom alert ‌‌

"@type" : "Alert",
  "data" : {
    "alertid" : "513709-15960581055100.6171420183265794",
    "timetriggered" : "1596058401201",
    "alerttype" : "electrical",
    "customerid" : "1000006198",
    "ibx" : "PA4",
    "heartbeat" : "true",
    "thresholdvalue" : "0"
  }

environment_updated

Environment Data was updated / received.

The environment_updated event is sent when environment data is updated or calculated. It is visible to the all accounts which have cage / cabinet in the location related to the environment information.

The environmentData property is a EnvironmentData object containing the environment information.

{
    "name": "environment_updated",
    "data": { ... }
}

environmental sensors
This provides updates to temperature and humidity events available for environmental sensors through its classification relevant to a cage in an IBX as seen in tag_id. These sensor readings (value, uom) for accounts from within specific zones of the IBX can be acquired with a timestamp.

Example

Received message 1410591350247580:
        Data: {"@type":"Tagpoint","data":{"value":"45","tagId":"PA4.Environmental.DH-10:humidity","tagDisplayName":"Humidity","uom":"%","readingTime":1596831714128,"oid":"1.3.6.1.2.1.299.37.7.1191.24"},"name":"tagpoint_updated"}
        Attributes: [object Object]

power_updated
Power Consumption Data was updated / received.

The power_updated event is sent when power consumption data is received or calculated. It is visible to the user who has access to accounts that own the circuits to which the power consumption data is related to.

The powerData property is a PowerData object containing the power consumption information

{
    "name": "power_updated",
    "data": { ... }
}

tagpoint_updated
A tagpoint value was updated.

tagpoint_updated event is sent when a tagpoint data is updated. It is sent to all users who have visibility to the tagpoint.

The tagPointData property is a TagPointData object containing latest information about the tagPoint.

{
    "name": "tagpoint_updated",
    "data": { ... }
}

Streaming API

PUSH method

Near real-time (NRT) Streaming API supports the PUSH method for those who do not wish to use the public clouds that Equinix supports, but have their own cloud and can provide a target URL to which DCIM data can be sent. This allows many enterprise customers to build their own multi-cloud hybrid solutions and enables them to receive the DCIM data through a web server and database.

AWS IoT Core and Microsoft Azure IoT

The message format for the AWS IoT Core and Azure Event Hubs channels makes the messages more readable.

Here are some examples of messages that are sent over API Plus subscriptions.

Environmental - temperature

{
    "type": "environmental",
    "data": {
        "ibx": "CH2",
        "asset": {
            "id": "asset1",
            "level": "ZONE"
        },
        "reading": {
            "value": "23.300",
            "unit": "CELSIUS"
        },
        "tag": {
            "id": "temperature",
            "displayName": "Temperature"
        },
        "readingTime": "2020-08-24T09:21:00.000Z"
    }
}

Environmental - humidity

{
    "type": "environmental",
    "data": {
        "ibx": "CH1",
        "asset": {
            "id": "asset1",
            "level": "ZONE"
        },
        "reading": {
            "value": "66.120",
            "unit": "PERCENT"
        },
        "tag": {
            "id": "humidity",
            "displayName": "Humidity"
        },
        "readingTime": "2020-07-28T12:35:14.615Z"
    }
}

Power

{
    "type": "power",
    "data": {
        "ibx": "SP2",
        "asset": {
            "id": "0210:469593",
            "type": "CIRCUIT"
        },
        "cage": "ssxxxxsss",
        "cabinet": "SP2:01:021470:0210",
        "accountNumber": "1000659151",
        "realPower": {
            "value": "0.522",
            "unit": "kW"
        },
        "apparentPower": {
            "value": "1.070",
            "unit": "kVA"
        },
        "contractualPower": {
            "value": "60.000",
            "unit": "kVA"
        },
        "current": {
            "value": "1.500",
            "unit": "A"
        },
        "powerFactor": {
            "value": "0.48",
            "unit": "pf"
        },
        "soldCurrent": {
            "value": "15.000",
            "unit": "A"
        },
        "soldPower": {
            "value": "2.880",
            "unit": "kVA"
        },
        "powerConsumptionToContractual": {
            "value": "32.151",
            "unit": "PERCENT"
        },
        "cabinetRating": {
            "value": "123.300",
            "unit": "kVA"
        },
        "peakLastSevenDays": {
            "value": "1.146",
            "unit": "kVA"
        },
        "peakLastSevenDaysRatio": {
            "value": "34.424",
            "unit": "PERCENT"
        },
        "peakLastSevenDaysContractualPower": {
            "value": "3.329",
            "unit": "kVA"
        },
        "peakLastSevenDaysTime": "2020-07-29T07:00:00.000Z",
        "lastUpdated": "2020-07-24T11:46:00.000Z",
        "readingTime": "2020-07-24T11:45:00.000Z",
        "description": "test description",
        "oid": "1.3.6.1.2.1.299.2.10.6846",
        "circuitType": "primary",
        "customerName": "test customer"
    }
}

Metered power - kWh

{
    "type": "metered-power",
    "data": {
        "ibx": "LD9",
        "asset": {
            "id": "LD9.CBM-PDU-17-99",
            "type": "Customer Billing Meter"
        },
        "cage": "LD9:0G:00Z13Z",
        "cageSerialNo": "00Z13B-21010567",
        "accountNumber": "1000006212",
        "customerName": "ABC Company",
        "kilowattHour": {
            "value": "304574.323",
            "unit": "kWh"
        },
        "readingTime": "2023-04-24T11:45:00.000Z",
        "dataQuality": "Good"
    }
}
 

Metered power readings are available in kWh, kW, kVA, A, and pf (power factor) units.

Tag-point

{
    "type": "tag-point",
    "data": {
        "ibx": "LA1",
        "reading": {
            "value": "33406.6",
            "unit": "l/s"
        },
        "tag": {
            "id": "LA1.Air-Handler-7-4-4:totalsupplyairflow",
            "displayName": "Total Supply Air Flow"
        },
        "readingTime": "2020-08-24T09:21:00.000Z"
    }
}

Custom alert

{
    "type": "alert",
    "data": {
        "ibx": "SG2",
        "region": "APAC",
        "asset": {
            "id": "CH1.Colo.CH1_05_000550_0105",
            "type": "ENVIRONMENTAL",
            "classification": "Environmental"
        },
        "tag": {
            "id": "temperature"
        },
        "threshold": {
            "unit": "CELSIUS",
            "maxValue": "-6.67",
            "minValue": "-12.22"
        },
        "id": "zhe-15603221441540.3171591127612322145",
        "triggeredTime": "2019-09-23T23:01:30.655Z",
        "type": "environmental",
        "typeId": "Absolute",
        "conditional": "N",
        "eventType": "Out of Range",
        "heartbeat": false
    }
}

System alert

{
    "type": "system-alert",
    "data": {
        "ibx": "SG2",
        "region": "APAC",
        "metro": "SG",
        "country": "SG",
        "currentValue": {
            "unit": "kWh",
            "value": "2.650479E7",
            "type": "float"
        },
        "asset": {
            "id": "9SG2.ELEC4AUPSR-A10ASBF0",
            "type": "Circuit Breaker with Metering",
            "classification": "Electrical"
        },
        "tag": {
            "id": "SG2.ELEC5BUPSR-B14UAH2Q:breaker",
            "displayName": "Bypass Not Available"
        },
        "conditionName": "Low",
        "status": {
            "acknowledged": true,
            "acknowledgementTime": "2020-07-28T12:35:14.615Z",
            "cleared": false,
            "active": false
        },
        "threshold": {
            "unit": "kWh",
            "stateLimit": "80",
            "message": "Drive not in Auto"
        },
        "severity": 820,
        "triggeredTime": "2020-07-28T12:35:14.615Z",
        "processedTime": "2020-07-28T12:35:14.615Z",
        "normalProcessedTime": "2020-07-28T12:35:14.615Z",
        "normalTriggeredTime": "2020-07-28T12:35:14.615Z",
        "type": "Digital",
        "heartbeat": false
    }
}

Data Quality Indicators

The field dataQuality offers the Data Quality Indicators (DQI) of data points and alerts (system and custom) as part of the data itself. This is used to ensure and inform the API client that the data for DCIM assets is valid and collected reliably. The addition of DQI provides transparency regarding the quality of received data.

Store and Forward Indicators

The field messageRetried as the Store and Forward Indicator (SNFI) is used to communicate if the DCIM data is actually near real-time or delayed and sent at a later time due to a disrupted connection through the NRT channel. If the connection between the subscription client and publisher has an issue, the publisher uses the Store and Forward (SNF) mechanism to store the message on the publisher's side. Once the connection is re-established, these stored messages and NRT events are sent to the client after the established connection time. The data sent later because of the SNFI method, is marked, as they are not NRT data anymore, compared to other normal data.

Your API applications can make business rules and decisions based on both these indicators to improve data transparency and solution efficiency.

{
  "messageRetried": true,
  "type": "tag-point",
  "data": {
    "ibx": "SG2",
    "reading": {
      "value": "54.0",
      "unit": "s"
    },
    "tag": {
      "id": "SG2.UPS-5-RM A22-04:batterytimeremaining",
      "displayName": "Battery Time Remaining"
    },
    "readingTime": "2021-03-25T03:48:00.510Z",
    "dataQuality": "Good"
  }
}

Object Types​

Alarm

{
    "type": "object",
    "description": "alarm object - properties of the alarm",
    "properties": {
        "timetriggered": {
            "type": "string",
            "description": "time when the criteria for the alarm was met, in epoch (ms)"
        },
        "valuetype": {
            "type": "string",
            "description": "data type for the alarm data point value",
            "enum": [
                "Float",
                "Bool",
                "Int"
            ]
        },
        "severity": {
            "type": "integer",
            "description": "integer value which describes the severity of the alarm. higher values indicate higher severity\n• 800-899 – Urgent\n• 600-699 – High \n• 400-499 – Low \n• 200-299 – Informational\n"
        },
        "timenormalprocessed": {
            "type": "string",
            "description": "time alarm was cleared in the system. \n"
        },
        "circuit": {
            "type": "string",
            "description": "circuit number applicable to power alarms"
        },
        "alarmtype": {
            "type": "string",
            "description": "alarm type indicates the type of alarm",
            "enum": [
                "digital",
                "absolute",
                "deviation",
                "multi-state"
            ]
        },
        "tagid": {
            "type": "string",
            "description": "tag id linked to the alarm. available for alarms on infra assets. unique identifier for the tag\n"
        },
        "uom": {
            "type": "string",
            "description": "unit of measure for the alarm value"
        },
        "cage": {
            "type": "string",
            "description": "cage us id linked to the alarm. available with power alarms or environmental alarms\n"
        },
        "timeprocessed": {
            "type": "string",
            "description": "time when the alarm was created in the system."
        },
        "assetid": {
            "type": "string",
            "description": "asset id linked to the alarm"
        },
        "metro": {
            "type": "string",
            "description": "metro id linked to the alarm"
        },
        "accountno": {
            "type": "string",
            "description": "customer account number"
        },
        "conditionname": {
            "type": "string",
            "description": "condition name for the alarm"
        },
        "region": {
            "type": "string",
            "description": "region linked to the alarm"
        },
        "value": {
            "type": "string",
            "description": "data point value at which the alarm was triggered"
        },
        "cabinet": {
            "type": "string",
            "description": "cabinet us id. applicable for power alarms"
        },
        "assettype": {
            "type": "string",
            "description": "Will contain\n• template name for alarms linked to infra assets.\n• \"environmental\" for environmental alarms.\n• \"CIRCUIT\" for power alarms \n"
        },
        "ibx": {
            "type": "string",
            "description": "ibx code"
        },
        "status": {
            "type": "boolean",
            "description": "indicator whether an alarm is active"
        },
        "assetclassification": {
            "type": "string",
            "description": "asset classification",
            "enum": [
                "Electrical",
                "Mechanical",
                "Environmental",
                "Power"
            ]
        }
    }
}

Alert

"AlertCondition": {
    "type": "object",
    "properties": {
        "affectedCustomerAsset": {
            "type": "null"
        },
        "alertType": {
            "type": "null"
        },
        "asset": {
            "type": "string"
        },
        "assetname": {
            "type": "string"
        },
        "assettype": {
            "type": "string"
        },
        "condalerttypeid": {
            "type": "string"
        },
        "condassetclassification": {
            "type": "string"
        },
        "condassetid": {
            "type": "string"
        },
        "condcurrentvalue": {
            "type": "string"
        },
        "condeventtype": {
            "type": "string"
        },
        "condtagid": {
            "type": "string"
        },
        "customerAssets": {
            "type": "null"
        },
        "ibx": {
            "type": "string"
        },
        "infraAssets": {
            "type": "null"
        },
        "measurementType": {
            "type": "null"
        },
        "region": {
            "type": "null"
        },
        "section": {
            "type": "string"
        },
        "thresholdUnit": {
            "type": "string"
        },
        "thresholdValue": {
            "type": "string"
        },
        "thresholdValueMax": {
            "type": "string"
        },
        "thresholdValueMin": {
            "type": "string"
        },
        "uom": {
            "type": "string"
        }
    }
},
"AlertType": {
    "type": "object",
    "properties": {
        "defaultValue": {
            "type": "null"
        },
        "eventType": {
            "type": "string"
        },
        "id": {
            "type": "string"
        },
        "tagId": {
            "type": "null"
        },
        "type": {
            "type": "string"
        },
        "unit": {
            "type": "string"
        },
        "value": {
            "type": "string"
        }
    }
},
"Alert": {
    "type": "object",
    "properties": {
        "accountNo": {
            "type": "string"
        },
        "acknowledge": {
            "type": "boolean"
        },
        "affectedCustomerAsset": {
            "type": "null"
        },
        "alertType": {
            "": "#/definitions/AlertType"
        },
        "alertTypeName": {
            "type": "string"
        },
        "asset": {
            "type": "string"
        },
        "assetclassification": {
            "type": "string"
        },
        "assetname": {
            "type": "string"
        },
        "assettype": {
            "type": "string"
        },
        "conditionalAlert": {
            "$ref": "#/definitions/AlertCondition"
        },
        "country": {
            "type": "string"
        },
        "createdOn": {
            "type": "null"
        },
        "currentvalue": {
            "type": "string"
        },
        "eventtype": {
            "type": "string"
        },
        "ibx": {
            "type": "string"
        },
        "id": {
            "type": "string"
        },
        "lastmaintenance": {
            "type": "string"
        },
        "metro": {
            "type": "string"
        },
        "modifiedOn": {
            "type": "null"
        },
        "notificationType": {
            "type": "string"
        },
        "region": {
            "type": "string"
        },
        "relatedincidents": {
            "type": "string"
        },
        "resiliency": {
            "type": "string"
        },
        "section": {
            "type": "string"
        },
        "severity": {
            "type": "string"
        },
        "tagid": {
            "type": "string"
        },
        "thresholdUnit": {
            "type": "string"
        },
        "thresholdValue": {
            "type": "string"
        },
        "thresholdValueMax": {
            "type": "string"
        },
        "thresholdValueMin": {
            "type": "string"
        },
        "timeZone": {
            "type": "string"
        },
        "timeacknowledged": {
            "type": "string"
        },
        "timeprocessed": {
            "type": "string"
        },
        "timetriggeredMilisec": {
            "type": "string"
        },
        "triggeredOn": {
            "type": "integer"
        },
        "type": {
            "type": "string"
        },
        "uom": {
            "type": "string"
        },
        "year": {
            "type": "string"
        }
    }
}

EnvironmentData

"EnvironmentData": {
    "type": "object",
    "properties": {
        "ibx": {
            "type": "string",
            "description": "ibx code"
        },
        "accountNo": {
            "type": "string",
            "description": "account number"
        },
        "zone": {
            "type": "string",
            "description": "zone unique space id"
        },
        "cage": {
            "type": "string",
            "description": "cage unique space id"
        },
        "cabinet": {
            "type": "string",
            "description": "cabinet unique space id"
        },
        "sensor": {
            "type": "string",
            "description": "sensor id"
        },
        "temperature": {
            "type": "string",
            "description": "current temperature"
        },
        "humidity": {
            "type": "string",
            "description": "current humidity"
        },
        "timestamp": {
            "type": "string",
            "description": "epoch timestamp when the current reading was read"
        },
        "temperatureUom": {
            "type": "string",
            "description": "unit of measure for temperature values"
        },
        "humidityUom": {
            "type": "string",
            "description": "unit of measure for humidity"
        },
        "minTemperature": {
            "type": "string",
            "description": "minimum temperature for last x(?) hours"
        },
        "maxTemperature": {
            "type": "string",
            "description": "maximum temperature for last x(?) hours"
        },
        "minHumidity": {
            "type": "string",
            "description": "minimum humidity for last x(?) hours"
        },
        "maxHumidity": {
            "type": "string",
            "description": "maximum humidity for last x(?) hours"
        }
    }
}

PowerData

"PowerData": {
    "type": "object",
    "properties": {
        "ibx": {
            "type": "string",
            "description": "ibx code"
        },
        "accountNo": {
            "type": "string",
            "description": "customer account number"
        },
        "levelType": {
            "type": "string",
            "description": "power hierarchy node levelType linked to the power data",
            "enum": [
                "ibx",
                "cage",
                "cabinet",
                "circuit"
            ]
        },
        "levelValue": {
            "type": "string",
            "description": "power hierarchy node levelValue linked to the power data. ibx code, \ncage unique space id, cabinet unique space id and circuit id for \nlevelType ibx, cage, cabinet, circuit resp.\n"
        },
        "isAlarm": {
            "type": "string"
        },
        "kva": {
            "type": "number",
            "description": "power consumption in kva"
        },
        "amps": {
            "type": "number",
            "description": "instantaneous current amp reading on circuits"
        },
        "cage": {
            "type": "string",
            "description": "cage unique space id"
        },
        "cabinet": {
            "type": "string",
            "description": "cabinet unique space id"
        },
        "soldKva": {
            "type": "number",
            "description": "maximum amp draw allowable on a circuit"
        },
        "cabinetRating": {
            "type": "number",
            "description": "maximum kVA draw allowed for the cabinet"
        },
        "contractualKva": {
            "type": "number",
            "description": "The maximum power draw contractually allowable in a \nprivate cage. \n"
        },
        "percentageKva": {
            "type": "number",
            "description": "calculated field kva / contractualKva"
        },
        "peakKvaLastSevenDays": {
            "type": "number"
        },
        "peakKvaLastSevenDaysPercentage": {
            "type": "number"
        },
        "peakKvaLastSevenDaysContractualKva": {
            "type": "number"
        },
        "peakKvaLastSevenDaysTime": {
            "type": "integer"
        },
        "type": {
            "type": "string",
            "description": "value to be IBX, CAGE, CABINET, primary or redundant for levelType\nibx, cage, cabinet, circuit resp.\n",
            "enum": [
                "IBX",
                "CAGE",
                "CABINET",
                "primary",
                "redundant"
            ]
        },
        "description": {
            "type": "string",
            "description": "circuit description when the levelType is circuit. null otherwise. \n"
        },
        "soldAmps": {
            "type": "integer"
        },
        "primaryKva": {
            "type": "number",
            "description": "the sum of instantaneous power draw reading on all the primary \ncircuits within the levelType.\n"
        },
        "redundantKva": {
            "type": "number",
            "description": "the sum of instantaneous power draw reading on all the redundant \ncircuits within the levelType.\n"
        },
        "kw": {
            "type": "string",
            "description": "measure of real power expressed in kilowatt applicable for ibxs\nthat have capability of energy meter reading\n"
        },
        "powerFactor": {
            "type": "string",
            "description": "The ratio between real power and apparent power in a circuit.(kW/kVA)\n"
        },
        "readingTime": {
            "type": "string",
            "description": "date-time when the latest value was read in (epoc - milliseconds). \n"
        },
        "lastUpdatedTime": {
            "type": "string",
            "description": "date-time when the latest value was updated (epoc - milliseconds).\n"
        },
        "customerName": {
            "type": "string"
        }
    }
}

MeteredPower

"MeteredPower": {
    "type": "object",
    "properties": {
        "ibx": {
            "type": "string"
        },
        "assetId": {
            "type": "string"
        },
        "assetSerialNumber": {
            "type": "string"
        },
        "assetType": {
            "type": "string"
        },
        "cage": {
            "type": "string"
        },
        "cageSerialNo": {
            "type": "string"
        },
        "accountNumber": {
            "type": "string"
        },
        "customerName": {
            "type": "string"
        },
        "readingTime": {
            "type": "string"
        },
        "dataQuality": {
            "type": "integer"
        },
        "ucid": {
            "type": "string"
        },
        "kilowattHour": {
            "type": "number"
        },
        "realPower": {
            "type": "number"
        },
        "apparentPower": {
            "type": "number"
        },
        "powerFactor": {
            "type": "number"
        },
        "current": {
            "type": "number"
        }
    }
}

TagPointData

"TagPointData": {
    "type": "object",
    "description": "Tag Point is a property of the Asset it is linked to.\n",
    "properties": {
        "value": {
            "type": "string",
            "description": "Current data value for the tag point\n"
        },
        "tagId": {
            "type": "string",
            "description": "ID for the tagPoint - Unique Identifier for the Tag Point\n"
        },
        "tagDisplayName": {
            "type": "string",
            "description": "Generic label for the tag point\n"
        },
        "uom": {
            "type": "string",
            "description": "Unit of measure for the data value for the tag point\n"
        },
        "alarmStatus": {
            "type": "string",
            "description": "Indicates whether there are any alarms currently active for the tag\npoint\n"
        },
        "readingTime": {
            "type": "string",
            "format": "date-time",
            "description": "date time when the tag point value was read from the device. \n"
        }
    }
}