Spectate
Spectate API
Spectate API

Monitors

Download schema

Uptime monitors check a URL, host, port or DNS name from Spectate's regions every interval, and raise alerts when it goes down, gets slow or its certificate is about to expire. Monitors and hosts together count against the plan's resource limit.

List monitors

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

Returns the team's monitors, newest first unless you sort. Filters combine with AND.

List monitors › query Parameters

page
​integer

Page number, from 1.

Default: 1
per_page
​integer

Monitors per page, 1 to 100.

Default: 25
filter[state]
​MonitorState · enum

Only monitors in this state.

A monitor's state as the dashboard shows it: paused when disabled, otherwise its uptime status.

down
Checks fail: a failed check, repeated from the same region about 5 seconds later, failed again.
pending
Not checked yet.
up
The latest check succeeded.
paused
Disabled by a member or the system.
Enum values:
down
pending
up
paused
filter[uptime_status]
​UptimeStatus · enum

Only monitors with this uptime status, whether paused or not.

Whether a monitor's target answers, from its latest checks.

pending
Not checked yet.
up
The latest check succeeded.
down
Checks fail: a failed check, repeated from the same region about 5 seconds later, failed again.
Enum values:
pending
up
down
filter[protocol]
​MonitorProtocol · enum

Only monitors of this protocol.

What a monitor checks, and so the format of its uri.

https
An HTTPS request to the URL in uri, with a certificate check.
http
An HTTP request to the URL in uri.
icmp
A ping (ICMP echo) to the host in uri.
tcp
A TCP connect to host:port, optionally with a TLS handshake and a banner keyword.
dns
A DNS query for a record of the name in uri, optionally compared with expected values.
smtp
An SMTP greeting from host:port (port optional), with STARTTLS by default.
imap
An IMAP greeting from host:port (port optional), over TLS by default.
pop3
A POP3 greeting from host:port (port optional), over TLS by default.
Enum values:
https
http
icmp
tcp
dns
smtp
imap
pop3
filter[enabled]
​boolean

Only running (true) or paused (false) monitors.

filter[project_id]
​string · uuid

Only monitors of this project.

filter[search]
​string

Case-insensitive text in the label, target, protocol or region.

sort
​string

Sort by label, created_at, last_checked_at or state (down, pending, up, paused, then label). Prefix - for descending. Default -created_at.

List monitors › Responses

Paginated set of Monitor

current_page
​integer · min: 1 · required
​Monitor[] · 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.

Create a monitor

POST
https://api.spectate.net/v1
/monitors

The monitor starts checking at once unless enabled is false. Without project_id it joins the team's default project. Monitors and hosts together are limited by the plan (403 PLAN_LIMIT_REACHED), and so is the shortest interval (422). Targets on private or reserved addresses are refused (422).

Create a monitor › Request Body

A new monitor. Only `label`, `protocol`, `uri` and `interval` are required; everything else has a sensible default.
CreateMonitor
label
​string · maxLength: 255 · required

Name shown in the dashboard, alerts and status pages

Example: Website
protocol
​MonitorProtocol · enum · required

What to check; decides the format of uri

https
An HTTPS request to the URL in uri, with a certificate check.
http
An HTTP request to the URL in uri.
icmp
A ping (ICMP echo) to the host in uri.
tcp
A TCP connect to host:port, optionally with a TLS handshake and a banner keyword.
dns
A DNS query for a record of the name in uri, optionally compared with expected values.
smtp
An SMTP greeting from host:port (port optional), with STARTTLS by default.
imap
An IMAP greeting from host:port (port optional), over TLS by default.
pop3
A POP3 greeting from host:port (port optional), over TLS by default.
Enum values:
https
http
icmp
tcp
dns
smtp
imap
pop3
uri
​string · maxLength: 2048 · required

The target: a URL for http and https, a host for icmp, host:port for tcp, host or host:port for mail, a DNS name for dns. Private and reserved addresses are refused. For http and https the scheme is optional: example.com/health and https://example.com/health give the same monitor, stored without the scheme. A scheme that differs from protocol (http:// for an https monitor) is refused with 422

Example: https://example.com/health
interval
​MonitorInterval · enum · required

Seconds between checks. Plans set the shortest allowed interval (422 below it)

Enum values:
30
60
120
180
300
600
900
1800
enabled
​boolean

Whether the monitor starts running at once. Default true

primary_location
​MonitorLocation · enum

Region the checks run from. Default eu

eu
Europe.
us
North America.
as
Asia.
oc
Oceania.
Enum values:
eu
us
as
oc
timeout
​integer · min: 1 · max: 60

