Spectate API

Problems Spectate or an alert source detected. An alert escalates along its escalation path until someone acknowledges it, and resolves on its own when the problem is over, or when someone resolves it by hand. Resolved alerts can be deleted. Alerts can lead to incidents.


List alerts

GET
https://api.spectate.net/v1
/alerts

Returns the team's alerts, most recently fired first unless you sort.

List alerts › query Parameters

page
​integer

Page number, from 1.

Default: 1
per_page
​integer

Alerts per page, 1 to 100.

Default: 25
filter[status]
​AlertStatus · enum

Only firing or resolved alerts.

Whether an alert's problem is ongoing.

firing
The problem is ongoing; it escalates until acknowledged.
resolved
The problem is over.
Enum values:
firing
resolved
filter[severity]
​Severity · enum

Only alerts of this severity.

How urgent an alert or incident is. Escalation paths can branch on it.

critical
Customers are affected right now.
high
Serious, needs attention soon.
medium
Should be looked at.
low
Informational.
Enum values:
critical
high
medium
low
filter[source_type]
​AlertSourceType · enum

Only alerts raised by this kind of check or integration.

What raised an alert.

uptime
A monitor went down.
certificate
A monitor's certificate is invalid or expires soon.
performance
A monitor got slow.
dns
The answer of a DNS monitor changed (when it alerts on changes), or a nameserver has a problem that leaves its monitor up.
host_metric
A host's metric condition held, or it stopped sending data.
domain
A domain expires soon, expired or its registration changed.
external
An alert source (external tool) fired it.
status_page
Visitor issue reports over the threshold or a traffic spike (metadata.type: issue_reports, traffic_spike).
manual
Someone paged by hand, with nothing else to attach it to.
Enum values:
uptime
certificate
performance
dns
host_metric
domain
external
status_page
filter[resource_id]
​string · uuid

Only alerts about this resource (a monitor, host, domain, status page or alert source ID).

filter[acknowledged]
​boolean

Only acknowledged (true) or unacknowledged (false) alerts.

sort
​string

Sort by fired_at, resolved_at, severity or status. Prefix - for descending. Default -fired_at.

List alerts › Responses

Paginated set of Alert

current_page
​integer · min: 1 · required
​Alert[] · required
first_page_url
​string | null · required
from
​integer | null · min: 1 · required
last_page_url
​string | null · required
last_page
​integer · min: 1 · required
​object[] · required

Generated paginator links.

next_page_url
​string | null · required
path
​string | null · required

Base path for paginator generated URLs.

per_page
​integer · min: 0 · required

Number of items shown per page.

prev_page_url
​string | null · required
to
​integer | null · min: 1 · required

Number of the last item in the slice.

total
​integer · min: 0 · required

Total number of items being paginated.


Get an alert

GET
https://api.spectate.net/v1
/alerts/{alert}

Returns the alert with the resource it's about and who acknowledged it.

Get an alert › path Parameters

alert
​string · uuid · required

Alert ID.

Get an alert › Responses

The alert.

An alert: a problem a monitor, host, domain, status page or alert source detected. It escalates along its escalation path until someone acknowledges it, and resolves when the problem is over.
id
​string · uuid · required

Alert ID

title
​string · required

What's wrong

Example: Website is down
description
​string | null · required

More about it, as the source described it

status
​AlertStatus · enum · required

Whether the problem is ongoing

firing
The problem is ongoing; it escalates until acknowledged.
resolved
The problem is over.
Enum values:
firing
resolved
severity
​Severity · enum · required

How urgent it is

critical
Customers are affected right now.
high
Serious, needs attention soon.
medium
Should be looked at.
low
Informational.
Enum values:
critical
high
medium
low
source_type
​AlertSourceType · enum · required

What raised it

uptime
A monitor went down.
certificate
A monitor's certificate is invalid or expires soon.
performance
A monitor got slow.
dns
The answer of a DNS monitor changed (when it alerts on changes), or a nameserver has a problem that leaves its monitor up.
host_metric
A host's metric condition held, or it stopped sending data.
domain
A domain expires soon, expired or its registration changed.
external
An alert source (external tool) fired it.
status_page
Visitor issue reports over the threshold or a traffic spike (metadata.type: issue_reports, traffic_spike).
manual
Someone paged by hand, with nothing else to attach it to.
Enum values:
uptime
certificate
performance
dns
host_metric
domain
external
status_page
​required
fired_at
​string · date-time · required

