Get alerts

GET/alerts

Base URL: https://api.tinkermode.com

Get a list of alerts that match the specified criteria.

Authentication

Send an Authorization header of the form ModeCloud <AUTH_CODE>.

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

Query parameters

Name	Type	Required	Constraints	Description
`alertRuleId`	string	No		Return alerts of the specified alert rule.
`beginInvocationTime`	string	No		Return alerts bound by this invocation timestamp. Format must conform to RFC3339.
`beginRecoveryTime`	string	No		Return alerts bound by this recovery timestamp. Format must conform to RFC3339.
`endInvocationTime`	string	No		Return alerts bound by this invocation timestamp. Format must conform to RFC3339.
`endRecoveryTime`	string	No		Return alerts bound by this recovery timestamp. Format must conform to RFC3339.
`entityId`	string	No		Return alerts of the specified entity. Accepts a comma-separated list of entity IDs.
`includeDescendants`	boolean	No		Only meaningful together with the entityId filter. If true, an entity also matches alerts invoked by its descendants. Defaults to false.
`limit`	integer	No	default: 25; min: 1	Maximum number of alerts to return.
`projectId`	integer	Yes		Return alerts of the specified project.
`severity`	integer	No		Return alerts with the specified severity.
`skip`	integer	No	default: 0; min: 0	Number of alerts to skip over.
`state`	integer	No		Return alerts with the specified state.

Responses

`200` Successful retrieval of alerts.

Content type: application/json

Represents an alert

An array of objects with the following shape:

Property Type Required Constraints Description

alertRuleId integer No The unique identifier for the alert rule

condition one of 4 No The snapshot of condition that triggered the alert. The shape is discriminated by conditionType.

One of the following 4 shapes:

Variant 1

Evaluates an aggregated metric value against one or more severity-based thresholds.

Property Type Required Constraints Description

aggregation string Yes one of: avg, min, max, sum, count The aggregation function applied to the metric over duration.

conditionType string Yes one of: metricsThreshold The discriminator for the condition type. Must be metricsThreshold.

delay string No Optional. How long the evaluation is delayed after the job is dispatched (e.g. 1min). Capped at 10 days. Note (Alerting V2): this field is not used by evaluation scheduling; the server silently replaces invalid values with 0sec.

duration string Yes Required. The time range over which data points are aggregated for evaluation (e.g. 1min, 10min, 1hour). Must be a positive, non-zero multiple of the job invocation interval. Capped at 10 days (V2: 1 day). Note (Alerting V2): the multiple-of-interval constraint does not apply; any positive, non-zero duration up to 1 day is accepted.

frequency string No Optional. How often the condition is evaluated (e.g. 1min, 10min, 1hour). Capped at 1 hour. Note (Alerting V2): this field is not used by evaluation scheduling; the server silently replaces invalid values with 1min and the actual cadence is controlled by the platform.

metricsCondition object Yes The metric on which the condition is evaluated.

Property Type Required Constraints Description

entityClass string Yes The entity class that owns the metric.

entityTargetCondition object No Optional. Constraint on which entities the condition applies to. When omitted, the condition applies to the entity that owns the alert rule.

Properties of entityTargetCondition
Property	Type	Required	Constraints	Description
`entityIds`	array<string>	Yes		The entity IDs to target (or exclude).
`exclude`	boolean	No		If true, the listed entities are excluded instead of included.
`targetBy`	string	Yes	one of: parents, entities	How to target entities.

metricName string Yes The name of the metric inside the metrics definition.

metricsDefinitionId string Yes The identifier of the metrics definition.

thresholds array<one of 3> Yes min items: 1 Severity-based thresholds. The first matching threshold determines the severity. Duplicate severities are not allowed.