Seconds before a check times out, 1 to 60. Default 30

Example: 30
max_redirects
​integer | null · min: 0 · max: 10

HTTP: redirects to follow, 0 to 10; null follows up to 10

​MonitorHeader[]

HTTP: up to 25 headers to send

​MonitorAdvancedSettingsInput

Protocol-specific settings

allow_insecure_requests
​boolean

HTTPS: accept invalid certificates for the check itself. Default false

expected_http_status_code
​string | null · minLength: 1 · maxLength: 200

HTTP: status codes that count as up, comma-separated, * as a wildcard digit; null accepts 2xx and 3xx

Example: 2**,301
certificate_check_enabled
​boolean

Check the TLS certificate for validity and expiry (HTTPS, and TCP or mail with TLS). Default false

certificate_expiry_threshold_days
​integer · min: 1 · max: 90

Days before the certificate expires that the "expires soon" alert fires, 1 to 90. Default 14

Example: 14
performance_check_enabled
​boolean

Raise alerts for slow responses. Default false

performance_hard_threshold
​integer | null · min: 1 · max: 30000

Milliseconds, 1 to 30000: a response slower than this raises an alert

Example: 2000
performance_deviation_percentage
​integer | null · min: 1 · max: 500

Percent, 1 to 500: alert when recent response times are this much above the earlier ones (see the two timeframes)

Example: 50
performance_deviation_timeframe
​integer | null · min: 15 · max: 120

Minutes of recent checks to compare: 15, 30, 45, 60, 75, 90, 105 or 120. Must be shorter than performance_deviation_before_timeframe

Example: 30
performance_deviation_before_timeframe
​integer | null · min: 60 · max: 1440

Minutes before those to compare with, a whole number of hours from 60 to 1440

Example: 240
regional_performance_enabled
​boolean

Also measure response time from the regions other than primary_location, every minute (or at the interval, when longer). Shown with the monitor's performance; not used for uptime or alerts. Team plan and up. Default false

project_id
​string | null · uuid

Project to add the monitor to; default the team's default project, null for none

escalation_path_ids
​string[]

Escalation paths for the monitor's alerts. Leave out or send [] to follow the project's paths, else the team's default path

Create a monitor › Responses

The new monitor.

A monitor: a check of a URL, host or DNS name from Spectate's regions, with its settings and latest results.
Monitor
id
​string · uuid · required

Monitor ID

label
​string · required

Name shown in the dashboard, alerts and status pages

Example: Website
protocol
​MonitorProtocol · enum · required

What is checked; decides the format of uri

https
An HTTPS request to the URL in uri, with a certificate check.
http
An HTTP request to the URL in uri.
icmp
A ping (ICMP echo) to the host in uri.
tcp
A TCP connect to host:port, optionally with a TLS handshake and a banner keyword.
dns
A DNS query for a record of the name in uri, optionally compared with expected values.
smtp
An SMTP greeting from host:port (port optional), with STARTTLS by default.
imap
An IMAP greeting from host:port (port optional), over TLS by default.
pop3
A POP3 greeting from host:port (port optional), over TLS by default.
Enum values:
https
http
icmp
tcp
dns
smtp
imap
pop3
uri
​string · required

The target as stored: a URL without the scheme for http and https (the protocol is the scheme), a host for icmp, host:port for tcp and mail, a DNS name for dns. url has the full URL

Example: example.com/health
url
​string · required

The target as the dashboard shows it, for example smtp://mail.example.com:587 for SMTP

Example: https://example.com/health
interval
​MonitorInterval · enum · required

Seconds between checks

Enum values:
30
60
120
180
300
600
900
1800
primary_location
​MonitorLocation · enum · required

Region the checks run from; a failed check is repeated from the same region about 5 seconds later before the monitor goes down

eu
Europe.
us
North America.
as
Asia.
oc
Oceania.
Enum values:
eu
us
as
oc
timeout
​integer · required

Seconds before a check times out

Example: 30
max_redirects
​integer | null · required

HTTP: redirects followed before the check fails; null follows up to 10

​MonitorHeader[] · required

HTTP: headers sent with every check

​MonitorAdvancedSettings · required

Protocol-specific settings

enabled
​boolean · required

Whether the monitor runs. false when paused by a member or by the system (see paused_reason)

​required
allow_insecure_requests
​boolean · required

HTTPS: whether invalid certificates are accepted for the check itself (the certificate check still reports them)

expected_http_status_code
​string | null · required

HTTP: status codes that count as up, comma-separated, * as a wildcard digit (2**,301); null accepts 2xx and 3xx

