Alerts

Alerts are scoped to a team, so every alerts endpoint lives under a team path. Use these endpoints to read alerts and to acknowledge or close them. To create alerts, see Send Alerts.

Keys with the Read Only role can call the GET endpoints. Keys with the Admin role can call all of them. List endpoints are paginated, see Pagination.

Alert Values

Field	Value	Meaning
status	1	Open
status	2	Acknowledged
status	3	Closed
severity	1	Critical
severity	2	Warning (high)
severity	3	Info (low)

List Alerts

GET /account/{accountId}/team/{teamId}/alert

Required role
Admin or Read Only

Path parameters

Name	Type	Required	Description
accountId	number	Yes	Your account ID.
teamId	number	Yes	The team that owns the alerts.

Query parameters

Name	Type	Required	Description
limit	number	No	Page size. Defaults to 20. Any whole number from 1 to 100. Any other value is treated as 20.
id	number	No	Pagination cursor. Pass the pk.id value from the previous response.
start	number	No	Earliest time to include, in epoch microseconds. Inclusive.
end	number	No	Latest time to include, in epoch microseconds. Inclusive.
order	string	No	asc returns the oldest alerts first. Any other value, or omitting it, returns the newest first.

Response

Status 200.

Name	Type	Description
items	array	Alert summaries, described below.
pk	object	Present only when more results exist. Contains id, the cursor for the next page.

Each item in items is a summary and does not include the description or timeline. Use Get Alert for the full alert.

Name	Type	Description
accountId	number	The account ID.
id	number	The alert ID.
apikeyId	number	ID of the API key that created the alert, or 0 if it was not created with a key.
count	number	How many times the alert has fired, including duplicates.
labels	object	Key-value labels attached to the alert.
owner	string	Who acknowledged or closed the alert. API keys appear as apikey:<keyId>.
severity	number	1, 2, or 3.
status	number	1, 2, or 3.
teamId	number	The team ID.
title	string	The alert title.

Errors

Status	When
400	id, start, or end is not numeric.

Notes

• A page can contain fewer than limit items while pk is still present. Keep requesting pages until pk is absent.
• You can use start and end on their own or together.

Get Alert

GET /account/{accountId}/team/{teamId}/alert/{alertId}

Required role
Admin or Read Only

Path parameters

Name	Type	Required	Description
accountId	number	Yes	Your account ID.
teamId	number	Yes	The team that owns the alert.
alertId	number	Yes	The alert ID.

Response

Status 200.

Name	Type	Description
accountId	number	The account ID.
apikeyId	number	ID of the API key that created the alert, or 0.
id	number	The alert ID.
count	number	How many times the alert has fired, including duplicates.
description	string	The alert description.
escalationTeamId	number	The team the alert was escalated to, if any.
labels	object	Key-value labels attached to the alert.
notifications	array	Notifications sent for the alert. See below.
owner	string	Who acknowledged or closed the alert.
severity	number	1, 2, or 3.
status	number	1, 2, or 3.
teamId	number	The team ID.
timeline	array	Events in the alert’s history. See below.
title	string	The alert title.
ttl	number	When the alert expires, in epoch seconds.

notifications items:

Name	Type	Description
actor	string	Who or what triggered the notification.
time	number	When it was sent, in epoch seconds.
type	string	The notification type.
value	string	The recipient or related value.

timeline items:

Name	Type	Description
actor	string	Who or what caused the event.
time	number	When the event happened, in epoch seconds.
type	string	One of ack, closed, duplicate, email, escalationFrom, escalationTo, muteAck, muteEmail, muteEscalationTo, mutePhone, muteSms, phone, sms.
value	string	The recipient or related value.

Notes

• Labels support up to 50 entries. Keys are 1 to 64 characters and values are 1 to 128 characters.

Acknowledge or Close Alert

PATCH /account/{accountId}/team/{teamId}/alert/{alertId}

Required role
Admin

Path parameters

Name	Type	Required	Description
accountId	number	Yes	Your account ID.
teamId	number	Yes	The team that owns the alert.
alertId	number	Yes	The alert ID.

Request body

Send Content-Type: application/json.

Name	Type	Required	Description
status	number	Yes	2 to acknowledge the alert, 3 to close it.

Response

Status 200 with an empty object.

Errors

Status	When
403	The alert does not belong to the team in the path.
404	The alert does not exist.
409	The alert is already acknowledged or closed, so the change is not allowed.

Notes

• Alerts move forward only: open, then acknowledged, then closed. You cannot acknowledge a closed alert.
• The change adds an entry to the alert’s timeline and sets the alert’s owner to apikey:<keyId>.
• Acknowledging or closing an alert clears its pending notifications.

Not Available on v1

Deleting alerts is not available through the API. Creating alerts is done through Send Alerts.

Related

• Send Alerts
• Teams
• Pagination
• Errors