Skip to content
All documentation

GET /v1/status

Updated
Reading time
3 min
On this page

The snapshot to check before sending a batch, and the first thing to look at when requests are queuing. It answers two questions: can a request be processed right now, and how much of your plan is left this month?

curl https://api.revoye.com/v1/status \
  -H "Authorization: Bearer $REVOYE_KEY"
{
  "devices": { "total": 2, "online": 1 },
  "agents": { "total": 3, "idle": 2, "busy": 1, "error": 0, "offline": 0 },
  "providers": [
    {
      "kind": "<model id>",
      "enabled": true,
      "agents_idle": 2,
      "rate_limit_per_hour": 60,
      "used_this_hour": 14
    }
  ],
  "queue": { "depth": 4, "oldest_queued_at": "2026-10-13T09:12:00Z" },
  "channels": {
    "desk": { "available": true, "devices": { "online": 1 } },
    "cloud": { "available": true, "providers": { "<model id>": "available" } }
  },
  "quota": {
    "desk": { "used": 120400, "limit": null, "resets_at": "2026-11-13T00:00:00Z" },
    "cloud": { "used": 48210, "limit": 1000000, "resets_at": "2026-11-13T00:00:00Z" }
  }
}

<model id> stands for an id from GET /v1/models.

Reading it

FieldMeans
channelsOne entry per channel your plan includes — a channel it does not include is absent, not false. available: true means it can process a request now
channels.desk.devices.onlineHow many of your devices have Revoye Desk online right now
channels.cloud.providersWhich models Revoye Cloud can process right now: available or unavailable
quotaThis month's tokens per included channel. limit: null is unlimited. resets_at is your subscription date, not the first of the month
queue.depthRequests waiting
queue.oldest_queued_atWhen the oldest waiting request was queued. The single best signal that requests are backing up
devices.totalYour devices connected to Revoye Desk. A removed device is not counted, and has to be connected again to come back
devices.onlineOf those, how many are online now
agents.*Revoye Desk capacity on your devices: free (idle), working (busy), needing attention in Revoye Desk (error) or offline
providers[]Revoye Desk, per model: whether it is switched on, how much capacity is free (agents_idle), and your optional hourly limit
rate_limit_per_hourThe hourly limit you set for that model on Revoye Desk. null means no limit
used_this_hourRequests counted against that limit this hour

devices, agents and providers describe Revoye Desk only. On a plan without it, ignore them and use channels and quota.

available: false is not an error. It describes this instant. Requests sent now wait in your queue — or move to the other channel, on a plan with both.

Using it well

As a pre-flight check. Before a batch, confirm that a channel your plan includes is available. If none is, either queue with a callback_url or wait — do not fire a thousand requests that will all sit behind a device that is switched off.

As a budget check. Compare quota.*.used with limit before a large batch. A request that does not fit in what is left is refused with QUOTA_EXCEEDED rather than queued.

As a capacity signal. A queue.depth that keeps growing while queue.oldest_queued_at gets older means requests arrive faster than they are processed. Spread the batch out, or use webhooks so the wait does not matter.

Not as a lock. The snapshot is true when it is generated and can be stale by the time you act on it. Treat it as a hint and handle NO_DEVICE_ONLINE and NO_AGENT_AVAILABLE anyway.

Not in a tight loop. Polling status per request wastes your request rate limit. Poll on a schedule you actually need — once a minute is plenty for a dashboard.

Requires status:read.