Example: 2**,301
certificate_check_enabled
​boolean · required

Whether the TLS certificate is checked for validity and expiry

certificate_expiry_threshold_days
​integer · required

Days before the certificate expires that the "expires soon" alert fires

Example: 14
uses_tls
​boolean · required

Whether a check reports a certificate: HTTPS, and TCP or mail with TLS

​required
certificate_expires_at
​string | null · date-time · required

When the certificate expires

certificate_valid_from
​string | null · date-time · required

When the certificate became valid

certificate_issuer
​string | null · required

Who issued the certificate

Example: R11
certificate_error
​string | null · required

Why the certificate isn't valid, with certificate_status invalid or expired

certificate_checked_at
​string | null · date-time · required

When the certificate was last checked

performance_check_enabled
​boolean · required

Whether slow responses raise alerts (performance_hard_threshold, performance_deviation_percentage)

performance_hard_threshold
​integer | null · required

Milliseconds: a response slower than this raises an alert

Example: 2000
performance_deviation_percentage
​integer | null · required

Percent: an alert fires when the average response time of the last performance_deviation_timeframe minutes is this much above the average of the performance_deviation_before_timeframe minutes before

Example: 50
performance_deviation_timeframe
​integer | null · required

Minutes of recent checks compared (15 to 120, in steps of 15)

Example: 30
performance_deviation_before_timeframe
​integer | null · required

Minutes before those that they're compared with (60 to 1440, in whole hours)

Example: 240
regional_performance_enabled
​boolean · required

Also measure response time from the regions other than primary_location, every minute (or at the interval, when longer). Shown with the monitor's performance; not used for uptime or alerts. Team plan and up

uptime_status
​UptimeStatus · enum · required

Whether the target answers, from the latest checks

pending
Not checked yet.
up
The latest check succeeded.
down
Checks fail: a failed check, repeated from the same region about 5 seconds later, failed again.
Enum values:
pending
up
down
uptime_status_changed_at
​string | null · date-time · required

When uptime_status last changed

last_checked_at
​string | null · date-time · required

When the monitor was last checked

response_time
​integer | null · required

Milliseconds the latest check took

Example: 182
​required
​MonitorUptime · required

Uptime over rolling windows

project_id
​string | null · uuid · required

The project the monitor belongs to; null for none

​EscalationPathReference[] · required

Escalation paths the monitor's alerts follow. Empty: the project's paths, else the team's default path

created_at
​string · date-time · required

When the monitor was created

updated_at
​string · date-time · required

When the monitor's settings last changed

Get a monitor

GET
https://api.spectate.net/v1
/monitors/{monitor}

Returns the monitor's settings and its latest results: uptime status, response time, certificate and uptime percentages.

Get a monitor › path Parameters

monitor
​string · uuid · required

Monitor ID.

Get a monitor › Responses

The monitor.

A monitor: a check of a URL, host or DNS name from Spectate's regions, with its settings and latest results.
Monitor
id
​string · uuid · required

Monitor ID

label
​string · required

Name shown in the dashboard, alerts and status pages

Example: Website
protocol
​MonitorProtocol · enum · required

What is checked; decides the format of uri

https
An HTTPS request to the URL in uri, with a certificate check.
http
An HTTP request to the URL in uri.
icmp
A ping (ICMP echo) to the host in uri.
tcp
A TCP connect to host:port, optionally with a TLS handshake and a banner keyword.
dns
A DNS query for a record of the name in uri, optionally compared with expected values.
smtp
An SMTP greeting from host:port (port optional), with STARTTLS by default.
imap
An IMAP greeting from host:port (port optional), over TLS by default.
pop3
A POP3 greeting from host:port (port optional), over TLS by default.
Enum values:
https
http
icmp
tcp
dns
smtp
imap
pop3
uri
​string · required

The target as stored: a URL without the scheme for http and https (the protocol is the scheme), a host for icmp, host:port for tcp and mail, a DNS name for dns. url has the full URL

Example: example.com/health
url
​string · required

The target as the dashboard shows it, for example smtp://mail.example.com:587 for SMTP

Example: https://example.com/health
interval
​MonitorInterval · enum · required

Seconds between checks

Enum values:
30
60
120
180
300
600
900
1800
primary_location
​MonitorLocation · enum · required

Region the checks run from; a failed check is repeated from the same region about 5 seconds later before the monitor goes down

eu
Europe.
us
North America.
as
Asia.
oc
Oceania.
Enum values:
eu
us
as
oc
timeout
​integer · required

Seconds before a check times out

Example: 30
max_redirects
​integer | null · required

