Skip to content

Query alert

GET /alert/<alertKs>?fields=...&actions=...

Description

Query alert details. This API call will work for both an open and closed alert.

Path parameters

Param Description
alertKs Alert key string (ks).

Query parameters

Param Default Description
fields all fields Fields to return (see Fields below for all available fields).
actions none Action fields. If at least one field is given, the result will include "actions" with an array of action objects (see Actions below for all available action fields).
condition none Condition fields. If at least one field is given, the result will include "condition" with a condtion object (see Condition below for all available condition fields).

Fields

Field Return type Description
ks string Key string of the alert.
status string Current lifecycle state of the alert. See Alert Status Values for details.
message string Initial message when the alert was opened.
severity integer Initial severity when the alert was opened (value between 0=highest and 7=lowest severity).
timestamp integer Unix timestamp in seconds when the alert was opened.
lastMessage string Message of the last hit (equal to "message" with only a single hit).
lastSeverity integer Severity of the last hit (equal to "severity" with only a single hit).
lastTimestamp integer Unix timestamp in seconds of the last hit (equal to "timestamp" with only a single hit).
ownerId integer/null User Id of the owner or null when the alert is not assigned to an owner.
assetId integer Id of the associated asset.
item string Name of the associated item.
closedTimestamp integer/null Unix timestamp in seconds when the alert was closed or null if not closed.
solution string/null Resolution note provided when an alert is closed. Only populated if the alert has status Closed and was marked with a solution; otherwise null.

Alert Status Values

Status State Description
Open Open The alert is open and currently unassigned.
Assigned Open The alert is open and assigned to a user (ownerId is populated).
Closed Closed The alert was manually closed by a user.
AutoClosed Closed The alert was automatically closed because a subsequent evaluation of the condition returned an OK state.
IndirectClosed Closed The alert was closed because the underlying condition is no longer evaluated (e.g., condition removed, check disabled, or unassigned from asset).

Actions

Action field Return type Description
kind string One of: Assign, Comment, IntegrationCall, Close, AutoClose, IndirectClose, SeverityChanged
timestamp integer Unix timestamp in seconds.
data object/null Additional data object.

Condition

Condition field Return type Description
id integer Condition Id.
name string Condition name.
collector string Collector key.
check string Check key.
type string Type key.
kind string One of ItemExpression, ItemMissing, ItemsMustExist.
description string Condition description.
labels array(integer) List with label Ids.
ownerId integer Container Id where the condition is created.
masterId integer/null Condition Id of the master condition if this is a linked condition; otherwise null. A linked condition overrides specific fields of its master condition and replaces it during evaluation.
expression string/null Evaluation expression. Applicable when kind is ItemExpression or ItemMissing.
singleAlert boolean Gathers up all alerts into a single alert per asset. When false, each item will creates its own alert. Default: false.
closeOnReturn boolean/null Automatically closes the alert when a previously missing item reappears. Only applicable when kind is ItemMissing. Default: false.
ticks integer/null Number of consecutive matching polls required before an alert is raised (0 triggers immediately). Not applicable when kind is ItemMissing. Default: 0.
severity integer/null Alert severity level assigned when triggered. Only applicable when kind is ItemsMustExist.
ignoreCase boolean/null Enables case-insensitive matching for item names. Only applicable when kind is ItemsMustExist. Default: false.
itemsRe string/null Regular expression pattern for matching items. Only applicable when kind is ItemsMustExist.
itemsList array(string)/null Explicit list of item names to match. Only applicable when kind is ItemsMustExist.

Return codes

Error code Reason
200 Success.
400 Unknown field or action or invalid alert key string.
401 Invalid or missing token.
403 Insufficient permissions (required: API+READ).
404 Alert not found.

Example

Curl request:

curl \
    -X GET 'https://api.infrasonar.com/alert/xxx?actions=kind,timestamp,data' \
    -H 'Authorization: Bearer XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'

Response:

{
    "ks": "<a-unique-key-string>",
    "message": "Initial message of the alert",
    "severity": 3,
    "timestamp": 1667511262,
    "lastMessage": "Last message of the alert",
    "lastSeverity": 3,
    "lastTimestamp": 1667511523,
    "ownerId": 123,
    "closedTimestamp": null,
    "actions": [
        {
            "kind": "Assign",
            "timestamp": 1667511469,
            "data": {
                "userId": 123,
                "ownerId": 123,
                "message": "Alert assigned to me!"
            }
        }
    ]
}