Usage and credits
Every model call costs credits. If your integration runs AI at any volume, plan for reaching the limit and for seeing it coming.
Check the balance
GET /me carries the current balance, which makes it the cheapest pre-flight check
before a batch of expensive work:
Code
low is the warning to act on. It fires before hasCredits goes false, which is the
difference between slowing down and stopping.
Running out
When credits are exhausted, model-running endpoints answer 403 with
code: "insufficient_credits":
Code
The two are different problems sharing a status. insufficient_credits is temporary and
fixed by topping up, while license_required means the plan does not include that module
and no amount of credit changes it. Retrying either is pointless. See errors.
Credits are not the only cap. Model-running endpoints are also counted against the
expensive rate-limit tier, so a burst can hit a 429 while credits are
healthy. Handle both.
Usage against the plan
Code
Reports what has been consumed this cycle and what the plan allows, the numbers behind a usage bar:
| Field | |
|---|---|
availableCredits, currentPeriodUsage, remainingCredits | The cycle's credit position. |
creditsExceeded | Whether the cycle is spent. |
topupCredits | Purchased credits held on top of the plan. Plan credits burn first, so this is the tail of the bar rather than a separate pool. |
creditsCycle | monthly or annual. Annual plans grant credits yearly. |
storageUsed, storageEntitlement | Bytes. Storage is entitled separately from credits. |
accountCreated | For building a period selector that does not offer periods before the workspace existed. |
This endpoint needs only usage:view, so an ordinary integration can watch its own
consumption. The breakdowns below sit under /admin and need admin:usage:view.
Usage breakdowns
Three views over the same data, for three different questions.
GET /admin/usage/entries lists the individual metered operations: what was run, by whom,
and how many credits it cost. Paginated with the standard envelope.
GET /admin/usage/aggregated returns totals rather than rows.
GET /admin/usage/pivot groups totals two ways at once, for a table:
Code
group_by accepts date, usage_user, agent_name, prompt_name or usage_param,
and time_granularity is day, week or month. Pass tz, or the buckets fall on
someone else's day boundaries.
GET /admin/usage/details returns the entries behind one cell of that pivot. This is the
drill-down: when a number looks wrong, open it to see the calls that produced it.
Shared filters
These endpoints share usage_user, usage_param, usage_timestamp (a time range) and
usage_details, plus agent_id and prompt_id on the detail view. One is worth calling
out:
usage_user=null is a real query, not an empty filter. The literal string
null matches entries with no user attached: scheduled work, autopilot runs,
anything the platform did on its own. Omitting the parameter returns every user's
rows instead, which is a different question with a similar-looking answer.
That bucket is where autonomous work appears. If usage climbed overnight and no user accounts for it, run that query.
Attribute spend
Usage entries carry the agent and prompt that produced them, which makes per-feature accounting possible without instrumenting your own side:
Code
This is the administrative view, so the key needs admin:usage:view. For an integration
reselling AI or billing its own customers, that grouping plus usage_user is the raw
material for an invoice.
What spends credits
Anything that runs a model. These are the easiest to underestimate:
POST /threads/{id}/messages | Every message, and every tool call it makes. |
POST /files/{id}/reanalyze and the bulk form | Per file. Re-analyzing a library is a real bill. |
| Generation | Images, infographics, decks. See generating content. |
POST /tasks/{id}/run-autopilot | Per run, and routines run unattended on a schedule. |
The /assist/* helpers | One call each. |
Two of these deserve a budget alarm rather than a spot check, because nobody is watching when they fire: scheduled routines and scheduled infographic refreshes. A weekly refresh across forty infographics is roughly five hundred model calls a quarter that nobody requested individually.
Next steps
- Plans and modules explains what your plan entitles.
- Autonomous AI covers the work that spends credits unattended.
- Rate limits is the other ceiling on model calls.
The product guide covers the same subject from the app's side: the usage screens, and the four habits that prevent most credit surprises.