When it fired

acknowledged_at
​string | null · date-time · required

When it was acknowledged, which stopped its escalation; null while unacknowledged

acknowledged_by
​string | null · required

Who acknowledged it: a member's name, an API token, or how (for example a phone call)

Example: Jane Doe
recovering_since
​string | null · date-time · required

When the monitor came back up. The alert stays firing for the team's recovery wait and resolves when the monitor stays up; null at any other time

group_leader_id
​string | null · uuid · required

The alert that escalates for this one, when they're grouped; null when it escalates by itself

snoozed_until
​string | null · date-time · required

Until when someone snoozed it; null when it isn't snoozed. It counts as acknowledged until then

muted_at
​string | null · date-time · required

When maintenance muted it, so it pages nobody until the window ends; null when it isn't muted

resolved_at
​string | null · date-time · required

When it resolved; null while firing

resolved_by
​string | null · required

Who resolved it by hand: a member's name or an API token. null while firing, and when it resolved on its own because the problem was over

Example: Jane Doe
​object | null · required

Labels the source sent (Prometheus, Grafana); null when it sent none

​AlertLink[] · required

Links the source sent along


Delete an alert

DELETE
https://api.spectate.net/v1
/alerts/{alert}

Deletes a resolved alert for good, with its escalation history. Incidents and status page incidents it led to stay, without the link to it; messages already posted in Slack or Telegram stay in their channels. A firing alert can't be deleted: resolve it first.

Delete an alert › path Parameters

alert
​string · uuid · required

Alert ID.

Delete an alert › Responses

No content

No data returned

Acknowledge an alert

POST
https://api.spectate.net/v1
/alerts/{alert}/acknowledge

Stops its escalation: nobody else is notified. The alert keeps firing until the problem is over. The dashboard, Slack and Telegram show it as acknowledged by the API token. Acknowledging an acknowledged or resolved alert changes nothing.

Acknowledge an alert › path Parameters

alert
​string · uuid · required

Alert ID.

Acknowledge an alert › Responses

The acknowledged alert.

An alert: a problem a monitor, host, domain, status page or alert source detected. It escalates along its escalation path until someone acknowledges it, and resolves when the problem is over.
id
​string · uuid · required

Alert ID

title
​string · required

What's wrong

Example: Website is down
description
​string | null · required

More about it, as the source described it

status
​AlertStatus · enum · required

Whether the problem is ongoing

firing
The problem is ongoing; it escalates until acknowledged.
resolved
The problem is over.
Enum values:
firing
resolved
severity
​Severity · enum · required

How urgent it is

critical
Customers are affected right now.
high
Serious, needs attention soon.
medium
Should be looked at.
low
Informational.
Enum values:
critical
high
medium
low
source_type
​AlertSourceType · enum · required

What raised it

uptime
A monitor went down.
certificate
A monitor's certificate is invalid or expires soon.
performance
A monitor got slow.
dns
The answer of a DNS monitor changed (when it alerts on changes), or a nameserver has a problem that leaves its monitor up.
host_metric
A host's metric condition held, or it stopped sending data.
domain
A domain expires soon, expired or its registration changed.
external
An alert source (external tool) fired it.
status_page
Visitor issue reports over the threshold or a traffic spike (metadata.type: issue_reports, traffic_spike).
manual
Someone paged by hand, with nothing else to attach it to.
Enum values:
uptime
certificate
performance
dns
host_metric
domain
external
status_page
​required
fired_at
​string · date-time · required

When it fired

acknowledged_at
​string | null · date-time · required

When it was acknowledged, which stopped its escalation; null while unacknowledged

acknowledged_by
​string | null · required

Who acknowledged it: a member's name, an API token, or how (for example a phone call)

Example: Jane Doe
recovering_since
​string | null · date-time · required

When the monitor came back up. The alert stays firing for the team's recovery wait and resolves when the monitor stays up; null at any other time

group_leader_id
​string | null · uuid · required

The alert that escalates for this one, when they're grouped; null when it escalates by itself

snoozed_until
​string | null · date-time · required