HTTP: redirects followed before the check fails; null follows up to 10

​MonitorHeader[] · required

HTTP: headers sent with every check

​MonitorAdvancedSettings · required

Protocol-specific settings

enabled
​boolean · required

Whether the monitor runs. false when paused by a member or by the system (see paused_reason)

​required
allow_insecure_requests
​boolean · required

HTTPS: whether invalid certificates are accepted for the check itself (the certificate check still reports them)

expected_http_status_code
​string | null · required

HTTP: status codes that count as up, comma-separated, * as a wildcard digit (2**,301); null accepts 2xx and 3xx

Example: 2**,301
certificate_check_enabled
​boolean · required

Whether the TLS certificate is checked for validity and expiry

certificate_expiry_threshold_days
​integer · required

Days before the certificate expires that the "expires soon" alert fires

Example: 14
uses_tls
​boolean · required

Whether a check reports a certificate: HTTPS, and TCP or mail with TLS

​required
certificate_expires_at
​string | null · date-time · required

When the certificate expires

certificate_valid_from
​string | null · date-time · required

When the certificate became valid

certificate_issuer
​string | null · required

Who issued the certificate

Example: R11
certificate_error
​string | null · required

Why the certificate isn't valid, with certificate_status invalid or expired

certificate_checked_at
​string | null · date-time · required

When the certificate was last checked

performance_check_enabled
​boolean · required

Whether slow responses raise alerts (performance_hard_threshold, performance_deviation_percentage)

performance_hard_threshold
​integer | null · required

Milliseconds: a response slower than this raises an alert

Example: 2000
performance_deviation_percentage
​integer | null · required

Percent: an alert fires when the average response time of the last performance_deviation_timeframe minutes is this much above the average of the performance_deviation_before_timeframe minutes before

Example: 50
performance_deviation_timeframe
​integer | null · required

Minutes of recent checks compared (15 to 120, in steps of 15)

Example: 30
performance_deviation_before_timeframe
​integer | null · required

Minutes before those that they're compared with (60 to 1440, in whole hours)

Example: 240
regional_performance_enabled
​boolean · required

Also measure response time from the regions other than primary_location, every minute (or at the interval, when longer). Shown with the monitor's performance; not used for uptime or alerts. Team plan and up

uptime_status
​UptimeStatus · enum · required

Whether the target answers, from the latest checks

pending
Not checked yet.
up
The latest check succeeded.
down
Checks fail: a failed check, repeated from the same region about 5 seconds later, failed again.
Enum values:
pending
up
down
uptime_status_changed_at
​string | null · date-time · required

When uptime_status last changed

last_checked_at
​string | null · date-time · required

When the monitor was last checked

response_time
​integer | null · required

Milliseconds the latest check took

Example: 182
​required
​MonitorUptime · required

Uptime over rolling windows

project_id
​string | null · uuid · required

The project the monitor belongs to; null for none

​EscalationPathReference[] · required

Escalation paths the monitor's alerts follow. Empty: the project's paths, else the team's default path

created_at
​string · date-time · required

When the monitor was created

updated_at
​string · date-time · required

When the monitor's settings last changed

Update a monitor

PATCH
https://api.spectate.net/v1
/monitors/{monitor}

Changes only the fields you send; advanced_settings is merged into the current settings. Changing protocol requires a uri in the new protocol's format. The next check uses the new settings.

Update a monitor › path Parameters

monitor
​string · uuid · required

Monitor ID.

Update a monitor › Request Body

Changes to a monitor; fields you leave out keep their value. To pause or resume it, use `pauseMonitor` and `resumeMonitor`.
UpdateMonitor
label
​string · maxLength: 255

Name shown in the dashboard, alerts and status pages

Example: Website
protocol
​MonitorProtocol · enum

What to check. Changing it requires uri in the new protocol's format

https
An HTTPS request to the URL in uri, with a certificate check.
http
An HTTP request to the URL in uri.
icmp
A ping (ICMP echo) to the host in uri.
tcp
A TCP connect to host:port, optionally with a TLS handshake and a banner keyword.
dns
A DNS query for a record of the name in uri, optionally compared with expected values.
smtp
An SMTP greeting from host:port (port optional), with STARTTLS by default.
imap
An IMAP greeting from host:port (port optional), over TLS by default.
pop3
A POP3 greeting from host:port (port optional), over TLS by default.
Enum values:
https
http
icmp
tcp
dns
smtp
imap
pop3
uri
​string · maxLength: 2048

The target, in the format of the (new) protocol; see createMonitor. For http and https the scheme is optional and must match the protocol; it is stored without the scheme

