Get an agent

GET

agents

{id}

Get an Observer Agent: status, first and last heartbeat, metric count

curl --request GET \
  --url https://use.observer/api/v1/agents/{id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://use.observer/api/v1/agents/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "status": "never_connected",
  "online": true,
  "created_at": "2023-11-07T05:31:56Z",
  "description": "<string>",
  "last_heartbeat_at": "2023-11-07T05:31:56Z",
  "version": "<string>",
  "is_demo": true,
  "first_heartbeat_at": "2023-11-07T05:31:56Z",
  "started_at": "2023-11-07T05:31:56Z",
  "revoked_at": "2023-11-07T05:31:56Z",
  "previous_key_valid_until": "2023-11-07T05:31:56Z",
  "metric_count": 123,
  "source_types_active": [
    "<string>"
  ],
  "queue_depth": 123,
  "otlp_stats": {},
  "custom_probes": [
    {}
  ],
  "prometheus_url": "<string>",
  "install": {
    "docker": {
      "label": "<string>",
      "content": "<string>",
      "file": "<string>",
      "logs_command": "<string>",
      "note": "<string>"
    },
    "compose": {
      "label": "<string>",
      "content": "<string>",
      "file": "<string>",
      "logs_command": "<string>",
      "note": "<string>"
    },
    "kubernetes": {
      "label": "<string>",
      "content": "<string>",
      "file": "<string>",
      "logs_command": "<string>",
      "note": "<string>"
    },
    "systemd": {
      "label": "<string>",
      "content": "<string>",
      "file": "<string>",
      "logs_command": "<string>",
      "note": "<string>"
    },
    "binary": {
      "label": "<string>",
      "content": "<string>",
      "file": "<string>",
      "logs_command": "<string>",
      "note": "<string>"
    }
  },
  "env": {}
}

{
  "type": "https://docs.use.observer/api/getting-started/errors#forbidden",
  "title": "forbidden",
  "status": 403,
  "detail": "missing scope: write:incidents"
}

{
  "type": "https://docs.use.observer/api/getting-started/errors#forbidden",
  "title": "forbidden",
  "status": 403,
  "detail": "missing scope: write:incidents"
}

{
  "type": "https://docs.use.observer/api/getting-started/errors#forbidden",
  "title": "forbidden",
  "status": 403,
  "detail": "missing scope: write:incidents"
}

{
  "type": "https://docs.use.observer/api/getting-started/errors#forbidden",
  "title": "forbidden",
  "status": 403,
  "detail": "missing scope: write:incidents"
}

{
  "type": "https://docs.use.observer/api/getting-started/errors#forbidden",
  "title": "forbidden",
  "status": 403,
  "detail": "missing scope: write:incidents"
}

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.

Path Parameters

string<uuid>

required

Agent id.

Response

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

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.

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

Install snippets, one per target: docker (docker run), compose, kubernetes (Secret + Deployment manifest), systemd and binary. 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.

Show child attributes

env

object

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.

Show child attributes

Get an Observer Agent: status, first and last heartbeat, metric count

curl --request GET \
  --url https://use.observer/api/v1/agents/{id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://use.observer/api/v1/agents/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "status": "never_connected",
  "online": true,
  "created_at": "2023-11-07T05:31:56Z",
  "description": "<string>",
  "last_heartbeat_at": "2023-11-07T05:31:56Z",
  "version": "<string>",
  "is_demo": true,
  "first_heartbeat_at": "2023-11-07T05:31:56Z",
  "started_at": "2023-11-07T05:31:56Z",
  "revoked_at": "2023-11-07T05:31:56Z",
  "previous_key_valid_until": "2023-11-07T05:31:56Z",
  "metric_count": 123,
  "source_types_active": [
    "<string>"
  ],
  "queue_depth": 123,
  "otlp_stats": {},
  "custom_probes": [
    {}
  ],
  "prometheus_url": "<string>",
  "install": {
    "docker": {
      "label": "<string>",
      "content": "<string>",
      "file": "<string>",
      "logs_command": "<string>",
      "note": "<string>"
    },
    "compose": {
      "label": "<string>",
      "content": "<string>",
      "file": "<string>",
      "logs_command": "<string>",
      "note": "<string>"
    },
    "kubernetes": {
      "label": "<string>",
      "content": "<string>",
      "file": "<string>",
      "logs_command": "<string>",
      "note": "<string>"
    },
    "systemd": {
      "label": "<string>",
      "content": "<string>",
      "file": "<string>",
      "logs_command": "<string>",
      "note": "<string>"
    },
    "binary": {
      "label": "<string>",
      "content": "<string>",
      "file": "<string>",
      "logs_command": "<string>",
      "note": "<string>"
    }
  },
  "env": {}
}

{
  "type": "https://docs.use.observer/api/getting-started/errors#forbidden",
  "title": "forbidden",
  "status": 403,
  "detail": "missing scope: write:incidents"
}

{
  "type": "https://docs.use.observer/api/getting-started/errors#forbidden",
  "title": "forbidden",
  "status": 403,
  "detail": "missing scope: write:incidents"
}

{
  "type": "https://docs.use.observer/api/getting-started/errors#forbidden",
  "title": "forbidden",
  "status": 403,
  "detail": "missing scope: write:incidents"
}

{
  "type": "https://docs.use.observer/api/getting-started/errors#forbidden",
  "title": "forbidden",
  "status": 403,
  "detail": "missing scope: write:incidents"
}

{
  "type": "https://docs.use.observer/api/getting-started/errors#forbidden",
  "title": "forbidden",
  "status": 403,
  "detail": "missing scope: write:incidents"
}

Getting started

Account

Status pages

Services

Metrics

SLOs

SLA statements

Incidents

Maintenances

Config as code

Agents

Change events

Authorizations

Path Parameters

Response