Get alert rules

GET/alertRules

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

Get a list of alert rules.

Authentication

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

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

Query parameters

Name	Type	Required	Constraints	Description
`conditionType`	string	No		Return alert rules of the specified condition type.
`enabled`	boolean	No		Return alert rules with the specified enabled state.
`entityId`	string	No		Return alert rules 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 filter also matches alert rules attached to its descendants. Defaults to false.
`limit`	integer	No	default: 25; min: 1	Maximum number of alert rules to return.
`projectId`	integer	Yes		Return alert rules of the specified project.
`scheduleId`	string	No		Return alert rules with the specified schedule.
`skip`	integer	No	default: 0; min: 0	Number of alert rules to skip over.

Responses

`200` Successfully retrieved the alert rules.

Content type: application/json

Represents an alert rule

An array of objects with the following shape:

Property Type Required Constraints Description

actions array<object> No The actions to take when the alert rule is triggered

Property Type Required Constraints Description

recipients array<one of 5> No Optional. Recipients that will be notified when this action runs. Each recipient is discriminated by its recipientType. Maximum 10 recipients. Assistant recipients (slack, direct, msTeams) must belong to the same project and entity as the alert rule.

One of the following 5 shapes:

Variant 1

Sends the alert notification to an email address.

Property	Type	Required	Constraints	Description
`email`	string	Yes		The destination email address.
`recipientType`	string	Yes	one of: email

Variant 2

Emits an event of eventType into the project event stream.

Property	Type	Required	Constraints	Description
`eventType`	string	Yes		The event type to emit.
`recipientType`	string	Yes	one of: event

Variant 3

Sends the alert notification to a Slack channel via an assistant.

Property	Type	Required	Constraints	Description
`assistantId`	integer	Yes		Identifier of the Slack assistant.
`channelId`	string	Yes		Slack channel identifier.
`recipientType`	string	Yes	one of: slack
`workspaceId`	string	Yes		Slack workspace identifier.

Variant 4

Sends the alert notification to a Direct chat room via an assistant.

Property	Type	Required	Constraints	Description
`assistantId`	integer	Yes		Identifier of the Direct assistant.
`domainId`	string	Yes		Direct domain identifier.
`recipientType`	string	Yes	one of: direct
`roomId`	string	Yes		Direct room identifier.

Variant 5

Sends the alert notification to a Microsoft Teams channel via an assistant.

Property	Type	Required	Constraints	Description
`assistantId`	integer	Yes		Identifier of the Microsoft Teams assistant.
`channelId`	string	Yes		Microsoft Teams channel identifier.
`recipientType`	string	Yes	one of: msTeams
`teamId`	string	Yes		Microsoft Teams team identifier.
`tenantId`	string	Yes		Microsoft Teams tenant identifier.

videoFeeds array<object> No Optional. Video feed snapshots to capture and attach to the alert notification when the rule fires. When omitted, no snapshots are captured. Whether/how a given recipient renders the attachment depends on that recipient's channel.

Properties of videoFeeds
Property	Type	Required	Constraints	Description
`entityId`	string	Yes		Entity owning the video feed. Supports the `{{triggeredEntityId}}` template placeholder to refer to the entity that triggered the alert.
`videoFeedId`	string	No		Optional. Specific video feed identifier. When omitted, all video feeds of the entity are used.

condition one of 5 No The condition that triggers the alert rule. The shape is discriminated by conditionType.

One of the following 5 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

Evaluates several metric conditions together and alerts only when all of them breach at the same severity. Each condition watches its own entity and metric; which entity fills which condition is given explicitly by entityTuples, one tuple per monitored installation. Alerting V2 only, and event-driven only: there is no scheduled evaluation for this condition type, so it has no frequency or delay.

Property Type Required Constraints Description

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

conditions array<object> Yes min items: 2; max items: 10 The AND-ed conditions. Order is significant: a condition's position is its identity, referenced by entityTuples[].entities and by the conditionN message template aliases, so reordering conditions changes the meaning of both. Every condition must define the same set of threshold severities, because the composite severity is the highest severity at which all conditions breach. Two conditions may share, or fully duplicate, the same entityClass + metricsDefinitionId + metricName; the entity binding comes from the tuple, not the condition.

Property Type Required Constraints Description

aggregation string Yes one of: avg, min, max, sum, count The aggregation function applied to this condition's metric over its duration.

duration string Yes Required. The time range over which this condition's data points are aggregated (e.g. 1min, 10min). Must be positive and non-zero, capped at 1 day. Each condition has its own duration.

