Usage
What this account spent over a window — credits, jobs, items and synchronous calls — grouped by op, API key or day: the number an agent holds a budget against
1 endpoint under /api/v1/usage. What every call shares is on the REST overview, and what they are for — with the calls for every SDK, the CLI and MCP — on Jobs → What you are charged. * marks a required field.
Usage over a window, grouped
GET /api/v1/usage
What was spent over a time window, grouped by atomic op, by API key, or by UTC day, with the window's total beside the groups:
jobs— jobs created in the windowcreditsanditems— what those jobs were charged and how many of their items settled, so farsync— synchronous calls (/images/transform,/images/render) that succeeded and so cost an op from the allowance; never counted injobs./images/metadatais free and not counted
A job submitted as a raw type groups under that type; a console session, which has no key, groups under console. Days are UTC. Usage lives as long as the job records it comes from, so a window older than the plan's retention reads short.
USE THIS WHEN:
- An agent has a budget and needs to know what it has spent, and on what
- Attributing cost across several keys (one key per agent is the usual shape)
DO NOT USE WHEN:
- You need one job's own cost →
GET /api/v1/jobs/{id}(actualCredits, andcreditsper item) - You need every credit movement, top-ups and refunds included → the credit ledger, which a signed-in console session reads and an API key cannot
Parameters
| Name | In | Type | Description |
|---|---|---|---|
| from | query | string | Start of the window, inclusive. YYYY-MM-DD (UTC midnight) or an ISO-8601 instant. Defaults to 30 days before to; the window may span at most 366 days. |
| to | query | string | End of the window, exclusive — 2026-10-01 ends with the last instant of 30 September. Same formats. Defaults to now. |
| groupBy | query | string | What a group is: an op (op), an API key (key) or a UTC day (day)one of op · key · day |
Returns 200 — data is Usage
The window, its total and its groups
Errors
| Status | Code and when |
|---|---|
| 400 |
|
Objects
Each described once; a linked type is another object on this page.
Bucket
What was spent in one group, or in the whole window
| Field | Type | Description |
|---|---|---|
| credits | integer (int64) | Credits charged, for the jobs created in the window |
| items | integer (int64) | Items of those jobs that settled |
| jobs | integer (int64) | Jobs created in the window |
| key | string | The group: an op name (or the raw type of a job submitted without one), an API key id or console, or a UTC date YYYY-MM-DD. Absent on the total |
| sync | integer (int64) | Synchronous calls that succeeded and counted against the processing allowance |
Usage
Usage over one window: its bounds, the grouping, the total and one bucket per group
| Field | Type | Description |
|---|---|---|
| from | string (date-time) | Start of the window, inclusive |
| groupBy | string | What each group isone of op · key · day |
| groups | Bucket[] | One bucket per op, key or day that has any usage, ordered by key |
| to | string (date-time) | End of the window, exclusive |
| total | Bucket | The window's totals — the sum of the groups |