Until when someone snoozed it; null when it isn't snoozed. It counts as acknowledged until then

muted_at
​string | null · date-time · required

When maintenance muted it, so it pages nobody until the window ends; null when it isn't muted

resolved_at
​string | null · date-time · required

When it resolved; null while firing

resolved_by
​string | null · required

Who resolved it by hand: a member's name or an API token. null while firing, and when it resolved on its own because the problem was over

Example: Jane Doe
​object | null · required

Labels the source sent (Prometheus, Grafana); null when it sent none

​AlertLink[] · required

Links the source sent along


Escalate a muted alert now

POST
https://api.spectate.net/v1
/alerts/{alert}/escalate-now

Starts its escalation, also while the maintenance window that muted it still runs. An alert that isn't muted doesn't change.

Escalate a muted alert now › path Parameters

alert
​string · uuid · required

Alert ID.

Escalate a muted alert now › Responses

The alert.

An alert: a problem a monitor, host, domain, status page or alert source detected. It escalates along its escalation path until someone acknowledges it, and resolves when the problem is over.
id
​string · uuid · required

Alert ID

title
​string · required

What's wrong

Example: Website is down
description
​string | null · required

More about it, as the source described it

status
​AlertStatus · enum · required

Whether the problem is ongoing

firing
The problem is ongoing; it escalates until acknowledged.
resolved
The problem is over.
Enum values:
firing
resolved
severity
​Severity · enum · required

How urgent it is

critical
Customers are affected right now.
high
Serious, needs attention soon.
medium
Should be looked at.
low
Informational.
Enum values:
critical
high
medium
low
source_type
​AlertSourceType · enum · required

What raised it

uptime
A monitor went down.
certificate
A monitor's certificate is invalid or expires soon.
performance
A monitor got slow.
dns
The answer of a DNS monitor changed (when it alerts on changes), or a nameserver has a problem that leaves its monitor up.
host_metric
A host's metric condition held, or it stopped sending data.
domain
A domain expires soon, expired or its registration changed.
external
An alert source (external tool) fired it.
status_page
Visitor issue reports over the threshold or a traffic spike (metadata.type: issue_reports, traffic_spike).
manual
Someone paged by hand, with nothing else to attach it to.
Enum values:
uptime
certificate
performance
dns
host_metric
domain
external
status_page
​required
fired_at
​string · date-time · required

When it fired

acknowledged_at
​string | null · date-time · required

When it was acknowledged, which stopped its escalation; null while unacknowledged

acknowledged_by
​string | null · required

Who acknowledged it: a member's name, an API token, or how (for example a phone call)

Example: Jane Doe
recovering_since
​string | null · date-time · required

When the monitor came back up. The alert stays firing for the team's recovery wait and resolves when the monitor stays up; null at any other time

group_leader_id
​string | null · uuid · required

The alert that escalates for this one, when they're grouped; null when it escalates by itself

snoozed_until
​string | null · date-time · required

Until when someone snoozed it; null when it isn't snoozed. It counts as acknowledged until then

muted_at
​string | null · date-time · required

When maintenance muted it, so it pages nobody until the window ends; null when it isn't muted

resolved_at
​string | null · date-time · required

When it resolved; null while firing

resolved_by
​string | null · required

Who resolved it by hand: a member's name or an API token. null while firing, and when it resolved on its own because the problem was over

Example: Jane Doe
​object | null · required

Labels the source sent (Prometheus, Grafana); null when it sent none

​AlertLink[] · required

Links the source sent along


Resolve an alert

POST
https://api.spectate.net/v1
/alerts/{alert}/resolve

Ends the alert by hand, as if its problem were over: its escalation stops, the channels and on-call members it notified hear that it resolved, Slack and Telegram show it as resolved by the API token, and status pages automated from an uptime alert show the monitor as recovered. Use it for false alarms, or for alerts whose source can't tell they're over.

If the problem is still there, the source fires a new alert at its next check (a monitor that is still down, a host metric still over its limit). Resolving a resolved alert changes nothing.

Resolve an alert › path Parameters

alert
​string · uuid · required

Alert ID.

Resolve an alert › Responses

The resolved alert.

An alert: a problem a monitor, host, domain, status page or alert source detected. It escalates along its escalation path until someone acknowledges it, and resolves when the problem is over.
id
​string · uuid · required

