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
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 for other streaming behavior.
Understand token counts
-
Input and caching
- Chat Completions
prompt_tokensand Responsesinput_tokensinclude cache reads and writes. Do not add cache details to these totals again. - Messages
input_tokenscounts ordinary input. Complete input isinput_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.
- Chat Completions
-
Output and reasoning
reasoning_tokensorthinking_tokensis part of the corresponding output count, not additional usage. Do not add reasoning tokens tocompletion_tokensoroutput_tokensagain. - 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. This guide does not define audio-specific usage fields. See Speech and the model’s documentation for audio formats and metering. Do not apply text or image accounting rules to audio requests.
-
Field states
0is a returned numeric value. An absent field ornullis 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 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:
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-levelusage. This example shows only the usage object:
When all counters contain numeric values, check the total with:
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 supportstream_options.include_usage, set it to true to request usage. This request enables streaming and requests usage:
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.
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-levelusage. This example shows only the usage object:
When all counters contain numeric values, check the total with:
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 inresponse.usage. Earlier content deltas and other fields are omitted. Counts are illustrative.
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:
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:
Cache write TTL tiers
TTL is the cache’s lifetime. For Messages requests that support cache breakpoints throughcache_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.
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: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 and Token usage and billing 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 twomessage_delta events demonstrate cumulative output handling, not a fixed number of events per request.
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
Why are some usage fields missing?
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.
Are reasoning tokens additional output tokens?
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.Why do cache fields keep returning zero?
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.Should I add cache counts to total_tokens?
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.Which fields show 5-minute and 1-hour cache writes?
Which fields show 5-minute and 1-hour cache writes?
Messages exposes the following fields. Both are part of
cache_creation_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.How do zero, absent, and null differ?
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.
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.Why does API usage differ from Usage Detail?
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.Does a missing final usage object mean no usage occurred?
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.Usage records may appear only after generation finishes. Check the request’s usage and costs in View usage later. Do not resend the same request solely because the final usage chunk is missing.

