Skip to main content
Every successful completion returns a usage object that counts the tokens the request consumed. On each of POST /v1/chat/completions, POST /v1/responses and POST /v1/messages, the usage carries a fixed set of keys in that endpoint’s own format, whichever provider served the request. The values in it, the cache counts especially, still depend on what that provider reports. Keys the serving provider adds on its own are returned alongside the fixed ones — see Provider keys.
The per-provider behaviour on this page was observed on 8 October 2026. It follows the serving provider, so it can change when a provider changes its API or when MeshAPI routes a model differently. To see which provider served a request, read event.provider from GET /v1/usage/requests/{request_id}.

​
Chat Completions usage

Every chat completion returns these keys:
The same keys appear on streamed and non-streamed responses. A count that is unused, or that the provider doesn’t report, is 0.
Deprecated: some responses also carry a top-level cache_creation_input_tokens. It duplicates prompt_tokens_details.cache_write_tokens and appears only on a cache write served by Bedrock, for example on Anthropic Claude or Amazon Nova models. Read cache_write_tokens instead.

​
Provider keys

Besides the fixed keys, usage carries any other key the serving provider reported, unchanged. For example:
Here prompt_cache_hit_tokens and prompt_cache_miss_tokens come from DeepSeek; the same count is also in cached_tokens. Other examples are OpenRouter’s is_byok and xAI’s num_sources_used. Provider keys can also appear inside prompt_tokens_details and completion_tokens_details.
  • Provider keys depend on the route. They differ by provider and can change or disappear when a provider changes its API or MeshAPI routes a model differently. Build on the fixed keys.
  • A fixed key always holds MeshAPI’s value. If a provider sends a key with the same name, MeshAPI’s value replaces it. OpenRouter’s is_byok describes OpenRouter’s own account. Read byok_used for whether your provider key served the request.
  • Provider cost figures are never returned. Read your charge from the Usage API instead — see the note under Summary.
The same rule applies on Responses and Messages.

​
What a 0 means

The keys are always present, but 0 can mean either “nothing happened” or “the provider doesn’t report this”:
  • A route that doesn’t report cache writes returns cache_write_tokens: 0 even when the provider cached the prompt.
  • A route that doesn’t report the 1-hour split returns cache_write_1h_tokens: 0 even after a 1-hour write.
The next section shows which routes report what.

​
Cache reporting by serving provider

Which cache counts are filled in on POST /v1/chat/completions, by the provider that served the request:
  • “No” means the count is always returned as 0 on that route. The provider may still cache; it just isn’t reported.
  • 1-hour writes on Amazon Nova are counted in cache_write_tokens, but cache_write_1h_tokens stays 0.
  • Cache reads are best-effort on providers that cache automatically (OpenAI, Google, DeepInfra, xAI, Qwen, Mistral). An identical repeat can still return cached_tokens: 0, and OpenAI can report a fresh write instead.
Which routes honour a cache_control marker in the first place is covered in Caching.

​
Examples

These are real usage blocks, reformatted only.

​
Splitting input tokens

prompt_tokens includes cached and cache-written tokens:
In the 1-hour write example above: 4701 − 0 − 4686 = 15 fresh tokens, and 4,686 tokens written with a 1-hour TTL. On Anthropic models, “other cache write” is the 5-minute TTL. What each kind of token costs is in What it costs.

​
Streaming

On a streamed chat completion, the usage object arrives on the final chunk. You don’t need stream_options.include_usage: MeshAPI requests usage from the provider on every stream. The keys are the same as on a non-streamed response. On a Responses stream, usage arrives on the closing response.completed or response.incomplete event, under response.usage. On a Messages stream, it arrives on message_delta. If the upstream fails partway through a stream, the response can end without a usage chunk.

​
Gateway cache hits

When the MeshAPI response cache answers a request: The usage object on a hit is not a count of new work: Check X-Cache before using usage for cost tracking. To always reach the provider, send X-Mesh-Cache: no-store. A Chat Completions hit on anthropic/claude-haiku-4.5, where the original response reported cache_write_tokens: 4687:

​
Responses API

Every POST /v1/responses response returns these keys, in the OpenAI Responses format:
The fields mean the same as their Chat Completions counterparts: Provider keys are returned alongside, as on Chat Completions. What each serving provider reports:
On this endpoint, an identical repeat can report another full cache write rather than a cache read.
Not every route can serve the Responses API. One that can’t returns 501 model_capability_not_supported — for example, google/gemini-2.5-flash on the Vertex route. GET /v1/responses/{id} returns the stored response as the provider kept it, so its usage is not in this format.

​
Messages API

Every POST /v1/messages response returns these keys, in Anthropic’s format:
All of these are present on every response, and 0 when unused. A cache read:
Total input is input_tokens + cache_creation_input_tokens + cache_read_input_tokens. Don’t apply this on a gateway cache hit, where input_tokens already holds the whole input. On a stream, the counts arrive on message_delta. message_start carries the same fixed keys as zeros — see Messages API. Provider keys are returned on the response body and on message_delta.

​
Summary

Usage tells you what was processed, not what you were charged. For the exact charge of a request, read event.cost_usd from GET /v1/usage/requests/{request_id}. That endpoint returns no per-request cache fields, so record usage from the response if you need them.
  • Caching — the gateway response cache and provider prompt caching, and what each costs
  • Usage & Monitoring API — usage, spend and per-request history
  • Pricing — how cached tokens are billed