Skip to main content
GET
Get an Observer Agent: status, whether it ever connected, heartbeats, metric count

Authorizations

Authorization
string
header
required

An organization API key (obs_pub_…) sent as Authorization: Bearer <key>. Each key carries scopes; an endpoint lists the scope it needs. read:change_events is reserved: keys can carry it, but no endpoint needs it yet.

Scopes

read:agents

Path Parameters

id
string<uuid>
required

Agent id.

Query Parameters

target
enum<string>

Add the install snippet for this one target (and env): docker, compose, kubernetes, systemd (Linux), launchd (macOS) or binary (Linux or macOS, foreground).

Available options:
docker,
compose,
kubernetes,
systemd,
launchd,
binary
include
enum<string>

install: add every install snippet (and env). Omit it for the small default response.

Available options:
install

Response

ok

id
string<uuid>
required
name
string
required

Config documents name the agent a metric runs on by this (metrics[].agent).

status
enum<string>
required

never_connected: no heartbeat yet (installed agents report within about a minute). online: a heartbeat in the last 90 seconds. offline: it has connected before but has been silent for over 90 seconds. revoked: its key is rejected (console kill switch).

Available options:
never_connected,
online,
offline,
revoked
online
boolean
required

status is online.

created_at
string<date-time>
required
description
string | null
connected_ever
boolean

The agent has sent at least one heartbeat, ever. Unlike status it stays true when the agent goes offline or is revoked. false = nothing has ever run with its key: safe to reuse (rotate its key) instead of creating another agent.

first_seen_at
string<date-time> | null

First heartbeat ever, when known (null for agents that never connected).

last_heartbeat_at
string<date-time> | null

Last heartbeat.

version
string | null

Agent version from its last heartbeat.

is_demo
boolean

Seeded demo agent; nothing runs it.

suspended
boolean

true while the agent is suspended because the organization is over its plan's limit (after a 7-day grace). Nothing is deleted; it is read-only until the person chooses it as active in Billing or upgrades. Writes return 403 item_suspended_plan.

suspended_at
string<date-time> | null

When the suspension started.

first_heartbeat_at
string<date-time> | null

First heartbeat ever: when the install first connected.

started_at
string<date-time> | null

When the running agent process started.

revoked_at
string<date-time> | null
previous_key_valid_until
string<date-time> | null

After a graceful key rotation: the old key keeps working until this time. null when no old key is valid.

metric_count
integer

Metrics assigned to this agent.

source_types_active
string[]

Probe types the agent reported running in its last heartbeat.

queue_depth
integer

Samples buffered on the agent, not yet delivered.

otlp_stats
object | null

Latest OTLP receiver stats, when the agent runs the receiver.

custom_probes
object[]

Custom probes registered on the agent (name, description, has_config_schema), from its last heartbeat.

prometheus_url
string | null

Prometheus base URL recorded for the agent, if it reads PromQL.

install
object

Only with ?target= or ?include=install. Install snippets keyed by target: docker (docker run), compose, kubernetes (Secret + Deployment manifest), systemd (Linux service), launchd (macOS LaunchAgent) and binary (foreground, Linux or macOS). Only the requested target with ?target=, all of them with ?include=install. The systemd, launchd and binary snippets pick the right binary on the host (uname). Without prometheus_url they are for a probes-only agent. Here with the ${AGENT_KEY} placeholder: the key is only returned by create and rotate-key.

env
object

Only with ?target= or ?include=install. The agent's environment as NAME: value (AGENT_KEY, CLOUD_SERVER_URL, and PROMETHEUS_SERVER_URL for a Prometheus agent), for installs the snippets do not cover, such as an existing Compose file or Helm values. AGENT_KEY is the ${AGENT_KEY} placeholder here.