Your API key:

All requests below will use this key. Your API key is sent directly to api.cueapi.ai and never stored by the docs site.

GET/v1/workers

List Workers

List all registered workers for the authenticated account with heartbeat status (active, stale, dead).

Returns every cueapi-worker daemon registered to the authenticated account, ordered by last_heartbeat descending (most recently seen first).

Request

bash

curl https://api.cueapi.ai/v1/workers \
  -H "Authorization: Bearer cue_sk_YOUR_KEY"

Response

json

{
  "workers": [
    {
      "worker_id": "agent-mac-01",
      "last_heartbeat": "2026-04-19T22:30:14Z",
      "seconds_since_heartbeat": 18,
      "heartbeat_status": "active",
      "handlers": ["generate-report", "send-email"],
      "registered_since": "2026-04-12T09:15:00Z"
    },
    {
      "worker_id": "ci-runner-prod",
      "last_heartbeat": "2026-04-19T22:08:42Z",
      "seconds_since_heartbeat": 1310,
      "heartbeat_status": "dead",
      "handlers": ["nightly-backup"],
      "registered_since": "2026-03-20T17:42:00Z"
    }
  ]
}

`heartbeat_status` values

Status	When	Meaning
`active`	Last heartbeat < 360s ago	Worker is alive and pulling work
`stale`	360–900s ago	Worker may have hung; new claims still allowed for now
`dead`	900s+ ago	Worker is presumed gone; existing claims expire and re-route

The 360s active window matches cueapi-worker's default 30-second heartbeat interval × 12. Stale → dead transition matches the server's claim-lease expiry.

Scoped key filtering

If your API key was created with restricted_to_workers scoping, only workers registered under that key (or its sibling keys in the same group) are returned. Default default-labeled keys see all workers on the account.

Errors

Status	Code	Cause
401	`not_authenticated`	Missing/invalid bearer token

GET/v1/workers

Try it

Enter your API key above to send requests

Previous← Heartbeat NextDelete Worker →