Skip to content
All documentation

GET /v1/status

Updated
Reading time
2 min
On this page

The snapshot to check before sending work, and the first thing to look at when jobs are queuing. It answers one question: can anything answer right now?

curl https://revoyeapi.degird.com/v1/status \
  -H "Authorization: Bearer $REVOYE_KEY"
{
  "devices": { "total": 2, "online": 1 },
  "agents": { "total": 7, "idle": 3, "busy": 2, "error": 0, "offline": 2 },
  "providers": [
    {
      "kind": "chatgpt",
      "enabled": true,
      "agents_idle": 2,
      "rate_limit_per_hour": 60,
      "used_this_hour": 14
    },
    {
      "kind": "deepseek",
      "enabled": true,
      "agents_idle": 1,
      "rate_limit_per_hour": null,
      "used_this_hour": 3
    }
  ],
  "queue": { "depth": 4, "oldest_queued_at": "2026-08-18T09:12:00Z" }
}

Reading it

FieldMeans
devices.totalYour active devices. A revoked device has left the fleet and cannot rejoin without pairing again
devices.onlineDevices connected right now
agents.*The state of every agent Revoye knows about
providers[].agents_idleNarrower than agents.idle — it counts only agents the router could actually dispatch to. An agent switched off in the dashboard or in the extension is excluded here while still appearing in the state totals
rate_limit_per_hourYour configured cap. null means no cap
used_this_hourConsumption against that cap
queue.depthJobs waiting
queue.oldest_queued_atHow long the oldest one has been waiting. The single best signal that your fleet is undersized

agents.idle of zero is not an error. It is a description of your fleet at this instant.

Using it well

As a pre-flight check. Before a batch, confirm devices.online > 0. If it is zero, either queue with a callback_url or wait — do not fire a thousand jobs that will all sit behind an offline laptop.

As a capacity signal. A queue.depth that grows while agents.idle stays at zero means you are saturated. The fix is more agents, not more retries.

Not as a lock. The snapshot is true when it is generated and can be stale by the time you act on it — an agent idle a moment ago may have taken another job. Treat it as a hint and handle NO_AGENT_AVAILABLE anyway.

Not in a tight loop. Polling status per request wastes your ingress rate limit. Poll on a schedule you actually need — once a minute is plenty for a dashboard — and let NO_AGENT_AVAILABLE tell you the rest.

Requires status:read.