Alerts

Alerts triggered by Alert Rules.

Endpoints

The Alert object

  • idstring

    The unique identifier for the alert

  • projectIdinteger

    The unique identifier for the project the alert rule belongs to

  • homeIdinteger

    The unique identifier for the home the alert rule belongs to

  • alertRuleIdinteger

    The unique identifier for the alert rule

  • conditionobject

    The snapshot of condition that triggered the alert

  • descriptionstring

    The description of the alert

  • severityinteger

    The severity of the alert. 1 - High, 2 - Moderate, 3 - Low

  • entityIDstring

    The unique identifier for the entity the alert rule belongs to

  • entityTypestring

    The class of the entity

  • metricsDefinitionIDstring

    The identifier of the group that the metric in which the alert is invoked belongs to

  • metricNamestring

    The name of the metric in which the alert is invoked

  • stateinteger

    The state of the alert. 1 - Alerting, 2 - Recovered, 3 - Obsolete (an alert becomes obsolete when the alert rule is changed), 4 - Ineffective (an alert becomes ineffective when the alert rule is disabled)

  • invocationTimestring

    The time the alert was triggered

  • recoveryTimestring

    The time the alert was recovered

Get alerts

Endpoint
get /alerts
Description

Get a list of alerts that match the specified criteria.

Query Parameters

  • projectId

    integer

    required

    Return alerts of the specified project. Either projectId or homeId should be specified.

  • homeId

    integer

    required

    Return alerts of the specified home. Either projectId or homeId should be specified.

  • alertRuleId

    string

    Return alerts of the specified alert rule.

  • entityId

    string

    Return alerts of the specified entity.

  • state

    integer

    Return alerts with the specified state.

  • severity

    integer

    Return alerts with the specified severity.

  • skip

    integer

    Number of alerts to skip over.

  • limit

    integer

    Maximum number of alerts to return.

    Default value is 25

    Minimum value is 1

Request Headers What's this?

  • Authorization

    required

    To fetch the alerts of a project, the request must be made using the API the key of a user with permission to read project alerts, or a project API key. To fetch the alerts of a home, the request must be made using the API the key of a user with permission to read home alerts, or a project API key.

Response
  • 200Successful retrieval of alerts.
  • 401Authorization is required to access this resource.
  • 403Request failed because of denied permission.
  • 500An unexpected error has occurred.
  • 503The service is temporarily unavailable.

Response Body Sample

[
  {
    "id": "63ce9a3e9bc89f001b228c80",
    "projectId": 1,
    "homeId": 2,
    "alertRuleId": 5,
    "condition": {
      "conditionType": "metricsThreshold",
      "duration": "1min",
      "frequency": "1min",
      "delay": "1min",
      "aggregation": "avg",
      "thresholds": [
        {
          "severity": 1,
          "operator": "greaterThan",
          "operands": [
            0.86
          ]
        },
        {
          "severity": 2,
          "operator": "greaterThan",
          "operands": [
            0.85
          ]
        },
        {
          "severity": 3,
          "operator": "greaterThan",
          "operands": [
            0.84
          ]
        }
      ],
      "targetMetrics": [
        {
          "entityClass": "robot1",
          "metricsDefinitionId": "location",
          "metricName": "speed"
        }
      ]
    },
    "description": "Robot exceeded a speed limit",
    "severity": 1,
    "entityId": "robot1-1",
    "entityClass": "robot1",
    "metricsDefinitionId": "location",
    "metricName": "speed",
    "state": 1,
    "invocationTime": "2023-01-23T14:31:26Z"
  },
  {
    "id": "63ce9a3e9bc89f001b228c7f",
    "projectId": 1,
    "homeId": 2,
    "alertRuleId": 5,
    "condition": {
      "conditionType": "metricsThreshold",
      "duration": "1min",
      "frequency": "1min",
      "delay": "1min",
      "aggregation": "avg",
      "thresholds": [
        {
          "severity": 1,
          "operator": "greaterThan",
          "operands": [
            0.86
          ]
        },
        {
          "severity": 2,
          "operator": "greaterThan",
          "operands": [
            0.85
          ]
        },
        {
          "severity": 3,
          "operator": "greaterThan",
          "operands": [
            0.84
          ]
        }
      ],
      "metricsCondition": {
        "entityClass": "robot1",
        "metricsDefinitionId": "location",
        "metricName": "speed"
      },
      "targetMetrics": [
        {
          "entityClass": "robot1",
          "metricsDefinitionId": "location",
          "metricName": "speed"
        }
      ]
    },
    "description": "Robot exceeded a speed limit",
    "severity": 2,
    "entityId": "robot1",
    "entityClass": "robot1-1",
    "metricsDefinitionId": "metrics",
    "metricName": "speed",
    "state": 1,
    "invocationTime": "2023-01-23T14:31:26Z"
  }
]

Get an alert

Endpoint
get /alerts/{alertId}
Description

Return the alert with the specified ID.

Path Parameters

  • alertId

    string

    required

    Alert ID.

Request Headers What's this?

  • Authorization

    required

    Must contain the key of a user with permissions to read the alert or a project API key.

Response
  • 200Successfully retrieved the alert with specified ID.

Recover an alert

Endpoint
patch /alerts/{alertId}/recover
Description

Recover the alert with the specified ID.

Path Parameters

  • alertId

    string

    required

    Alert ID.

Request Headers What's this?

  • Authorization

    required

    Must contain the key of a user with permissions to update the alert or a project API key with admin permission.

Response
  • 204Successfully recovered the alert with specified ID.