Alert ID

title
​string · required

What's wrong

Example: Website is down
description
​string | null · required

More about it, as the source described it

status
​AlertStatus · enum · required

Whether the problem is ongoing

firing
The problem is ongoing; it escalates until acknowledged.
resolved
The problem is over.
Enum values:
firing
resolved
severity
​Severity · enum · required

How urgent it is

critical
Customers are affected right now.
high
Serious, needs attention soon.
medium
Should be looked at.
low
Informational.
Enum values:
critical
high
medium
low
source_type
​AlertSourceType · enum · required

What raised it

uptime
A monitor went down.
certificate
A monitor's certificate is invalid or expires soon.
performance
A monitor got slow.
dns
The answer of a DNS monitor changed (when it alerts on changes), or a nameserver has a problem that leaves its monitor up.
host_metric
A host's metric condition held, or it stopped sending data.
domain
A domain expires soon, expired or its registration changed.
external
An alert source (external tool) fired it.
status_page
Visitor issue reports over the threshold or a traffic spike (metadata.type: issue_reports, traffic_spike).
manual
Someone paged by hand, with nothing else to attach it to.
Enum values:
uptime
certificate
performance
dns
host_metric
domain
external
status_page
​required
fired_at
​string · date-time · required

When it fired

acknowledged_at
​string | null · date-time · required

When it was acknowledged, which stopped its escalation; null while unacknowledged

acknowledged_by
​string | null · required

Who acknowledged it: a member's name, an API token, or how (for example a phone call)

Example: Jane Doe
recovering_since
​string | null · date-time · required

When the monitor came back up. The alert stays firing for the team's recovery wait and resolves when the monitor stays up; null at any other time

group_leader_id
​string | null · uuid · required

The alert that escalates for this one, when they're grouped; null when it escalates by itself

snoozed_until
​string | null · date-time · required

Until when someone snoozed it; null when it isn't snoozed. It counts as acknowledged until then

muted_at
​string | null · date-time · required

When maintenance muted it, so it pages nobody until the window ends; null when it isn't muted

resolved_at
​string | null · date-time · required

When it resolved; null while firing

resolved_by
​string | null · required

Who resolved it by hand: a member's name or an API token. null while firing, and when it resolved on its own because the problem was over

Example: Jane Doe
​object | null · required

Labels the source sent (Prometheus, Grafana); null when it sent none

​AlertLink[] · required

Links the source sent along


Page someone

POST
https://api.spectate.net/v1
/alerts/page

With nothing to attach it to: creates an alert with source manual, open until someone resolves it or its incident resolves. With an incident_id whose alert still fires, the page goes on that alert instead. Texts and calls use the team's credits.

Page someone › Request Body

A page with nothing to attach it to.
target_type
​AlertPageTarget · enum · required

Who: a member, whoever is on call for a schedule, or an escalation path

member
A team member.
schedule
Whoever is on call for a schedule.
path
An escalation path.
Enum values:
member
schedule
path
target_id
​string · uuid · required

The member's, schedule's or path's ID

title
​string · maxLength: 255 · required

What the page is about, up to 255 characters

Example: The database needs a second pair of eyes
message
​string | null · maxLength: 2000

More detail for the person paged, up to 2000 characters

severity
​Severity · enum

How urgent. Default high

critical
Customers are affected right now.
high
Serious, needs attention soon.
medium
Should be looked at.
low
Informational.
Enum values:
critical
high
medium
low
incident_id
​string | null · uuid

An incident to tie this to: the new alert resolves with it

Page someone › Responses

The alert the page is on.

An alert: a problem a monitor, host, domain, status page or alert source detected. It escalates along its escalation path until someone acknowledges it, and resolves when the problem is over.
id
​string · uuid · required

Alert ID

title
​string · required

What's wrong

Example: Website is down
description
​string | null · required

More about it, as the source described it

status
​AlertStatus · enum · required

Whether the problem is ongoing

firing
The problem is ongoing; it escalates until acknowledged.
resolved
The problem is over.
Enum values:
firing
resolved
severity
​Severity · enum · required

How urgent it is

critical
Customers are affected right now.
high
Serious, needs attention soon.
medium
Should be looked at.
low
Informational.
Enum values:
critical
high
medium
low
source_type
​AlertSourceType · enum · required