Properties of thresholds
Property	Type	Required	Constraints	Description
`operands`	array<number>	Yes		Operand values for the operator. Single value for `greaterThan`/`lessThan`/etc., two values for `between`/`outside` (with `operands[0] < operands[1]`), list for `in`/`notIn`.
`operator`	string	Yes	one of: greaterThan, greaterThanOrEqualTo, lessThanOrEqualTo, lessThan, between, outside, in, notIn	The comparison operator applied to the aggregated value and `operands`.
`severity`	integer	Yes	one of: 1, 2, 3	Alert severity. 1 - High, 2 - Moderate, 3 - Low.

One of the following 3 shapes:

Variant 1

Property	Type	Required	Constraints	Description
`operands`	unknown	No	min items: 1; max items: 1
`operator`	unknown	No	one of: greaterThan, greaterThanOrEqualTo, lessThanOrEqualTo, lessThan

Variant 2

Property	Type	Required	Constraints	Description
`operands`	unknown	No	min items: 2; max items: 2
`operator`	unknown	No	one of: between, outside

Variant 3

Property	Type	Required	Constraints	Description
`operands`	unknown	No	min items: 1; max items: 1000
`operator`	unknown	No	one of: in, notIn

Variant 2

Fires an alert when a metric stops reporting data points for the configured duration.

Property Type Required Constraints Description

conditionType string Yes one of: metricsHeartbeat The discriminator for the condition type. Must be metricsHeartbeat.

delay string No Optional. How long the evaluation is delayed after the job is dispatched. Must be a multiple of the job invocation interval. Capped at 10 days.

duration string Yes Required. The window in which at least one data point is expected (e.g. 1min, 10min, 1hour). Must be a positive, non-zero multiple of the job invocation interval. Capped at 90 days.

frequency string No Optional. How often the condition is evaluated (e.g. 1min). Must be a multiple of the job invocation interval. Capped at 1 hour.

metricsCondition object Yes The metric whose heartbeat is monitored.

Property Type Required Constraints Description

entityClass string Yes The entity class that owns the metric.

entityTargetCondition object No Optional. Constraint on which entities the condition applies to. When omitted, the condition applies to the entity that owns the alert rule.

Properties of entityTargetCondition
Property	Type	Required	Constraints
`entityIds`	array<string>	Yes
`exclude`	boolean	No
`targetBy`	string	Yes	one of: parents, entities

metricName string Yes The name of the metric inside the metrics definition.

metricsDefinitionId string Yes The identifier of the metrics definition.

severity integer Yes one of: 1, 2, 3 The severity emitted when the heartbeat is missed. 1 - High, 2 - Moderate, 3 - Low.

Variant 3

Fires an alert when an entity stops reporting location data points for the configured duration.

Property Type Required Constraints Description

conditionType string Yes one of: locationHeartbeat The discriminator for the condition type. Must be locationHeartbeat.

delay string No Optional. How long the evaluation is delayed after the job is dispatched. Must be a multiple of the job invocation interval. Capped at 10 minutes.

duration string Yes Required. The window in which at least one location data point is expected (e.g. 1min, 10min, 1hour). Must be a positive, non-zero multiple of the job invocation interval. Capped at 10 minutes.

frequency string No Optional. How often the condition is evaluated (e.g. 1min). Must be a multiple of the job invocation interval. Capped at 10 minutes.

locationCondition object Yes The location data source on which the heartbeat is monitored.

Property Type Required Constraints Description

entityClass string Yes The entity class whose location is monitored.

entityTargetCondition object No Optional. Constraint on which entities the condition applies to. When omitted, the condition applies to the entity that owns the alert rule.

Properties of entityTargetCondition
Property	Type	Required	Constraints
`entityIds`	array<string>	Yes	min items: 1; max items: 100
`exclude`	boolean	No
`targetBy`	string	Yes	one of: parents, entities

severity integer Yes one of: 1, 2, 3 The severity emitted when the heartbeat is missed. 1 - High, 2 - Moderate, 3 - Low.

Variant 4

Evaluates geofence-based metric conditions on tracked entities.

Property Type Required Constraints Description

conditionType string Yes one of: geofence The discriminator for the condition type. Must be geofence.

