> ## Documentation Index
> Fetch the complete documentation index at: https://docs.compute.prentis.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Usage and billing

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

export const freeErrors = 26;

export const billedErrors = 2;

export const dataErrors = 28;

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

```json theme={null}
"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](/vision) 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.

<Note>
  Streaming does not cost you these numbers. The final data event carries `usage` whether
  or not you asked for it — see [Streaming](/streaming).
</Note>

## What a failed call costs

Almost always nothing. **{freeErrors} of the {dataErrors} errors this API can return are
free**; {billedErrors} 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](/errors).

## Seeing it again

Everything above is visible in the [console](https://compute.prentis.ai) 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                |

<Warning>
  `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](/reliability).
</Warning>

## 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

<CardGroup cols={2}>
  <Card title="Rate limits and quotas" icon="gauge" href="/rate-limits-and-quotas">
    What throttles you before money does.
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/errors">
    Every code, with its billing column.
  </Card>
</CardGroup>