Example: https://example.com/health
interval
​MonitorInterval · enum

Seconds between checks. Plans set the shortest allowed interval

Enum values:
30
60
120
180
300
600
900
1800
primary_location
​MonitorLocation · enum

Region the checks run from

eu
Europe.
us
North America.
as
Asia.
oc
Oceania.
Enum values:
eu
us
as
oc
timeout
​integer · min: 1 · max: 60

Seconds before a check times out, 1 to 60

max_redirects
​integer | null · min: 0 · max: 10

HTTP: redirects to follow, 0 to 10; null follows up to 10

​MonitorHeader[]

HTTP: up to 25 headers to send; replaces the current headers

​MonitorAdvancedSettingsInput

Protocol-specific settings; settings you leave out keep their value

allow_insecure_requests
​boolean

HTTPS: accept invalid certificates for the check itself

expected_http_status_code
​string | null · minLength: 1 · maxLength: 200

HTTP: status codes that count as up; null accepts 2xx and 3xx

certificate_check_enabled
​boolean

Check the TLS certificate for validity and expiry

certificate_expiry_threshold_days
​integer · min: 1 · max: 90

Days before the certificate expires that the "expires soon" alert fires, 1 to 90

performance_check_enabled
​boolean

Raise alerts for slow responses

performance_hard_threshold
​integer | null · min: 1 · max: 30000

Milliseconds, 1 to 30000: a response slower than this raises an alert

performance_deviation_percentage
​integer | null · min: 1 · max: 500

Percent, 1 to 500: alert when recent response times are this much above the earlier ones

performance_deviation_timeframe
​integer | null · min: 15 · max: 120

Minutes of recent checks to compare: 15 to 120 in steps of 15

performance_deviation_before_timeframe
​integer | null · min: 60 · max: 1440

Minutes before those to compare with: 60 to 1440 in whole hours

regional_performance_enabled
​boolean

Also measure response time from the regions other than primary_location, every minute (or at the interval, when longer). Shown with the monitor's performance; not used for uptime or alerts. Team plan and up

project_id
​string | null · uuid

Project of the monitor; null for none

escalation_path_ids
​string[]

Escalation paths for the monitor's alerts; replaces the current ones. [] follows the project's paths, else the team's default path

Update a monitor › Responses

The updated monitor.

A monitor: a check of a URL, host or DNS name from Spectate's regions, with its settings and latest results.
Monitor
id
​string · uuid · required

Monitor ID

label
​string · required

Name shown in the dashboard, alerts and status pages

Example: Website
protocol
​MonitorProtocol · enum · required

What is checked; decides the format of uri

https
An HTTPS request to the URL in uri, with a certificate check.
http
An HTTP request to the URL in uri.
icmp
A ping (ICMP echo) to the host in uri.
tcp
A TCP connect to host:port, optionally with a TLS handshake and a banner keyword.
dns
A DNS query for a record of the name in uri, optionally compared with expected values.
smtp
An SMTP greeting from host:port (port optional), with STARTTLS by default.
imap
An IMAP greeting from host:port (port optional), over TLS by default.
pop3
A POP3 greeting from host:port (port optional), over TLS by default.
Enum values:
https
http
icmp
tcp
dns
smtp
imap
pop3
uri
​string · required

The target as stored: a URL without the scheme for http and https (the protocol is the scheme), a host for icmp, host:port for tcp and mail, a DNS name for dns. url has the full URL

Example: example.com/health
url
​string · required

The target as the dashboard shows it, for example smtp://mail.example.com:587 for SMTP

Example: https://example.com/health
interval
​MonitorInterval · enum · required

Seconds between checks

Enum values:
30
60
120
180
300
600
900
1800
primary_location
​MonitorLocation · enum · required

Region the checks run from; a failed check is repeated from the same region about 5 seconds later before the monitor goes down

eu
Europe.
us
North America.
as
Asia.
oc
Oceania.
Enum values:
eu
us
as
oc
timeout
​integer · required

Seconds before a check times out

Example: 30
max_redirects
​integer | null · required

HTTP: redirects followed before the check fails; null follows up to 10

​MonitorHeader[] · required

HTTP: headers sent with every check

​MonitorAdvancedSettings · required

Protocol-specific settings

enabled
​boolean · required

Whether the monitor runs. false when paused by a member or by the system (see paused_reason)

​required
allow_insecure_requests
​boolean · required

HTTPS: whether invalid certificates are accepted for the check itself (the certificate check still reports them)

expected_http_status_code
​string | null · required

