BillingReference

Usage fields and metering

Which numbers are read from the response and exactly how they become a charge.

By the end: You can reconcile a response's token counts against the amount deducted.

Metering is deliberately boring: read the token counts the provider reports, multiply by the published rates, and deduct exactly that. There are three details worth knowing.

1. Counts come from the response

The gateway takes prompt_tokens and completion_tokens (or the provider's equivalent) from the response body — or from the final stream event. It does not estimate from your request text when the provider has reported real numbers.

2. Silent providers are estimated, once

A few upstream responses carry no usage block at all. In that case the gateway estimates from the byte size of the request and the response, and — importantly — charges and records the same estimated figures. The log never says "0 tokens" while money moves.

3. Sub-cent precision is carried, not rounded away

A single short request against a cheap model can cost a fraction of a micro-dollar. Rounding each request up would overcharge someone sending many small requests, and rounding down would lose money over time. Instead the exact cost is accumulated per account, whole micro-dollars are deducted, and the remaining fraction is held for the next request. Over any sequence of requests the total deducted differs from the exact total by less than one micro-dollar.

This is why two requests with identical token counts can show slightly different deductions when viewed individually: the fractions are carried between them.

What is never charged

Model listing (GET /v1/models)
Token counting (/v1/messages/count_tokens)
Upstream failures — a 4xx or 5xx from the model service costs nothing

A request you cancel mid-stream is charged for what was generated before the cancellation, because the upstream service billed for it.