entityClass string Yes The entity class that owns the metric. Every entity bound to this condition's slot must be of this class.

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 for this condition. Duplicate severities are not allowed, and the set of severities must be identical across every condition of the rule.

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

entityTuples array<object> Yes min items: 1; max items: 100 The explicit entity mappings, one per monitored installation. Each tuple says which real entity fills each condition slot. Tuples are never inferred from entity hierarchy or scope, because that mapping is business knowledge the platform cannot guess. Two tuples of one rule alert independently. Duplicate mappings are rejected.

Properties of entityTuples
Property	Type	Required	Constraints	Description
`entities`	array<string>	Yes	min items: 2; max items: 10	The entity IDs filling each condition slot, positionally aligned with `conditions`: `entities[i]` is evaluated against `conditions[i]`. The length must equal the number of conditions, and each entity must be of its condition's `entityClass` and must be the alert rule's entity or one of its descendants. The same entity may appear in more than one slot.

Variant 3

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 4

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 5

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.

creationTime string No The time the alert rule was created

description string No The description of the alert rule

disableAutoRecovery boolean No Whether alert based on this rule recover automatically

disableRecoveryAlert boolean No Whether a notification will be sent when an alert recovers

enabled boolean No Whether the alert rule is enabled

id integer No The unique identifier for the alert rule

messageTemplate object No Templates used to render the notification title and message for the different alert state transitions. Template variables are referenced with {{name}} syntax. Supported variables: projectId, alertId, alertRuleId, alertRuleName, entityId, entityName, severity, invocationTime, invocationValue, currentValue.

Property Type Required Constraints Description

decreasedSeverityMessage string No Optional. Message body used when an alert's severity decreases. Max 2000 runes. When omitted, defaults to [{{alertRuleName}}] {{entityName}} severity decreased to {{severity}}.

decreasedSeverityTitle string No Optional. Title used when an alert's severity decreases. Max 200 runes. When omitted, defaults to [{{alertRuleName}}] {{entityName}} severity decreased.

increasedSeverityMessage string No Optional. Message body used when an alert's severity increases. Max 2000 runes. When omitted, defaults to [{{alertRuleName}}] {{entityName}} severity increased to {{severity}}.

increasedSeverityTitle string No Optional. Title used when an alert's severity increases. Max 200 runes. When omitted, defaults to [{{alertRuleName}}] {{entityName}} severity increased.

message string No Optional. Message body used when an alert is initially fired. Max 2000 runes. When omitted, defaults to a link back to the alert detail page in the BizStack console.

recoveryMessage string No Optional. Message body used when an alert recovers. Max 2000 runes. When omitted, defaults to a link back to the alert detail page in the BizStack console.

recoveryTitle string No Optional. Title used when an alert recovers. Max 200 runes. When omitted, defaults to [{{alertRuleName}}] {{entityName}} is back to normal.

severityMessageOverrides array<object> No max items: 3 Optional. Per-severity overrides for title, message, recoveryTitle, and recoveryMessage. When an override entry exists for the current severity and the field is non-empty, it takes precedence over the corresponding top-level field. increasedSeverityTitle, increasedSeverityMessage, decreasedSeverityTitle, and decreasedSeverityMessage are NOT overridable per severity. Each severity value must appear at most once.

Properties of severityMessageOverrides
Property	Type	Required	Constraints	Description
`message`	string	No		Optional. Message body override used when an alert fires at this severity. Max 2000 runes.
`recoveryMessage`	string	No		Optional. Message body override used when an alert recovers from this severity. Max 2000 runes.
`recoveryTitle`	string	No		Optional. Title override used when an alert recovers from this severity. Max 200 runes.
`severity`	integer	Yes	one of: 1, 2, 3	The alert severity level this override applies to. 1 = high, 2 = moderate, 3 = low. Must not be 0 (none).
`title`	string	No		Optional. Title override used when an alert fires at this severity. Max 200 runes.

title string Yes Title used when an alert is initially fired. Max 200 runes. Required.

name string No The name of the alert rule

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

reasonForDisabling unknown No read-only (server-generated); one of: unknown, api, invalid_entity, invalid_metric The reason why this alert rule was disabled. Will not be set when the alert rule is enabled

scheduleId string No The schedule ID for the alert rule

updateTime string No The time the alert rule was last updated

`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 alert rules

Authentication

Query parameters

Responses

200 Successfully retrieved the alert rules.

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` Successfully retrieved the alert rules.

`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.