HTTP: status codes that count as up, comma-separated, * as a wildcard digit (2**,301); null accepts 2xx and 3xx

Example: 2**,301
certificate_check_enabled
​boolean · required

Whether the TLS certificate is checked for validity and expiry

certificate_expiry_threshold_days
​integer · required

Days before the certificate expires that the "expires soon" alert fires

Example: 14
uses_tls
​boolean · required

Whether a check reports a certificate: HTTPS, and TCP or mail with TLS

​required
certificate_expires_at
​string | null · date-time · required

When the certificate expires

certificate_valid_from
​string | null · date-time · required

When the certificate became valid

certificate_issuer
​string | null · required

Who issued the certificate

Example: R11
certificate_error
​string | null · required

Why the certificate isn't valid, with certificate_status invalid or expired

certificate_checked_at
​string | null · date-time · required

When the certificate was last checked

performance_check_enabled
​boolean · required

Whether slow responses raise alerts (performance_hard_threshold, performance_deviation_percentage)

performance_hard_threshold
​integer | null · required

Milliseconds: a response slower than this raises an alert

Example: 2000
performance_deviation_percentage
​integer | null · required

Percent: an alert fires when the average response time of the last performance_deviation_timeframe minutes is this much above the average of the performance_deviation_before_timeframe minutes before

Example: 50
performance_deviation_timeframe
​integer | null · required

Minutes of recent checks compared (15 to 120, in steps of 15)

Example: 30
performance_deviation_before_timeframe
​integer | null · required

Minutes before those that they're compared with (60 to 1440, in whole hours)

Example: 240
regional_performance_enabled
​boolean · required

Also measure response time from the regions other than primary_location, every minute (or at the interval, when longer). Shown with the monitor's performance; not used for uptime or alerts. Team plan and up

uptime_status
​UptimeStatus · enum · required

Whether the target answers, from the latest checks

pending
Not checked yet.
up
The latest check succeeded.
down
Checks fail: a failed check, repeated from the same region about 5 seconds later, failed again.
Enum values:
pending
up
down
uptime_status_changed_at
​string | null · date-time · required

When uptime_status last changed

last_checked_at
​string | null · date-time · required

When the monitor was last checked

response_time
​integer | null · required

Milliseconds the latest check took

Example: 182
​required
​MonitorUptime · required

Uptime over rolling windows

project_id
​string | null · uuid · required

The project the monitor belongs to; null for none

​EscalationPathReference[] · required

Escalation paths the monitor's alerts follow. Empty: the project's paths, else the team's default path

created_at
​string · date-time · required

When the monitor was created

updated_at
​string · date-time · required

When the monitor's settings last changed

Delete a monitor

DELETE
https://api.spectate.net/v1
/monitors/{monitor}

Its checks stop at once and it no longer appears in the API or the dashboard. Seven days later the monitor is deleted permanently with all its data: check history, alerts and failure snapshots. Until then support can restore it on request. Incidents stay, and status page components that showed the monitor keep their place without it. Deleting the same monitor again returns 404.

Delete a monitor › path Parameters

monitor
​string · uuid · required

Monitor ID.

Delete a monitor › Responses

No content

No data returned

Pause a monitor

POST
https://api.spectate.net/v1
/monitors/{monitor}/pause

Stops its checks; ongoing alerts stay as they are. Pausing a paused monitor changes nothing.

Pause a monitor › path Parameters

monitor
​string · uuid · required

Monitor ID.

Pause a monitor › Responses

The paused monitor.

A monitor: a check of a URL, host or DNS name from Spectate's regions, with its settings and latest results.
Monitor
id
​string · uuid · required

Monitor ID

label
​string · required

Name shown in the dashboard, alerts and status pages

Example: Website
protocol
​MonitorProtocol · enum · required

What is checked; decides the format of uri

https
An HTTPS request to the URL in uri, with a certificate check.
http
An HTTP request to the URL in uri.
icmp
A ping (ICMP echo) to the host in uri.
tcp
A TCP connect to host:port, optionally with a TLS handshake and a banner keyword.
dns
A DNS query for a record of the name in uri, optionally compared with expected values.
smtp
An SMTP greeting from host:port (port optional), with STARTTLS by default.
imap
An IMAP greeting from host:port (port optional), over TLS by default.
pop3
A POP3 greeting from host:port (port optional), over TLS by default.
Enum values:
https
http
icmp
tcp
dns
smtp
imap
pop3
uri
​string · required

The target as stored: a URL without the scheme for http and https (the protocol is the scheme), a host for icmp, host:port for tcp and mail, a DNS name for dns. url has the full URL

