Usage and billing

The usage object is the number you are billed on, not an estimate of it.

Most inference APIs return token counts that are about what you were charged. Here they are what you were charged — the same three numbers land in your invoice and in the console, and they come from one record, not from two systems that are supposed to agree.

That is a design rule, not a coincidence, and it is the thing to hold us to.

What comes back

"usage": {
  "prompt_tokens": 28,
  "completion_tokens": 47,
  "total_tokens": 75,
  "prompt_tokens_details": { "cached_tokens": 0 }
}

Field	Meaning
prompt_tokens	Everything you sent: system, messages, tool definitions, and any images converted to tokens
completion_tokens	Everything generated, including tool-call arguments
total_tokens	The sum. It is not a separate measurement
prompt_tokens_details.cached_tokens	The part of the prompt served from cache

On /v1/messages the same numbers arrive as input_tokens and output_tokens, because an Anthropic SDK is parsing them.

Streaming does not cost you these numbers. The final data event carries usage whether or not you asked for it — see Streaming.

What a failed call costs

Almost always nothing. of the errors this API can return are free; are not, and both are streams that came apart after the model had already produced output.

That is a deliberately narrow exception. A rejected request, a model that was not available, a rate limit, a request that never reached a model — none of those produce a usage record, because none of them spent anything worth charging you for.

The per-code table is on Errors.

Seeing it again

Everything above is visible in the console after the call:

• Requests — per call, with its x-request-id, model, tokens and outcome. This is the page to open when a number surprises you.
• Analytics — the same usage aggregated by day, model and API key, with a cost view beside it.
• Billing — credits, spending limit, auto-reload, invoices.

Because it is the same record rather than a parallel log, a request you can see in your own logs is a request you can find there by its id.

Credits and limits

Inference draws on credits. Two settings decide what happens when they run low, and both produce errors that are not retryable, because nothing about waiting changes them:

Code	Meaning	What fixes it
INSUFFICIENT_BALANCE	Credits exhausted	Add credits, or turn on auto-reload
TENANT_BUDGET_EXCEEDED	Your own spending limit reached	Raise it, or wait for the period to roll
PAYMENT_REQUIRED	A payment is overdue	Update the payment method

TENANT_BUDGET_EXCEEDED arrives as a 429. It is a guardrail you asked for, not congestion — and a client that retries every 429 will never get past it. See Reliability.

Attributing spend

Two handles, and they behave differently:

• One API key per deployment or environment. Usage is attributed per key in the console, so staging and production separate without you sending anything extra.
• The user field (or metadata.user_id on /v1/messages) is echoed into that request’s log line so you can correlate with your own records. It is not kept on the usage record, so it cannot be used to break down a bill.

Next

Rate limits and quotas

What throttles you before money does.

Errors

Every code, with its billing column.