Usage and cost

Every billable reply reports what the request used and what it cost, inside the reply itself. There is no separate usage endpoint to call and no header to read.

usage.cost is the amount charged to your organization for this request, in US dollars, as a JSON number. It already includes your discount, and no gateway fees are added on top.
usage.cost_details breaks that amount down by billable part (for example input_cost, output_cost, cached_input_cost). Its total_cost always equals usage.cost. Only the parts that apply to the request are present.
Token Plan organizations see the list price, which is what counts against the plan's allowance.
Errors (4xx/5xx) are not charged and carry no cost.
Units that do not apply to a model are left out rather than reported as zero, and a count the model did not report is left out rather than guessed.

The sections below list where usage appears on each endpoint and which fields it carries.

Text

Chat completions

POST /v1/chat/completions

Non-streaming: usage on the response.
Streaming: the last chunk before data: [DONE] carries the same usage object, with an empty choices array. Earlier chunks carry no usage.

Field	Meaning
`prompt_tokens`	Input tokens, including cached ones
`completion_tokens`	Output tokens, including reasoning tokens
`total_tokens`	`prompt_tokens + completion_tokens`
`prompt_tokens_details.cached_tokens`	Input tokens read from the prompt cache
`prompt_tokens_details.cache_write_tokens`	Input tokens written to the prompt cache
`prompt_tokens_details.image_tokens`, `audio_tokens`, `video_tokens`	Input tokens by modality, when the model reports them
`completion_tokens_details.reasoning_tokens`	Output tokens spent on reasoning
`completion_tokens_details.image_tokens`, `audio_tokens`	Output tokens by modality
`cost`, `cost_details`	Charged cost: `input_cost`, `output_cost`, `cached_input_cost`, `cache_write_input_cost`, `image_input_cost`, `image_output_cost`, `audio_input_cost`, `web_search_cost`, `request_cost`, `total_cost`

Messages

POST /v1/messages

Non-streaming: usage on the message.
Streaming: the message_delta event carries the final usage, including cost. message_start reports the input counts known when the stream begins.

Field	Meaning
`input_tokens`	Input tokens not read from or written to the cache
`output_tokens`	Output tokens, including thinking
`cache_read_input_tokens`	Input tokens read from the prompt cache
`cache_creation_input_tokens`	Input tokens written to the prompt cache, with `cache_creation.ephemeral_5m_input_tokens` and `ephemeral_1h_input_tokens` when a write happened
`server_tool_use.web_search_requests`	Web searches run for the request
`cost`, `cost_details`	Charged cost, with the same breakdown as chat completions

Responses

POST /v1/responses and POST /v1/responses/compact

Non-streaming: usage on the response.
Streaming: response.usage inside the response.completed event.
Retrieving a stored response (GET /v1/responses/{id}) is free. Its usage describes the original generation, which was charged when it ran.

Field	Meaning
`input_tokens`	Input tokens, including cached ones
`input_tokens_details.cached_tokens`	Input tokens read from the prompt cache
`output_tokens`	Output tokens, including reasoning
`output_tokens_details.reasoning_tokens`	Output tokens spent on reasoning
`total_tokens`	`input_tokens + output_tokens`
`cost`, `cost_details`	Charged cost, with the same breakdown as chat completions

Embeddings and decisions

These endpoints do not stream; usage is on the JSON response.

Endpoint	Fields
`POST /v1/embeddings`	`prompt_tokens`, `total_tokens`, `cost`, `cost_details` (`input_cost`, `request_cost`, `total_cost`)
`POST /v1/decisions`	`input_tokens`, `output_tokens`, `total_tokens`, `cost`, `cost_details` (`input_cost`, `request_cost`, `total_cost`). Output tokens are not charged.

Images

POST /v1/images/generations and POST /v1/images/edits do not stream; usage is on the JSON response.

Field	Meaning
`input_tokens`	Prompt and input-image tokens
`input_tokens_details.text_tokens`, `image_tokens`	Input tokens by modality
`output_tokens`	Generated tokens
`output_tokens_details.image_tokens`, `text_tokens`	Output tokens by modality
`total_tokens`	`input_tokens + output_tokens`
`cost`, `cost_details`	Charged cost, including `image_input_cost` and `image_output_cost`, or a per-image `request_cost` for models priced per image

Audio

Speech

POST /v1/audio/speech

Plain audio (default): the reply is the audio file itself, so it carries no usage. The request is still charged, and the charge appears in your logs and balance.
stream_format: "sse": available on every speech model. The audio arrives as speech.audio.delta events (base64 in audio), followed by exactly one speech.audio.done event whose usage reports the cost. Use this when you need the cost of each request.

Pricing	`speech.audio.done` usage
Per token	`input_tokens`, `output_tokens`, `total_tokens`, `cost`, `cost_details` (`input_cost`, `output_cost`, `request_cost`, `total_cost`)
Per character	`input_characters`, `cost`, `cost_details` (`input_cost`, `request_cost`, `total_cost`)

Transcriptions

POST /v1/audio/transcriptions returns JSON with usage: type: "duration", seconds (the billed audio length), cost and cost_details (audio_input_cost, request_cost, total_cost). The top-level duration is kept as well.

Video

POST /v1/videos starts a job. The create response carries no usage, because the job is charged when it finishes.

GET /v1/videos/{id} reports usage once the job has finished: cost and cost_details (video_output_cost, and image_input_cost for image-to-video). Every later status check returns the same cost.
A finished job can briefly report its final status before its usage appears. Check again until usage is present.
Jobs that fail, are cancelled or expire are not charged and report cost: 0.
With a callback URL, the completion callback carries the same usage.

Moderation, reranking, OCR and search

These endpoints do not stream; usage is on the JSON response. Each endpoint's own result fields are unchanged.

Endpoint	Fields
`POST /v1/moderations`	`cost`, `cost_details` (`request_cost`, `total_cost`)
`POST /v1/rerank`	`input_tokens` and `total_tokens` for models priced per token, `cost`, `cost_details` (`input_cost`, `request_cost`, `total_cost`)
`POST /v1/ocr`	`pages_processed`, `cost`, `cost_details` (`page_cost`, `request_cost`, `total_cost`)
`POST /v1/search`	`cost`, `cost_details` (`request_cost`, `total_cost`)

Logs and balance

The same cost is recorded on the request in your logs and debited from your balance shortly after the reply. Prices per model and unit are listed on the pricing page.