Example: example.com/health
url
​string · required

The target as the dashboard shows it, for example smtp://mail.example.com:587 for SMTP

Example: https://example.com/health
interval
​MonitorInterval · enum · required

Seconds between checks

Enum values:
30
60
120
180
300
600
900
1800
primary_location
​MonitorLocation · enum · required

Region the checks run from; a failed check is repeated from the same region about 5 seconds later before the monitor goes down

eu
Europe.
us
North America.
as
Asia.
oc
Oceania.
Enum values:
eu
us
as
oc
timeout
​integer · required

Seconds before a check times out

Example: 30
max_redirects
​integer | null · required

HTTP: redirects followed before the check fails; null follows up to 10

​MonitorHeader[] · required

HTTP: headers sent with every check

​MonitorAdvancedSettings · required

Protocol-specific settings

enabled
​boolean · required

Whether the monitor runs. false when paused by a member or by the system (see paused_reason)

​required
allow_insecure_requests
​boolean · required

HTTPS: whether invalid certificates are accepted for the check itself (the certificate check still reports them)

expected_http_status_code
​string | null · required

HTTP: status codes that count as up, comma-separated, * as a wildcard digit (2**,301); null accepts 2xx and 3xx

Example: 2**,301
certificate_check_enabled
​boolean · required

Whether the TLS certificate is checked for validity and expiry

certificate_expiry_threshold_days
​integer · required

Days before the certificate expires that the "expires soon" alert fires

Example: 14
uses_tls
​boolean · required

Whether a check reports a certificate: HTTPS, and TCP or mail with TLS

​required
certificate_expires_at
​string | null · date-time · required

When the certificate expires

certificate_valid_from
​string | null · date-time · required

When the certificate became valid

certificate_issuer
​string | null · required

Who issued the certificate

Example: R11
certificate_error
​string | null · required

Why the certificate isn't valid, with certificate_status invalid or expired

certificate_checked_at
​string | null · date-time · required

When the certificate was last checked

performance_check_enabled
​boolean · required

Whether slow responses raise alerts (performance_hard_threshold, performance_deviation_percentage)

performance_hard_threshold
​integer | null · required

Milliseconds: a response slower than this raises an alert

Example: 2000
performance_deviation_percentage
​integer | null · required

Percent: an alert fires when the average response time of the last performance_deviation_timeframe minutes is this much above the average of the performance_deviation_before_timeframe minutes before

Example: 50
performance_deviation_timeframe
​integer | null · required

Minutes of recent checks compared (15 to 120, in steps of 15)

Example: 30
performance_deviation_before_timeframe
​integer | null · required

Minutes before those that they're compared with (60 to 1440, in whole hours)

Example: 240
regional_performance_enabled
​boolean · required

Also measure response time from the regions other than primary_location, every minute (or at the interval, when longer). Shown with the monitor's performance; not used for uptime or alerts. Team plan and up

uptime_status
​UptimeStatus · enum · required

Whether the target answers, from the latest checks

pending
Not checked yet.
up
The latest check succeeded.
down
Checks fail: a failed check, repeated from the same region about 5 seconds later, failed again.
Enum values:
pending
up
down
uptime_status_changed_at
​string | null · date-time · required

When uptime_status last changed

last_checked_at
​string | null · date-time · required

When the monitor was last checked

response_time
​integer | null · required

Milliseconds the latest check took

Example: 182
​required
​MonitorUptime · required

Uptime over rolling windows

project_id
​string | null · uuid · required

The project the monitor belongs to; null for none

​EscalationPathReference[] · required

Escalation paths the monitor's alerts follow. Empty: the project's paths, else the team's default path

created_at
​string · date-time · required

When the monitor was created

updated_at
​string · date-time · required

When the monitor's settings last changed

Resume a monitor

POST
https://api.spectate.net/v1
/monitors/{monitor}/resume

Starts its checks again, also when the system paused it for the plan limit, if the plan has room now (403 PLAN_LIMIT_REACHED otherwise). While the team's monitoring is paused (no paid plan) nothing can be resumed (409 TEAM_MONITORING_PAUSED). Resuming a running monitor changes nothing.

Resume a monitor › path Parameters

monitor
​string · uuid · required

Monitor ID.

Resume a monitor › Responses

The running monitor.

A monitor: a check of a URL, host or DNS name from Spectate's regions, with its settings and latest results.
Monitor
id
​string · uuid · required

Monitor ID

label
​string · required

Name shown in the dashboard, alerts and status pages

Example: Website
protocol
​MonitorProtocol · enum · required

What is checked; decides the format of uri