delay string No Optional. How long the evaluation is delayed after the job is dispatched. Must be a multiple of the job invocation interval. Capped at 10 minutes. Note (Alerting V2): this field is not used by evaluation scheduling; the server silently replaces invalid values with 0sec.

duration string Yes Required. The time range over which the condition is evaluated (e.g. 1min). Must be a positive, non-zero multiple of the job invocation interval. Capped at 30 minutes.

geofenceAlertType string Yes one of: inOnly, inAndOut Whether to alert only when entering the geofence, or for both enter and exit transitions.

geofenceEntityIds array<string> No Required when geofenceAlertType=inAndOut. The ordered list of geofence area entity IDs that define the zones. Validation requires at least one entry. The length of this list also determines the required dimensions of geofenceSeverityMatrix (rows and columns = len + 1, including the "outside" zone).

geofenceExcludingEntityClasses array<string> No Optional. Used only when geofenceAlertType=inOnly. Entity classes whose areas suppress evaluation when a tracked entity is inside them. Must not contain geofenceTargetEntities.entityClass or any entity class listed in geofenceInOnlyConditions.

geofenceExcludingEntityIds array<string> No Optional. Geofence entity IDs to exclude from evaluation.

geofenceInOnlyConditions array<object> No Optional in the schema, but required when geofenceAlertType=inOnly (validation will reject the rule otherwise). Per-entity-class conditions evaluated on geofence entry. entityClass must differ from geofenceTargetEntities.entityClass, severities must be unique across this array, and classes listed here must not appear in geofenceExcludingEntityClasses.

Property Type Required Constraints Description

entityClass string Yes

metricsConditions array<object> No

Properties of metricsConditions
Property	Type	Required
`metricName`	string	Yes
`metricsDefinitionId`	string	Yes
`threshold`	one of 3	Yes
Nested structure continues below this depth.

severity integer Yes one of: 1, 2, 3

geofenceSeverityMatrix array<array> No Required when geofenceAlertType=inAndOut. A square severity matrix representing transitions between zones (including an implicit "outside" zone). Must have exactly (length of geofenceEntityIds) + 1 rows and the same number of columns. matrix[from][to] gives the severity (0 - None, 1 - High, 2 - Moderate, 3 - Low) for transitioning from zone from to zone to, where index 0 represents outside. Ignored when geofenceAlertType=inOnly.

geofenceTargetEntities object Yes Specifies the entities whose locations are tracked and evaluated against the geofences.

Properties of geofenceTargetEntities
Property	Type	Required	Description
`entityClass`	string	Yes	The entity class of the geofence entities.
`entityIds`	array<string>	No	Optional. Specific entity IDs to evaluate. Each ID must be a descendant of the alert rule's owning entity. When omitted, all entities of `entityClass` under `parentEntityId` are evaluated; if `parentEntityId` is also omitted, all entities of `entityClass` under the alert rule's owning entity are evaluated.
`parentEntityId`	string	No	Optional. Restricts geofence target entity resolution to descendants of this entity. Must be a descendant of the alert rule's owning entity. When omitted, target entities are resolved under the alert rule's owning entity.

metricsConditionOperator string No one of: and, or Optional. Logical operator combining metricsConditions. Required when metricsConditions is non-empty. Ignored when metricsConditions is empty or absent.

metricsConditions array<object> No Optional. Per-metric threshold conditions evaluated against tracked entities. When present, metricsConditionOperator must also be set.

Property Type Required Constraints Description

entityClass string No Optional. The entity class to evaluate the metric against. When omitted, defaults to geofenceTargetEntities.entityClass.

entityId string No Optional. Scopes the metric evaluation to a specific entity. The entity must be a descendant of the alert rule's owning entity. When omitted, the metric is evaluated against any matching entity of entityClass.

metricName string Yes The name of the metric inside the metrics definition.

metricsDefinitionId string Yes The identifier of the metrics definition.

threshold one of 3 Yes The threshold the metric value is compared against.

