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

# Tokens and Usage

> Understand how token usage, cached tokens, and reasoning tokens are reported in the Responses API.

`Responses API` gives you one of the clearest usage breakdowns in the docs.

Use it to understand how much input, output, cached, and reasoning usage each request consumed.

## Usage Shape

Every successful non-streaming response includes a `usage` object at the root level.

```json theme={null}
{
  "object": "response",
  "status": "completed",
  "output": [...],
  "usage": {
    "input_tokens": 125,
    "input_tokens_details": {
      "cached_tokens": 100
    },
    "output_tokens": 45,
    "output_tokens_details": {
      "reasoning_tokens": 15
    },
    "total_tokens": 170
  }
}
```

## Field breakdown

* `input_tokens`: The total number of tokens sent in the prompt, including images or documents.
* `input_tokens_details.cached_tokens`: The portion of `input_tokens` that the upstream provider successfully cached from previous requests. These are billed at a discounted rate.
* `output_tokens`: The total number of tokens generated by the model, including hidden "thinking" tokens.
* `output_tokens_details.reasoning_tokens`: The portion of `output_tokens` that the model spent "thinking" before generating the visible answer. These are billed at the standard output rate.
* `total_tokens`: The sum of all input and output tokens (`input_tokens` + `output_tokens`).

## Streaming Usage

When you use `stream: true`, usage is not delivered token by token during the stream. It arrives with the final completed response snapshot.

You do not need a separate chat-style `stream_options` flag on this surface.

<CodeGroup>
  ```json Example Streaming Event theme={null}
  event: response.completed
  data: {"object":"response","status":"completed","output":[...],"usage":{"input_tokens":125,"output_tokens":45,"total_tokens":170,...}}
  ```
</CodeGroup>

## Practical Advice

* When using models with high context windows, actively monitor `input_tokens_details.cached_tokens`. A high ratio of cached tokens means your prompt design is highly cost-efficient.
* If you notice latency spikes or unexpected costs when using models that support reasoning effort, check `output_tokens_details.reasoning_tokens` to see how much budget the model spent planning its answer.
* Always log the `usage` object in your application database alongside the request metadata. It is the most reliable way to attribute costs to specific features or users before running aggregate reports against `/v1/account/activity`.

## Common mistakes

* only logging final text and ignoring usage metadata
* assuming streamed text deltas contain usage as they arrive
* treating reasoning tokens and visible output tokens as the same optimization problem

## Related Docs

* [Capabilities: Tokens and Usage](/build/tokens-and-usage)
* [Responses API](/api/responses)
* [Pricing and Billing](/build/billing)