https
An HTTPS request to the URL in uri, with a certificate check.
http
An HTTP request to the URL in uri.
icmp
A ping (ICMP echo) to the host in uri.
tcp
A TCP connect to host:port, optionally with a TLS handshake and a banner keyword.
dns
A DNS query for a record of the name in uri, optionally compared with expected values.
smtp
An SMTP greeting from host:port (port optional), with STARTTLS by default.
imap
An IMAP greeting from host:port (port optional), over TLS by default.
pop3
A POP3 greeting from host:port (port optional), over TLS by default.
Enum values:
https
http
icmp
tcp
dns
smtp
imap
pop3
uri
​string · required

The target as stored: a URL without the scheme for http and https (the protocol is the scheme), a host for icmp, host:port for tcp and mail, a DNS name for dns. url has the full URL

Example: example.com/health
url
​string · required

The target as the dashboard shows it, for example smtp://mail.example.com:587 for SMTP

Example: https://example.com/health
interval
​MonitorInterval · enum · required

Seconds between checks

Enum values:
30
60
120
180
300
600
900
1800
primary_location
​MonitorLocation · enum · required

Region the checks run from; a failed check is repeated from the same region about 5 seconds later before the monitor goes down

eu
Europe.
us
North America.
as
Asia.
oc
Oceania.
Enum values:
eu
us
as
oc
timeout
​integer · required

Seconds before a check times out

Example: 30
max_redirects
​integer | null · required

HTTP: redirects followed before the check fails; null follows up to 10

​MonitorHeader[] · required

HTTP: headers sent with every check

​MonitorAdvancedSettings · required

Protocol-specific settings

enabled
​boolean · required

Whether the monitor runs. false when paused by a member or by the system (see paused_reason)

​required
allow_insecure_requests
​boolean · required

HTTPS: whether invalid certificates are accepted for the check itself (the certificate check still reports them)

expected_http_status_code
​string | null · required

HTTP: status codes that count as up, comma-separated, * as a wildcard digit (2**,301); null accepts 2xx and 3xx

Example: 2**,301
certificate_check_enabled
​boolean · required

Whether the TLS certificate is checked for validity and expiry

certificate_expiry_threshold_days
​integer · required

Days before the certificate expires that the "expires soon" alert fires

Example: 14
uses_tls
​boolean · required

Whether a check reports a certificate: HTTPS, and TCP or mail with TLS

​required
certificate_expires_at
​string | null · date-time · required

When the certificate expires

certificate_valid_from
​string | null · date-time · required

When the certificate became valid

certificate_issuer
​string | null · required

Who issued the certificate

Example: R11
certificate_error
​string | null · required

Why the certificate isn't valid, with certificate_status invalid or expired

certificate_checked_at
​string | null · date-time · required

When the certificate was last checked

performance_check_enabled
​boolean · required

Whether slow responses raise alerts (performance_hard_threshold, performance_deviation_percentage)

performance_hard_threshold
​integer | null · required

Milliseconds: a response slower than this raises an alert

Example: 2000
performance_deviation_percentage
​integer | null · required

Percent: an alert fires when the average response time of the last performance_deviation_timeframe minutes is this much above the average of the performance_deviation_before_timeframe minutes before

Example: 50
performance_deviation_timeframe
​integer | null · required

Minutes of recent checks compared (15 to 120, in steps of 15)

Example: 30
performance_deviation_before_timeframe
​integer | null · required

Minutes before those that they're compared with (60 to 1440, in whole hours)

Example: 240
regional_performance_enabled
​boolean · required

Also measure response time from the regions other than primary_location, every minute (or at the interval, when longer). Shown with the monitor's performance; not used for uptime or alerts. Team plan and up

uptime_status
​UptimeStatus · enum · required

Whether the target answers, from the latest checks

pending
Not checked yet.
up
The latest check succeeded.
down
Checks fail: a failed check, repeated from the same region about 5 seconds later, failed again.
Enum values:
pending
up
down
uptime_status_changed_at
​string | null · date-time · required

When uptime_status last changed

last_checked_at
​string | null · date-time · required

When the monitor was last checked

response_time
​integer | null · required

Milliseconds the latest check took

Example: 182
​required
​MonitorUptime · required

Uptime over rolling windows

project_id
​string | null · uuid · required

The project the monitor belongs to; null for none

​EscalationPathReference[] · required

Escalation paths the monitor's alerts follow. Empty: the project's paths, else the team's default path

created_at
​string · date-time · required

When the monitor was created

updated_at
​string · date-time · required

When the monitor's settings last changed

API tokensHosts