What raised it

uptime
A monitor went down.
certificate
A monitor's certificate is invalid or expires soon.
performance
A monitor got slow.
dns
The answer of a DNS monitor changed (when it alerts on changes), or a nameserver has a problem that leaves its monitor up.
host_metric
A host's metric condition held, or it stopped sending data.
domain
A domain expires soon, expired or its registration changed.
external
An alert source (external tool) fired it.
status_page
Visitor issue reports over the threshold or a traffic spike (metadata.type: issue_reports, traffic_spike).
manual
Someone paged by hand, with nothing else to attach it to.
Enum values:
uptime
certificate
performance
dns
host_metric
domain
external
status_page
​required
fired_at
​string · date-time · required

When it fired

acknowledged_at
​string | null · date-time · required

When it was acknowledged, which stopped its escalation; null while unacknowledged

acknowledged_by
​string | null · required

Who acknowledged it: a member's name, an API token, or how (for example a phone call)

Example: Jane Doe
recovering_since
​string | null · date-time · required

When the monitor came back up. The alert stays firing for the team's recovery wait and resolves when the monitor stays up; null at any other time

group_leader_id
​string | null · uuid · required

The alert that escalates for this one, when they're grouped; null when it escalates by itself

snoozed_until
​string | null · date-time · required

Until when someone snoozed it; null when it isn't snoozed. It counts as acknowledged until then

muted_at
​string | null · date-time · required

When maintenance muted it, so it pages nobody until the window ends; null when it isn't muted

resolved_at
​string | null · date-time · required

When it resolved; null while firing

resolved_by
​string | null · required

Who resolved it by hand: a member's name or an API token. null while firing, and when it resolved on its own because the problem was over

Example: Jane Doe
​object | null · required

Labels the source sent (Prometheus, Grafana); null when it sent none

​AlertLink[] · required

Links the source sent along


Page someone about an alert

POST
https://api.spectate.net/v1
/alerts/{alert}/page

Pages a team member, whoever is on call for a schedule, or starts an escalation path, also if the alert is acknowledged. Texts and calls use the team's credits. The target must belong to the team (422 otherwise).

Page someone about an alert › path Parameters

alert
​string · uuid · required

Alert ID.

Page someone about an alert › Request Body

Who to page about an alert.
target_type
​AlertPageTarget · enum · required

Who: a member, whoever is on call for a schedule, or an escalation path

member
A team member.
schedule
Whoever is on call for a schedule.
path
An escalation path.
Enum values:
member
schedule
path
target_id
​string · uuid · required

The member's, schedule's or path's ID

Page someone about an alert › Responses

The alert.

An alert: a problem a monitor, host, domain, status page or alert source detected. It escalates along its escalation path until someone acknowledges it, and resolves when the problem is over.
id
​string · uuid · required

Alert ID

title
​string · required

What's wrong

Example: Website is down
description
​string | null · required

More about it, as the source described it

status
​AlertStatus · enum · required

Whether the problem is ongoing

firing
The problem is ongoing; it escalates until acknowledged.
resolved
The problem is over.
Enum values:
firing
resolved
severity
​Severity · enum · required

How urgent it is

critical
Customers are affected right now.
high
Serious, needs attention soon.
medium
Should be looked at.
low
Informational.
Enum values:
critical
high
medium
low
source_type
​AlertSourceType · enum · required

What raised it

uptime
A monitor went down.
certificate
A monitor's certificate is invalid or expires soon.
performance
A monitor got slow.
dns
The answer of a DNS monitor changed (when it alerts on changes), or a nameserver has a problem that leaves its monitor up.
host_metric
A host's metric condition held, or it stopped sending data.
domain
A domain expires soon, expired or its registration changed.
external
An alert source (external tool) fired it.
status_page
Visitor issue reports over the threshold or a traffic spike (metadata.type: issue_reports, traffic_spike).
manual
Someone paged by hand, with nothing else to attach it to.
Enum values:
uptime
certificate
performance
dns
host_metric
domain
external
status_page
​required
fired_at
​string · date-time · required

When it fired

acknowledged_at
​string | null · date-time · required

When it was acknowledged, which stopped its escalation; null while unacknowledged

