Skip to content

Alarms

GET {baseURl}/v2/devices/nodes/:nodeId/alarms
Alarms list for a given node.

Example
https://clarity-data-api.clarity.io/v2/devices/nodes/A0000001/alarms?org=myorgVD43

About

Alarms are triggered by an unusual condition of the Node, that we learn from the telemetry a Node sends along with the sensor information. For example, if the battery charge is very low or if the battery is not charging properly, an alarm will be raised. Roughly every ten minutes, we check for conditions that will trigger an alarm.

If an alarm is already active and the triggering condition persists, then we extend the same alarm (as opposed to starting a new alarm). If the trigger condition has subsided, then we clear the alarm. You can see these three events in the timestamps on an alarm: startedAt lastExtendedAt clearedAt. If an alarm has started, but not cleared yet, the alarm is active. If the alarm has cleared, the alarm is inactive.

We retain inactive alarms for one year after they have cleared. After one year, those alarm records are dropped. We will not drop an alarm record if it has not cleared.

Headers

  • x-api-key: the API key string.

Request

path parameter description
nodeId string The target node ID (marked on the physical device).
Example "A0000001"
query parameter description
org string
required		 The ID of the organization.
Find it under the user profile section in Dashboard.
Example "myorgVD43"
active, inactive flags
  • GET /alarms?active returns only active alarms
  • GET /alarms?inactive returns only inactive alarms
  • GET /alarms?active&inactive returns all alarms whether they are active or not
startTime string If provided, all alarms with time earlier than startTime will be filtered out. Date string is expected to be in ISO 8601 format.
Example: startTime=2019-01-01T00:00:00Z
endTime string If provided, all alarms with time later than endTime will be filtered out. Date string is expected to be in ISO 8601 format.
Default: UTC current time.
Example: endTime=2019-01-02T00:00:00Z

Response

attribute description
alarmType string The alarm identifier.
See Alarm Type below.
nodeId string The node ID (marked on the physical device).
Example "A0000001"
label string The display name of the alarm type.
category string The alarm category.
See Alarm Category below.
active boolean Whether the alarm is still in effect or has already cleared.
details object Information related to how the alarm was started and extended.
See Alarm Details.
clearedAt string The ISO 8601 time where the alarm was cleared.
null if the alarm hasn't cleared yet.
Example: 2022-01-01T00:00:00Z
lastExtendedAt string The ISO 8601 time where the alarm was extended.
null if the alarm wasn't extended.
Example: 2022-01-01T00:00:00Z
startedAt string The ISO 8601 time where the alarm started.
Example: 2022-01-01T00:00:00Z

Alarm Type

For details about each alarm type, please consult the relevant knowledge base articles.

  • "NO2 readings out of expected range"
  • "NO2 sensor flapping" (intermittent NO₂ sensor data)
  • "NO2 sensor not responding"
  • "PM sensor flapping" (intermittent PM sensor data)
  • "PM sensor not responding"
  • "PM2.5 number to mass concentration ratio above expected bound"
  • "T-RH sensor not responding"
  • "faulty battery thermistor" (battery hardware charging issue)
  • "late reading"
  • "low battery"
  • "module not responding"
  • "module paired but not detected"
  • "module power error"
  • "on-board sensor module not responding"
  • "temperature readings out of expected range"
  • "too cold to charge battery"
  • "too hot to charge battery"
  • "unpaired module detected"
  • "weak signal"

Alarm Category

Families of alarms organized by topic.

  • accessorymodule: related to module errors and module detection by the main unit (e.g. "unpaired module detected")
  • activity: alarms raised by the node's unexpected behavior (e.g. "late reading")
  • communication: alarms related to node communication (e.g."weak signal")
  • internalsensors: alarms that indicate potential problems with the unit's on-board sensors (e.g. "PM sensor flapping")
  • power: power and battery related alarms (e.g. "low battery")

Alarm Details

Informs how the alarm was first raised (onStart) or last extended (onLastExtended). Both fields hold objects with the same shape with the exception that onLastExtended can be null if the alarm was never extended. The specific format of these objects can vary by alarmType.

Alarms of type late reading have the following details:

attribute type
lastReadingReceivedAt string (ISO 8601 datetime)
safetyMargin number (time interval in seconds)

All the remaining alarms have this format:

attribute type
numReadingsInPeriod number
numFaultyReadings number
pctFaultyReadings number (percentage)

Example 200 Response

[
    {
        "alarmType": "late reading",
        "nodeId": "A0000001",
        "label": "Late reading",
        "category": "activity",
        "active": false,
        "details": {
            "onStart": {
                "lastReadingReceivedAt": "2022-08-31T04:30:20.477Z",
                "safetyMargin": 1490
            },
            "onLastExtend": null
        },
        "clearedAt": "2022-08-31T05:11:23.829Z",
        "lastExtendedAt": null,
        "startedAt": "2022-08-31T05:01:25.358Z"
    },
    {
        "alarmType": "low battery",
        "nodeId": "A0000002",
        "label": "Low battery",
        "category": "power",
        "active": false,
        "details": {
            "onStart": {
                "numReadingsInPeriod": 1,
                "numFaultyReadings": 1,
                "pctFaultyReadings": 100.0,
                "lookedBackTo": "2022-08-31T05:00:00.000Z"
            },
            "onLastExtend": null
        },
        "clearedAt": "2022-09-01T05:11:22.837Z",
        "lastExtendedAt": null,
        "startedAt": "2022-09-01T05:01:24.545Z"
    }
]