Usage API

Endpoints#

Scope rules#

These endpoints require the same bearer authentication as the rest of the public API. A key belongs to a room, so usage is the room's. Rungs are counted at the level each request ran at.

Current usage#

{
  "period_start": "2026-04-01T00:00:00+00:00",
  "period_end": "2026-05-01T00:00:00+00:00",
  "input_rungs": 48100,
  "output_rungs": 80300,
  "total_rungs": 128400,
  "request_count": 93,
  "allowance": 10000000,
  "remaining": 9871600,
  "estimated_cost_pence": 0
}

allowance and remaining are the room's spend limit for the period in rungs, as set in the API portal. No room is unlimited: a request that would pass the limit is refused before inference.

Usage history#

{
  "periods": [
    {
      "period_start": "2026-04-01T00:00:00+00:00",
      "period_end": "2026-05-01T00:00:00+00:00",
      "input_rungs": 48100,
      "output_rungs": 80300,
      "total_rungs": 128400,
      "request_count": 93
    }
  ]
}

History is returned in descending period order and is currently capped to the most recent 12 periods.

Limits#

{
  "tier": "developer",
  "requests_per_minute": 300,
  "rungs_per_minute": 5000000,
  "monthly_allowance": 10000000,
  "monthly_used": 128400
}

A room works on one request at a time; further requests queue. Limits apply per key and per room, and the spend tier rises with payment history and account age. See Limits and credit for the behaviour of headers and throttling responses.

Errors#

• 401 INVALID_API_KEY or 401 MISSING_API_KEY for auth failures
• 403 INSUFFICIENT_TIER when the account has no prepaid credit or Developer plan to draw on
• 500 DB_ERROR when usage data could not be queried
• 503 DB_UNAVAILABLE when the database is not available