acknowledged_by
​string | null · required

Who acknowledged it: a member's name, an API token, or how (for example a phone call)

Example: Jane Doe
recovering_since
​string | null · date-time · required

When the monitor came back up. The alert stays firing for the team's recovery wait and resolves when the monitor stays up; null at any other time

group_leader_id
​string | null · uuid · required

The alert that escalates for this one, when they're grouped; null when it escalates by itself

snoozed_until
​string | null · date-time · required

Until when someone snoozed it; null when it isn't snoozed. It counts as acknowledged until then

muted_at
​string | null · date-time · required

When maintenance muted it, so it pages nobody until the window ends; null when it isn't muted

resolved_at
​string | null · date-time · required

When it resolved; null while firing

resolved_by
​string | null · required

Who resolved it by hand: a member's name or an API token. null while firing, and when it resolved on its own because the problem was over

Example: Jane Doe
​object | null · required

Labels the source sent (Prometheus, Grafana); null when it sent none

​AlertLink[] · required

Links the source sent along


Snooze an alert

POST
https://api.spectate.net/v1
/alerts/{alert}/snooze

Pauses its escalation for 15 minutes to 24 hours. It counts as acknowledged until then; if it still fires then, the escalation starts again from the first step. Resolving ends it. A resolved alert can't be snoozed (422).

Snooze an alert › path Parameters

alert
​string · uuid · required

Alert ID.

Snooze an alert › Request Body

How long to snooze an alert.
minutes
​integer · min: 15 · max: 1440 · required

How long in minutes, 15 to 1440

Example: 60
reason
​string | null · maxLength: 500

Why, for the team; up to 500 characters

Snooze an alert › Responses

The snoozed alert.

An alert: a problem a monitor, host, domain, status page or alert source detected. It escalates along its escalation path until someone acknowledges it, and resolves when the problem is over.
id
​string · uuid · required

Alert ID

title
​string · required

What's wrong

Example: Website is down
description
​string | null · required

More about it, as the source described it

status
​AlertStatus · enum · required

Whether the problem is ongoing

firing
The problem is ongoing; it escalates until acknowledged.
resolved
The problem is over.
Enum values:
firing
resolved
severity
​Severity · enum · required

How urgent it is

critical
Customers are affected right now.
high
Serious, needs attention soon.
medium
Should be looked at.
low
Informational.
Enum values:
critical
high
medium
low
source_type
​AlertSourceType · enum · required

What raised it

uptime
A monitor went down.
certificate
A monitor's certificate is invalid or expires soon.
performance
A monitor got slow.
dns
The answer of a DNS monitor changed (when it alerts on changes), or a nameserver has a problem that leaves its monitor up.
host_metric
A host's metric condition held, or it stopped sending data.
domain
A domain expires soon, expired or its registration changed.
external
An alert source (external tool) fired it.
status_page
Visitor issue reports over the threshold or a traffic spike (metadata.type: issue_reports, traffic_spike).
manual
Someone paged by hand, with nothing else to attach it to.
Enum values:
uptime
certificate
performance
dns
host_metric
domain
external
status_page
​required
fired_at
​string · date-time · required

When it fired

acknowledged_at
​string | null · date-time · required

When it was acknowledged, which stopped its escalation; null while unacknowledged

acknowledged_by
​string | null · required

Who acknowledged it: a member's name, an API token, or how (for example a phone call)

Example: Jane Doe
recovering_since
​string | null · date-time · required

When the monitor came back up. The alert stays firing for the team's recovery wait and resolves when the monitor stays up; null at any other time

group_leader_id
​string | null · uuid · required

The alert that escalates for this one, when they're grouped; null when it escalates by itself

snoozed_until
​string | null · date-time · required

Until when someone snoozed it; null when it isn't snoozed. It counts as acknowledged until then

muted_at
​string | null · date-time · required

When maintenance muted it, so it pages nobody until the window ends; null when it isn't muted

resolved_at
​string | null · date-time · required

When it resolved; null while firing

resolved_by
​string | null · required

Who resolved it by hand: a member's name or an API token. null while firing, and when it resolved on its own because the problem was over

Example: Jane Doe
​object | null · required

Labels the source sent (Prometheus, Grafana); null when it sent none

​AlertLink[] · required

Links the source sent along