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

> Usage tracking in the Chat Completions compatibility layer.

`Chat Completions API` reports usage in the familiar OpenAI chat format.

Use this page if your app logs `prompt_tokens`, `completion_tokens`, or chat-style streaming usage today.

## Non-Streaming Usage

For non-streaming requests, every successful completion includes a `usage` object at the root level of the response.

```json theme={null}
{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-4.1-mini",
  "choices": [...],
  "usage": {
    "prompt_tokens": 194,
    "completion_tokens": 2,
    "total_tokens": 196
  }
}
```

## Field breakdown

* `prompt_tokens`: The number of tokens in the prompt (input). This correlates directly with input token pricing.
* `completion_tokens`: The number of tokens in the generated completion (output). This correlates directly with output token pricing.
* `total_tokens`: The sum of `prompt_tokens` and `completion_tokens`.

<Note>
  If the model supports prompt caching or reasoning efforts, their respective metrics may also appear in nested fields depending on the exact OpenAI version you are targeting, such as `prompt_tokens_details.cached_tokens`.
</Note>

## Streaming Usage

By default, the OpenAI chat protocol **does not** include a `usage` block when streaming.

If your application needs to calculate costs or track token consumption while using `stream: true`, you must explicitly request the usage data by setting `stream_options.include_usage` to `true`.

## How to request streaming usage

<CodeGroup>
  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      base_url="https://api.naga.ac/v1",
      api_key="YOUR_API_KEY",
  )

  stream = client.chat.completions.create(
      model="gpt-4.1-mini",
      messages=[{"role": "user", "content": "Hello!"}],
      stream=True,
      stream_options={"include_usage": True}
  )

  for chunk in stream:
      if chunk.usage:
          print(f"Prompt tokens: {chunk.usage.prompt_tokens}")
          print(f"Completion tokens: {chunk.usage.completion_tokens}")
  ```

  ```javascript Node.js theme={null}
  import OpenAI from 'openai';

  const client = new OpenAI({
    baseURL: 'https://api.naga.ac/v1',
    apiKey: 'YOUR_API_KEY',
  });

  const stream = await client.chat.completions.create({
    model: 'gpt-4.1-mini',
    messages: [{ role: 'user', content: 'Hello!' }],
    stream: true,
    stream_options: { include_usage: true }
  });

  for await (const chunk of stream) {
    if (chunk.usage) {
      console.log(`Prompt tokens: ${chunk.usage.prompt_tokens}`);
      console.log(`Completion tokens: ${chunk.usage.completion_tokens}`);
    }
  }
  ```

  ```bash cURL theme={null}
  curl https://api.naga.ac/v1/chat/completions \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4.1-mini",
      "messages": [{"role": "user", "content": "Hello!"}],
      "stream": true,
      "stream_options": {"include_usage": true}
    }'
  ```
</CodeGroup>

When enabled, the server will emit an additional chunk at the very end of the stream (just before `[DONE]`) that contains a null `choices` array and the populated `usage` object.

```json Example Streaming Usage Chunk theme={null}
{
  "id": "chatcmpl-123",
  "object": "chat.completion.chunk",
  "created": 1694268190,
  "model": "gpt-4.1-mini",
  "choices": [],
  "usage": {
    "prompt_tokens": 194,
    "completion_tokens": 2,
    "total_tokens": 196
  }
}
```

## Practical Advice

* When using streaming, remember that the usage chunk has an empty `choices` array. Your client logic should safely handle `choices` being empty or null on the final chunk before attempting to access `chunk.usage`.
* 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

* forgetting to enable `stream_options.include_usage` when streaming
* assuming the final usage chunk contains normal message deltas
* only tracking total tokens and ignoring prompt vs completion growth separately

## Related Docs

* [Capabilities: Tokens and Usage](/build/tokens-and-usage)
* [Chat Completions API](/api/chat-completions)
* [Streaming](/api/chat-completions/streaming)
* [Pricing and Billing](/build/billing)