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

# API token usage (usage)

> Read token usage from Chat Completions, Responses, and Messages, including cache and reasoning counts and streaming usage events.

The `usage` object records token usage for a Model Inference API request. Field names and streaming events differ by protocol, so check the protocol and the fields actually returned before reading usage. Token totals alone are not enough to calculate costs.

## Where to read usage

| Protocol | Endpoint | Usage location |
| - | - | - |
| Chat Completions | `POST /chat/completions` | <ul><li>Non-streaming: top-level `usage`.</li><li>Streaming: if usage is returned, top-level `usage` in a `chat.completion.chunk` at the end of the stream.</li></ul> |
| Responses | `POST /responses` | <ul><li>Non-streaming: top-level `usage`.</li><li>Streaming: `response.usage` in a terminal `response.completed` or `response.incomplete` event, if present.</li></ul> |
| Messages | `POST /messages` | <ul><li>Non-streaming: top-level `usage`.</li><li>Streaming: initialize usage from `message_start.message.usage`, then merge fields from subsequent `message_delta.usage` events. Use the latest cumulative output count.</li></ul> |

> [!NOTE]
>
> Streaming usage and nested details can be absent depending on the model, request, or whether the response completed. In particular, do not assume that every Chat Completions stream includes a final usage chunk. See [Streaming](https://docs.scitix.ai/model-inference/models/streaming.md) for other streaming behavior.

## Understand token counts

* **Input and caching**

  * Chat Completions `prompt_tokens` and Responses `input_tokens` include cache reads and writes. Do not add cache details to these totals again.
  * Messages `input_tokens` counts ordinary input. Complete input is `input_tokens + cache_read_input_tokens + cache_creation_input_tokens`, provided all three fields contain numeric values.
  * Do not compare input counts across protocols without accounting for these differences.

* **Output and reasoning**

  `reasoning_tokens` or `thinking_tokens` is part of the corresponding output count, not additional usage. Do not add reasoning tokens to `completion_tokens` or `output_tokens` again.

* **Input modalities**

  Text counts toward input tokens. For models that support image input, images submitted in the protocol's supported format are converted to tokens and included in input usage. The fields listed here do not separate text from image input, so the input total alone cannot tell you how much came from each. The console's **Image Input** field shows image input usage; see [View usage](https://docs.scitix.ai/model-inference/usage/view-usage.md).

  This guide does not define audio-specific usage fields. See [Speech](https://docs.scitix.ai/model-inference/models/speech.md) and the model's documentation for audio formats and metering. Do not apply text or image accounting rules to audio requests.

* **Field states**

  `0` is a returned numeric value. An absent field or `null` is not zero and does not prove that no usage occurred. Check that optional fields exist and contain numeric values, and allow for new fields in responses.

* **Costs**

  Input, cache reads, cache writes, and output can have different prices. API usage fields and console billing items can also use different accounting definitions. See [Token usage and billing](https://docs.scitix.ai/model-inference/usage/billing.md) for pricing and billing rules.

## Client-side function tools

Models that support function calling can return function calls for your client to execute. These are not server-side tool counters. Each protocol returns client-side function calls in a different location:

| Protocol | Function call location |
| - | - |
| Chat Completions | `choices[].message.tool_calls` |
| Responses | Items in `output[]` with `type: function_call` |
| Messages | Blocks in `content[]` with `type: tool_use` |

Returning a client-side function call does not add a function execution counter to `usage`; the protocol's usual usage structure still applies. When you send a function result back to the model, it counts as input in the next request. Record each model request separately. Do not add local function executions to token totals or Messages `server_tool_use` counters.

## Chat Completions

### Non-streaming responses

Non-streaming responses return top-level `usage`. This example shows only the usage object:

```json theme={null}
{
  "usage": {
    "prompt_tokens": 8,
    "completion_tokens": 4,
    "total_tokens": 12,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "cache_write_tokens": 0
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0
    }
  }
}
```

| Field | Type | Availability | Description |
| - | - | - | - |
| `prompt_tokens` | integer | Always returned | Input tokens, including cache reads and writes. |
| `completion_tokens` | integer | Always returned | Output tokens, including any reasoning tokens generated. |
| `total_tokens` | integer | Always returned | Input plus output tokens for this request. |
| `prompt_tokens_details.cached_tokens` | integer | Conditional | Cached input tokens, already included in `prompt_tokens`. |
| `prompt_tokens_details.cache_write_tokens` | integer | Conditional | Input tokens written to cache, already included in `prompt_tokens`. |
| `completion_tokens_details.reasoning_tokens` | integer | Conditional | Tokens used for reasoning, already included in `completion_tokens`. |

When all counters contain numeric values, check the total with:

```text theme={null}
total_tokens = prompt_tokens + completion_tokens
```

If the endpoint and model support multiple candidates through `n`, `usage` covers all candidates: input is counted once, and output is summed across candidates. It is not usage for each individual candidate.

### Streaming responses

For endpoints and models that support `stream_options.include_usage`, set it to `true` to request usage. This request enables streaming and requests usage:

```json theme={null}
{
  "model": "Qwen/Qwen3.6-27B",
  "messages": [
    {
      "role": "user",
      "content": "Reply with exactly the word OK."
    }
  ],
  "max_completion_tokens": 64,
  "stream": true,
  "stream_options": {
    "include_usage": true
  }
}
```

A usage chunk can also arrive without `stream_options.include_usage`; rely on the actual response rather than assuming it will be returned.

Streaming responses use SSE chunks. This excerpt illustrates a final usage chunk and omits earlier content and other response fields. The counts are illustrative; not every stream returns this chunk.

```text theme={null}
data: {"object":"chat.completion.chunk","choices":[],"usage":{"prompt_tokens":8,"completion_tokens":4,"total_tokens":12}}

data: [DONE]
```

Check the top-level `usage` of each `chat.completion.chunk`. A separate final usage chunk may contain no message content, so read `usage` before skipping a chunk with empty `choices`. If the stream is interrupted or this chunk is absent, the received chunks alone cannot establish final usage.

In this example, input is `8`, output is `4`, and the total is `12`. `[DONE]` marks the end of the stream; it is not a JSON usage object. Read usage before this marker. Read any cache or reasoning details using the field definitions above.

## Responses

### Non-streaming responses

Non-streaming responses return top-level `usage`. This example shows only the usage object:

```json theme={null}
{
  "usage": {
    "input_tokens": 8,
    "input_tokens_details": {
      "cached_tokens": 0,
      "cache_write_tokens": 0
    },
    "output_tokens": 5,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 13
  }
}
```

| Field | Type | Availability | Description |
| - | - | - | - |
| `input_tokens` | integer | Always returned | Input tokens, including cache reads and writes. |
| `output_tokens` | integer | Always returned | Output tokens, including any reasoning tokens generated. |
| `total_tokens` | integer | Always returned | Input plus output tokens for this request. |
| `input_tokens_details.cached_tokens` | integer | Conditional | Cached input tokens, already included in `input_tokens`. |
| `input_tokens_details.cache_write_tokens` | integer | Conditional | Input tokens written to cache, already included in `input_tokens`. |
| `output_tokens_details.reasoning_tokens` | integer | Conditional | Tokens used for reasoning, already included in `output_tokens`. |

When all counters contain numeric values, check the total with:

```text theme={null}
total_tokens = input_tokens + output_tokens
```

### Streaming responses

Streaming events carry content and status. This SSE excerpt shows a successful terminal event, retaining only the event type and the three totals in `response.usage`. Earlier content deltas and other fields are omitted. Counts are illustrative.

```text theme={null}
event: response.completed
data: {"type":"response.completed","response":{"usage":{"input_tokens":8,"output_tokens":5,"total_tokens":13}}}
```

Read `response.usage` from a terminal `response.completed` or `response.incomplete` event if present, not from the event's top level. An interrupted stream may never deliver a terminal event or final usage. The length of text assembled by your client is not an exact token count.

## Messages

### Non-streaming responses

Messages uses different field names and cache accounting. This example shows only the usage object:

```json theme={null}
{
  "usage": {
    "input_tokens": 590,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0,
    "cache_creation": {
      "ephemeral_5m_input_tokens": 0,
      "ephemeral_1h_input_tokens": 0
    },
    "output_tokens": 4,
    "output_tokens_details": {
      "thinking_tokens": 0
    },
    "server_tool_use": {
      "web_search_requests": 0,
      "web_fetch_requests": 0
    },
    "service_tier": "standard",
    "inference_geo": "global"
  }
}
```

| Field | Type | Availability | Description |
| - | - | - | - |
| `input_tokens` | integer | Always returned | Ordinary input tokens, excluding cache reads and writes. |
| `cache_creation_input_tokens` | integer | Conditional | Input tokens written to cache for this request. |
| `cache_read_input_tokens` | integer | Conditional | Input tokens read from cache for this request. |
| `cache_creation` | object | Conditional | Cache writes broken down by TTL. Check that the object and its fields exist. |
| `cache_creation.ephemeral_5m_input_tokens` | integer | Conditional | Input tokens written to the 5-minute cache; part of `cache_creation_input_tokens`. |
| `cache_creation.ephemeral_1h_input_tokens` | integer | Conditional | Input tokens written to the 1-hour cache; part of `cache_creation_input_tokens`. This field can be absent when no tokens are written to this tier. |
| `output_tokens` | integer | Always returned | Output tokens, including any thinking tokens generated. |
| `output_tokens_details` | object | Conditional | Output details. Check that the object exists and is not `null`. |
| `output_tokens_details.thinking_tokens` | integer | Conditional | Tokens used for thinking, already included in `output_tokens`. |
| `server_tool_use` | object | Conditional | Server-side tool request counters. The object can be absent when no server-side tool is executed. |
| `server_tool_use.web_search_requests` | integer | Conditional | Web search requests for this request; not tokens or client-side function calls. |
| `server_tool_use.web_fetch_requests` | integer | Conditional | Web fetch requests for this request; not tokens. |
| `service_tier` | string | Conditional | Service tier used for this request, such as `standard`, `priority`, or `batch`. |
| `inference_geo` | string | Conditional | Execution geography for this request; an example value is `global`. |

Availability of `cache_creation_input_tokens` and `cache_read_input_tokens` depends on the model and request. Do not treat absent or `null` fields as `0`, or use `input_tokens` alone to determine complete input usage.

If all three input counters contain numeric values, calculate complete input as follows. Paths are relative to `usage`:

```text theme={null}
Complete input = input_tokens + cache_creation_input_tokens + cache_read_input_tokens
```

#### Cache write TTL tiers

TTL is the cache's lifetime. For Messages requests that support cache breakpoints through `cache_control`, omitting the TTL uses the 5-minute tier. Specifying `{"type":"ephemeral","ttl":"1h"}` uses the 1-hour tier. Check the model for cache availability and supported request parameters.

A request can write to both tiers: different breakpoints can have different TTLs. When the total and both tier counters contain numeric values, check the following relationship. Do not add the tier counts to cache creation or complete input again.

```text theme={null}
cache_creation_input_tokens = cache_creation.ephemeral_5m_input_tokens + cache_creation.ephemeral_1h_input_tokens
```

For example, if the 1-hour field is absent, do not substitute `0` to check this equation. Chat Completions and Responses `cache_write_tokens` provide only aggregate writes. The fields listed here do not split that count by TTL, so you cannot derive each tier's usage from the aggregate.

#### Reasoning usage and response metadata

When reasoning details contain numeric values, they should satisfy:

```text theme={null}
output_tokens_details.thinking_tokens <= output_tokens
```

Search and fetch counts in `server_tool_use` are server-side tool requests, not tokens. Do not include them in input or output token totals.

`service_tier` and `inference_geo` are response metadata, not token counts. Their values alone do not establish prices, selectable service tiers, or geography configuration options. See [Prompt caching](https://docs.scitix.ai/model-inference/models/prompt-caching.md) and [Token usage and billing](https://docs.scitix.ai/model-inference/usage/billing.md) for cache policies, hit conditions, and pricing.

### Streaming responses

Usage can arrive in the start event and later events. This SSE excerpt omits content blocks and other fields. Counts are illustrative; the two `message_delta` events demonstrate cumulative output handling, not a fixed number of events per request.

```text theme={null}
event: message_start
data: {"type":"message_start","message":{"usage":{"input_tokens":590,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":0}}}

event: message_delta
data: {"type":"message_delta","usage":{"output_tokens":2}}

event: message_delta
data: {"type":"message_delta","usage":{"output_tokens":4}}

event: message_stop
data: {"type":"message_stop"}
```

Initialize usage from `message_start.message.usage`, then merge individual fields from later `message_delta.usage` events. Start-event input counters are not necessarily final, and output need not start at `0`. Output is **cumulative**: use the latest value, **not the sum of the deltas**.

In this example, complete input is `590 + 0 + 0 = 590`, and final output is `4`, not `2 + 4 = 6` or the start-event value of `0`. The `message_stop` event marks the end of the message; it does not require you to recalculate usage.

Fields such as `cache_creation`, `output_tokens_details.thinking_tokens`, `service_tier`, and `inference_geo` can arrive in the start event or later events. Merge nested fields individually and preserve values that later events omit. Do not replace accumulated usage with the last partial delta.

Keep `0`, missing fields, and `null` distinct; do not fill missing or `null` values with zero. If the stream is interrupted, the last delta you received may not contain final usage.

## FAQ

> [accordion] Why are some usage fields missing?
>
> Nested details and optional fields depend on the model, request, and response completeness. A sample from one model does not establish which fields other models return. Their absence does not prove that the model lacks a capability or that no usage occurred.
>
> Check for each field and its type before reading it; do not fill missing details with zero.

> [accordion] Are reasoning tokens additional output tokens?
>
> No. Chat Completions `reasoning_tokens`, Responses `reasoning_tokens`, and Messages `thinking_tokens` are included in their respective output counts. Do not add them again.
>
> If output and reasoning counts are both numeric, subtract reasoning from output to approximate non-reasoning output. For example, use `completion_tokens - completion_tokens_details.reasoning_tokens` for Chat Completions. This difference is not guaranteed to match tokenizing the text visible to your client. Do not subtract zero when the detail is absent.

> [accordion] Why do cache fields keep returning zero?
>
> Distinguish reads from writes. A returned cache read count of `0` means zero cache reads were recorded; a cache write count of `0` means zero writes were recorded. Zero writes alone do not tell you whether a cache hit occurred.
>
> For models that support caching, misses can result from a prompt below the minimum length, a changed prefix, or an expired cache. Check the model's conditions and keep reusable prefixes and message order stable. Hits are not guaranteed, even for repeated requests. An absent or `null` field means there is no readable value, not zero usage. See [Prompt caching](https://docs.scitix.ai/model-inference/models/prompt-caching.md).

> [accordion] Should I add cache counts to total\_tokens?
>
> No. Chat Completions and Responses already include cache reads and writes in input, and `total_tokens` is input plus output. Adding cache counts again would double-count them.
>
> The Messages usage fields listed here do not include `total_tokens`. To obtain complete input, add `input_tokens + cache_creation_input_tokens + cache_read_input_tokens` only when all three are numeric. To record input plus output, add `output_tokens` once if it is also numeric. Do not add TTL subtotals or `thinking_tokens` again.

> [accordion] Which fields show 5-minute and 1-hour cache writes?
>
> Messages exposes the following fields. Both are part of `cache_creation_input_tokens`:
>
> | Cache write tier | Field in `usage` |
> | - | - |
> | 5 minutes | `cache_creation.ephemeral_5m_input_tokens` |
> | 1 hour | `cache_creation.ephemeral_1h_input_tokens` |
>
> Chat Completions `prompt_tokens_details.cache_write_tokens` and Responses `input_tokens_details.cache_write_tokens` provide only aggregate writes, not separate counts for these tiers. To check tier-specific charges, consult the billing records rather than inferring the split from the aggregate.

> [accordion] Can all three protocols share the same usage parser?
>
> Do not use identical field mappings and formulas directly. Field names, cache accounting, and streaming usage locations differ. In particular, Messages ordinary input excludes cache reads and writes, while Chat Completions and Responses input already includes them.
>
> You can store normalized usage in your application, but parse each protocol separately first. For streaming, handle Chat Completions final usage chunks, Responses terminal events, and Messages start and partial update events separately. Use the latest cumulative output count for Messages.

> [accordion] How do zero, absent, and null differ?
>
> * `0`: a returned numeric value recording zero usage for that field.
> * Absent: the response does not provide the field. This does not prove that the model lacks the capability or that no usage occurred.
> * `null`: the field exists but has no readable numeric value. It is not zero.
>
> Do not normalize all three states to `0` or use missing details to verify totals. Allow unknown new fields in your client, but calculate usage only from fields whose meanings and types are defined.

> [accordion] Why does API usage differ from Usage Detail?
>
> The console's **Usage Detail** shows uncached input separately from cache reads and writes. Chat Completions `prompt_tokens` and Responses `input_tokens` already include cache-related input. Do not compare either API input total directly with the console's input column or add cache usage to that API total again.

> [accordion] Does a missing final usage object mean no usage occurred?
>
> No. An interrupted stream or client disconnect can prevent final usage from reaching your client. Once a request reaches the model and inference starts, disconnecting does not stop generation. All generated output is recorded and billed, including output generated after the disconnect. See [Token usage and billing](https://docs.scitix.ai/model-inference/usage/billing.md).
>
> Usage records may appear only after generation finishes. Check the request's usage and costs in [View usage](https://docs.scitix.ai/model-inference/usage/view-usage.md) later. Do not resend the same request solely because the final usage chunk is missing.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.