Spectate
Spectate API
Spectate API

Hosts

Download schema

Servers with the Spectate agent, which reports CPU, memory, disk and network metrics every minute. Hosts register themselves when the agent is installed with an install token; the API reads, renames, assigns and deletes them. Hosts and monitors together count against the plan's resource limit.

List hosts

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

Returns the team's hosts, newest first unless you sort.

List hosts › query Parameters

page
​integer

Page number, from 1.

Default: 1
per_page
​integer

Hosts per page, 1 to 100.

Default: 25
filter[state]
​HostState · enum

Only hosts in this state.

Whether a host's agent reports.

up
Reported in the last 15 minutes.
stale
Reported before, but not in the last 15 minutes.
pending
The agent never reported.
Enum values:
up
stale
pending
filter[project_id]
​string · uuid

Only hosts of this project.

filter[search]
​string

Case-insensitive text in the label, host info (hostname, platform, architecture) or agent version.

sort
​string

Sort by label, last_seen_at or created_at. Prefix - for descending. Default -created_at.

List hosts › Responses

Paginated set of Host

current_page
​integer · min: 1 · required
​Host[] · 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 a host

GET
https://api.spectate.net/v1
/hosts/{host}

Returns the host with what its agent reports about the system. Metrics themselves are in the dashboard.

Get a host › path Parameters

host
​string · uuid · required

Host ID.

Get a host › Responses

The host.

A server with the Spectate agent, which reports CPU, memory, disk and network metrics. Hosts are added by installing the agent with an install token, not through the API.
Host
id
​string · uuid · required

Host ID

label
​string | null · required

Name shown in the dashboard and alerts; the agent sets the hostname until you change it

Example: web-1
state
​HostState · enum · required

Whether the agent reports

up
Reported in the last 15 minutes.
stale
Reported before, but not in the last 15 minutes.
pending
The agent never reported.
Enum values:
up
stale
pending
​object | null · required

What the agent reports about the system, as key-value pairs (for example hostname, os, platform, kernel_version); the keys depend on the agent version and platform

cpu_info
​array | null · required

The CPUs, each as key-value pairs (for example model_name, cores, mhz)

agent_version
​string | null · required

Version of the agent

Example: 2.0.3
agent_update_version
​string | null · required

A newer agent release, when the host runs an older one (sudo spectate-agent update)

clock_offset_ms
​integer | null · required

Server time minus the host's clock, in milliseconds, as last measured by a v2 agent; null when unknown

last_seen_at
​string | null · date-time · required

When the agent last reported

no_data_alert_minutes
​integer | null · required

Minutes without data before the "no data received" alert fires; null when that alert is off

Example: 10
​required
project_id
​string | null · uuid · required

The project the host belongs to; null for none

​EscalationPathReference[] · required

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

created_at
​string · date-time · required

When the host registered

​HostHealthCheckResult[] · required

Health checks (agent 2.1 or later): failed services, out of memory, reboot, updates, clock, file handles and pressure. Checks of collectors that are switched off, and Linux-only checks on other systems, are left out

health_issues
​integer · required

Number of health checks that need attention (warning or critical)

Update a host

PATCH
https://api.spectate.net/v1
/hosts/{host}

Changes only the fields you send. The agent stops renaming a host once you set its label.

Update a host › path Parameters

host
​string · uuid · required

Host ID.

Update a host › Request Body

Changes to a host; fields you leave out keep their value.
UpdateHost
label
​string · maxLength: 255

Name shown in the dashboard and alerts

Example: web-1
no_data_alert_minutes
​integer | null · min: 2 · max: 1440

Minutes without data, 2 to 1440, before the "no data received" alert fires; null turns it off. A firing alert ends at once when the host is within the new window

Example: 10
project_id
​string | null · uuid

Project of the host; null for none

escalation_path_ids
​string[]

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

Update a host › Responses

The updated host.

A server with the Spectate agent, which reports CPU, memory, disk and network metrics. Hosts are added by installing the agent with an install token, not through the API.
Host
id
​string · uuid · required

Host ID

label
​string | null · required

Name shown in the dashboard and alerts; the agent sets the hostname until you change it

Example: web-1
state
​HostState · enum · required

Whether the agent reports

up
Reported in the last 15 minutes.
stale
Reported before, but not in the last 15 minutes.
pending
The agent never reported.
Enum values:
up
stale
pending
​object | null · required

What the agent reports about the system, as key-value pairs (for example hostname, os, platform, kernel_version); the keys depend on the agent version and platform

cpu_info
​array | null · required

The CPUs, each as key-value pairs (for example model_name, cores, mhz)

agent_version
​string | null · required

Version of the agent

Example: 2.0.3
agent_update_version
​string | null · required

A newer agent release, when the host runs an older one (sudo spectate-agent update)

clock_offset_ms
​integer | null · required

Server time minus the host's clock, in milliseconds, as last measured by a v2 agent; null when unknown

last_seen_at
​string | null · date-time · required

When the agent last reported

no_data_alert_minutes
​integer | null · required

Minutes without data before the "no data received" alert fires; null when that alert is off

Example: 10
​required
project_id
​string | null · uuid · required

The project the host belongs to; null for none

​EscalationPathReference[] · required

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

created_at
​string · date-time · required

When the host registered

​HostHealthCheckResult[] · required

Health checks (agent 2.1 or later): failed services, out of memory, reboot, updates, clock, file handles and pressure. Checks of collectors that are switched off, and Linux-only checks on other systems, are left out

health_issues
​integer · required

Number of health checks that need attention (warning or critical)

Delete a host

DELETE
https://api.spectate.net/v1
/hosts/{host}

The host disappears from the API and the dashboard, and data its agent still sends is refused (the agent stops itself). Uninstall the agent on the server too. Seven days later the host is deleted permanently with all its data: metrics, alerts and metric condition links. Until then support can restore it on request. Deleting the same host again returns 404.

Delete a host › path Parameters

host
​string · uuid · required

Host ID.

Delete a host › Responses

No content

No data returned
MonitorsHost install tokens