Properties of threshold
Property	Type	Required	Constraints	Description
`operands`	array<number>	Yes		Operand values for the operator. Single value for `greaterThan`/`lessThan`/etc., two values for `between`/`outside` (with `operands[0] < operands[1]`), list for `in`/`notIn`.
`operator`	string	Yes	one of: greaterThan, greaterThanOrEqualTo, lessThanOrEqualTo, lessThan, between, outside, in, notIn

One of the following 3 shapes:

Variant 1

Property	Type	Required	Constraints	Description
`operands`	unknown	No	min items: 1; max items: 1
`operator`	unknown	No	one of: greaterThan, greaterThanOrEqualTo, lessThanOrEqualTo, lessThan

Variant 2

Property	Type	Required	Constraints	Description
`operands`	unknown	No	min items: 2; max items: 2
`operator`	unknown	No	one of: between, outside

Variant 3

Property	Type	Required	Constraints	Description
`operands`	unknown	No	min items: 1; max items: 1000
`operator`	unknown	No	one of: in, notIn

whenLocationIsMissing string No one of: skipEvaluation, setFromAsOutsideOnly, setBothAsOutside Optional. How to treat tracked entities with no recent location data. Defaults to skipEvaluation when omitted.

description string No The description of the alert

entityID string No The unique identifier for the entity the alert rule belongs to

entityTuple array<string> No For a composite metrics-threshold alert only: the entity ID filling each condition slot, ordered by condition index, so tuples can be told apart. Absent for non-composite alerts.

entityType string No The class of the entity

homeId integer No The unique identifier for the home the alert rule belongs to

id string No The unique identifier for the alert

invocationTime string No The time the alert was triggered

metricName string No The name of the metric in which the alert is invoked

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

projectId integer No The unique identifier for the project the alert rule belongs to

recoveryTime string No The time the alert was recovered

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

state integer No 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)

videoFeedFiles array<object> No List of video feed files associated with the alert

Properties of videoFeedFiles
Property	Type	Required	Description
`entityId`	string	No	The identifier of the corresponded entity
`fileId`	string	No	The unique identifier of the file
`videoFeedId`	string	No	The identifier the corresponded video feed

Response example

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

`401` Authorization is required to access this resource.

Content type: application/json

Property	Type	Required	Constraints	Description
`data`	object	No	read-only (server-generated)	Any relevant data related to error.
`reason`	string	Yes	read-only (server-generated)	Reason of error.

`403` Request failed because of denied permission.

Content type: application/json

Property	Type	Required	Constraints	Description
`data`	object	No	read-only (server-generated)	Any relevant data related to error.
`reason`	string	Yes	read-only (server-generated)	Reason of error.

`429` Request failed because of rate limit.

Content type: application/json

Property	Type	Required	Constraints	Description
`data`	object	No	read-only (server-generated)	Any relevant data related to error.
`reason`	string	Yes	read-only (server-generated)	Reason of error.

`500` An unexpected error has occurred.

Content type: application/json

Property	Type	Required	Constraints	Description
`data`	object	No	read-only (server-generated)	Any relevant data related to error.
`reason`	string	Yes	read-only (server-generated)	Reason of error.

`503` The service is temporarily unavailable.

Content type: application/json

Property	Type	Required	Constraints	Description
`data`	object	No	read-only (server-generated)	Any relevant data related to error.
`reason`	string	Yes	read-only (server-generated)	Reason of error.

Get alerts

Authentication

Query parameters

Responses

200 Successful retrieval of alerts.

Response example

401 Authorization is required to access this resource.

403 Request failed because of denied permission.

429 Request failed because of rate limit.

500 An unexpected error has occurred.

503 The service is temporarily unavailable.

`200` Successful retrieval of alerts.

`401` Authorization is required to access this resource.

`403` Request failed because of denied permission.

`429` Request failed because of rate limit.

`500` An unexpected error has occurred.

`503` The service is temporarily unavailable.