# Usage accounting

> What you're charged for, what every usage field means, how cost is calculated, and how to look up the record of any request.

Source: https://0.0.0.0:3000/docs/account/usage-accounting
Documentation index: https://0.0.0.0:3000/docs/llms.txt

Every response reports what was measured and what it cost, in the key's currency. [`GET /generation`](#look-up-a-generation) returns the authoritative record of any request after the fact.

## What you're charged for

You pay for output delivered to you, at the offer's listed rates, based on the provider's reported usage as validated by Numes.

- **No output, no charge.** A request that fails before delivering output costs nothing, and the funds held for it are released.
- **Only the endpoint that delivers is charged.** If one endpoint fails before output and another then serves the request, you pay only for the one that served it. Output from two endpoints is never combined. See [Fallbacks](/docs/routing/fallbacks).
- **Delivered output is charged whatever it says.** A refusal, or output that fails your own validation such as invalid JSON, is charged like any other response.

[`GET /generation`](#look-up-a-generation) is the authoritative record of what each request delivered and cost.

## The usage object

Every buffered response and the final chunk of every stream include `usage`. It can't be switched off; `stream_options.include_usage` and `usage.include` are accepted and ignored.

```json title="usage"
{
  "prompt_tokens": 1204,
  "completion_tokens": 312,
  "total_tokens": 1516,
  "token_count_basis": "provider_native",
  "native_tokens": {
    "prompt_tokens": 1204,
    "completion_tokens": 312,
    "reasoning_tokens": 0,
    "cache_read_tokens": 1024
  },
  "cost": 0.002667,
  "cost_details": { "upstream_inference_cost": 0.002667 },
  "prompt_tokens_details": { "cached_tokens": 1024 },
  "completion_tokens_details": { "reasoning_tokens": 0 }
}
```

:::fields usage
- `prompt_tokens` `integer` — Billed input tokens.
- `completion_tokens` `integer` — Billed output tokens, including any reasoning.
- `total_tokens` `integer` — `prompt_tokens + completion_tokens`.
- `token_count_basis` `string` — `provider_native` when the counts are the provider's validated token counts, `gateway_estimate` otherwise.
- `native_tokens` `object` — The provider's validated token counts, when reported.
  - `prompt_tokens` `integer` — Input tokens.
  - `completion_tokens` `integer` — Output tokens.
  - `reasoning_tokens` `integer` — Reasoning tokens within the output, when reported.
  - `cache_read_tokens` `integer` — Input tokens read from the provider's cache, when reported.
  - `cache_write_tokens` `integer` — Input tokens written to the provider's cache, when reported.
- `gateway_billing_units` `object` — Billed quantities on some older requests, with `prompt_units`, `completion_units` and `reasoning_units`. Absent on current requests.
- `usage_meter` `string` — An identifier of the offer's billing basis. Treat it as opaque.
- `cost` `number` — Total charge in the key's currency: US dollars for USD keys, sats for BTC keys.
- `cost_details` `object` — Breakdown of `cost`.
  - `upstream_inference_cost` `number` — The provider's share of `cost`.
- `prompt_tokens_details` `object` — Cache split of the input, when known.
  - `cached_tokens` `integer` — Tokens read from cache.
  - `cache_write_tokens` `integer` — Tokens written to cache.
- `completion_tokens_details` `object` — Present when the reasoning split is known.
  - `reasoning_tokens` `integer` — Reasoning tokens within the output.
- `input_images` `integer` — Input images. Only when non-zero.
- `output_images` `integer` — Generated images. Only when non-zero.
- `input_audio_seconds` `number` — Input audio duration. Only when non-zero.
- `output_audio_seconds` `number` — Output audio duration. Only when non-zero.
- `hosted_tool_usage` `object` — Hosted-tool quantities by billed item, such as a number of searches. Only when a hosted tool was billed.
:::

Dedicated media endpoints report usage in their own units: images for [image generation](/docs/multimodal/image-generation), input characters and output audio seconds for [speech](/docs/multimodal/speech), and audio seconds for [transcription](/docs/multimodal/audio). [Embeddings](/docs/multimodal/embeddings) report `prompt_tokens`, `total_tokens` and `cost`.

## How cost is calculated

```text
cost = Σ (billed quantity × offer rate)   for each priced dimension
```

- **Offer rates** are the per-unit prices in [`GET /models`](/docs/api-reference/models/list-models) and the endpoints list: per input and output token, plus any per-request, image, audio, cache, reasoning or hosted-tool rate.
- **No markup on requests.** The platform fee is charged when you buy credits, so `cost_details.upstream_inference_cost` equals `cost`. See [Credits and payments](/docs/account/credits).
- **Prices are locked per request.** A price change while a request runs doesn't affect it.
- **Reasoning** counts as output, charged at the offer's reasoning rate when it has one and at the output rate otherwise. See [Reasoning](/docs/features/reasoning).
- **Prompt caching.** Input read from or written to the provider's cache is charged at the offer's cache rates, which are never higher than its input rate, based on the cache usage Numes accepts from the provider's response. The saving appears as `cache_discount` on the generation and **Saved by cache** in Logs. See [Prompt caching](/docs/features/prompt-caching).

### Exact decimals

Costs are exact decimal values in the key's currency, written as JSON numbers. Parse them as decimals if you add them up, for example with `json.loads(text, parse_float=Decimal)` in Python. Never add USD and BTC amounts together.

## Reservations

Before a request runs, an upper bound of its cost is held against your balance and spending limits. Unused funds are released when it completes, and only the actual charge is taken. A request whose upper bound exceeds your available funds or a spending limit is rejected with `402` before it runs. See [Credits and payments](/docs/account/credits#reservations).

## Usage in streams

A successful stream ends with a usage-only chunk whose `choices` array is empty, followed by `data: [DONE]`. If a stream ends with an error or your connection drops, there's no usage chunk; look up the generation instead. See [Streaming](/docs/features/streaming) for the event format.

## Look up a generation

`GET /generation` returns the record of one request: outcome, delivery, final usage, cost and every endpoint tried. After a disconnect or a mid-stream error, it's the authoritative record of what was delivered and charged.

```endpoint
GET /api/v1/generation
```

The generation ID is the `id` of a chat completion and the value of the `X-Generation-Id` response header, present on every response that started delivering. Call it with an inference key from the same account; another account's generation returns `404`.

```request
{
  "method": "GET",
  "path": "/generation",
  "query": { "id": "0f5b5c9a-3a7e-4c6f-9b1d-2e8f7a6c5d41" }
}
```

:::details Show an example response
```json
{
  "data": {
    "id": "0f5b5c9a-3a7e-4c6f-9b1d-2e8f7a6c5d41",
    "request_id": "7c1e0a9b2d3f4e5a6b7c8d9e0f1a2b3c",
    "model": "openai/gpt-6-luna",
    "provider_name": "Example Provider",
    "provider_slug": "example-provider",
    "endpoint": "example-provider/primary",
    "created_at": "2026-09-28T10:15:02Z",
    "completed_at": "2026-09-28T10:15:05Z",
    "outcome": "success",
    "streamed": true,
    "cancelled": false,
    "delivered_output": true,
    "usage": {
      "prompt_tokens": 1204,
      "completion_tokens": 312,
      "total_tokens": 1516,
      "cost": 0.002667,
      "cost_details": { "upstream_inference_cost": 0.002667 }
    },
    "total_cost": 0.002667,
    "upstream_inference_cost": 0.002667,
    "cache_discount": 0.000921,
    "attempts": [
      {
        "ordinal": 1,
        "provider_name": "Other Provider",
        "provider_slug": "other-provider",
        "endpoint": "other-provider/main",
        "dispatch_state": "confirmed",
        "financial_status": "finalized",
        "outcome": "failed",
        "failure_class": "rate_limited",
        "delivered_output": false,
        "cancelled": false,
        "usage": { "prompt_tokens": 0, "completion_tokens": 0 },
        "total_cost": 0,
        "upstream_inference_cost": 0
      },
      {
        "ordinal": 2,
        "provider_name": "Example Provider",
        "provider_slug": "example-provider",
        "endpoint": "example-provider/primary",
        "dispatch_state": "confirmed",
        "financial_status": "finalized",
        "outcome": "success",
        "delivered_output": true,
        "cancelled": false,
        "usage": { "prompt_tokens": 1204, "completion_tokens": 312, "cache_read_tokens": 1024 },
        "total_cost": 0.002667,
        "upstream_inference_cost": 0.002667
      }
    ]
  }
}
```
:::

:::fields Response `data`
- `id` `string` — Generation ID (a UUID).
- `request_id` `string` — The request's `X-Request-Id`.
- `model` `string` — Requested model ID.
- `provider_name` `string | null` — Display name of the provider that served the response; `null` if none did.
- `provider_slug` `string | null` — Routing slug of that provider.
- `endpoint` `string | null` — The serving endpoint as a `provider/endpoint` routing selector.
- `created_at` `string` — When the request was accepted.
- `completed_at` `string | null` — When it finished; `null` while running.
- `outcome` `string` — Final result; see the table below.
- `streamed` `boolean` — Whether the request used streaming.
- `cancelled` `boolean` — Whether you cancelled or disconnected.
- `delivered_output` `boolean` — Whether any billable output reached you.
- `usage` `object` — Final billed usage, in the same shape as the response `usage` without the provider's raw counts.
- `usage_meter` `string` — Opaque identifier of the billing basis.
- `total_cost` `number` — Total charge in the key's currency.
- `upstream_inference_cost` `number` — The provider's share of `total_cost`.
- `cache_discount` `number` — Amount saved by prompt caching.
- `attempts` `object[]` — Every endpoint tried, in order.
  - `ordinal` `integer` — Attempt number, starting at 1. Numbers can have gaps.
  - `provider_name` `string` — Display name of the provider tried.
  - `provider_slug` `string` — Routing slug of the provider tried.
  - `endpoint` `string` — Endpoint tried, as `provider/endpoint`.
  - `dispatch_state` `string` — `confirmed` when the request reached the provider, `uncertain` when that couldn't be confirmed.
  - `financial_status` `string` — `finalized`, or `pending` while the charge is being finalized.
  - `outcome` `string` — Result of this attempt.
  - `failure_class` `string` — Short code for why it failed, such as `rate_limited`. Omitted on success.
  - `delivered_output` `boolean` — Whether this attempt delivered billable output.
  - `cancelled` `boolean` — Whether the attempt ended because of a cancel.
  - `usage` `object` — Billed quantities for this attempt: `prompt_tokens`, `completion_tokens`, and when present `reasoning_tokens`, `cache_read_tokens`, `cache_write_tokens`, `input_images`, `output_images` and `input_audio_milliseconds`. Zero while pending.
  - `total_cost` `number` — What this attempt cost. Absent while pending.
  - `upstream_inference_cost` `number` — The provider's share. Absent while pending.
:::

| `outcome` | Meaning |
| --- | --- |
| `in_progress` | Still running, or the charge isn't final yet; usage and cost read zero |
| `success` | Completed and delivered |
| `cancelled` | You cancelled or disconnected |
| `partial_failure` | Failed after some output was delivered |
| `failed` | Failed before any output; not charged |
| `delivery_failure` | The response couldn't be fully delivered |
| Any other value | The request ended without a normal result |

For every outcome, `total_cost` is what you were charged. A pending charge isn't the same as zero: poll again until `financial_status` is `finalized`.

The record never contains prompt or response content, keys or session IDs.

## Usage in the dashboard

Every request also appears in [Logs](/dashboard/logs) with its **Usage and cost** panel. See [Activity and logs](/docs/account/activity).

## Next steps

:::cards
- {coins} [Credits and payments](/docs/account/credits) Balances, reservations and spending limits.
- {waves} [Streaming](/docs/features/streaming) The event format and cancellation.
- {database} [Prompt caching](/docs/features/prompt-caching) Earn cache discounts.
- {activity} [Activity and logs](/docs/account/activity) Explore spend across keys, models and apps.
- {code} [Get a generation](/docs/api-reference/chat/get-generation) Full schema of the generation record.
:::