Why a single per-token price lies on your bill

A counter-intuitive but verifiable detail across the major SDKs: `prompt_tokens` is inclusive. It already contains tokens read from cache and tokens spent writing to it, not just "fresh" tokens. Same on the output side: `completion_tokens` includes reasoning tokens for a model that produces them.

Concretely: `prompt_tokens = fresh_input + cache_read + cache_creation`. Treating `prompt_tokens` as one uniform block and pricing it at the full rate means paying for a cache read — typically 5-10x cheaper than a fresh token on providers that expose it — at the price of a brand-new one.

On real prompt-caching traffic (a large system prompt, reused across dozens of turns), the delta between a flat rate and a per-category rate isn't a few percent — it's a multiplicative factor on the share of cost coming from replayed context. An agent replaying the same 20K-token context every turn can see its real bill drop by half once the breakdown is applied — the difference between buying the context every call and renting it.

Cache writes, conversely, usually cost more than a fresh token (the upfront cost of caching). A flat rate therefore underbills that specific category — the error runs both ways, not just one.

If a per-request cost feeds a hard limit — a monthly budget per integration, an overage alert — pricing it at the full rate punishes exactly the behavior you want to encourage: prompt caching. An integration doing the right thing (stable, reused context) gets cut off while spending, in real money, a fraction of what the counter shows.

Three distinct counters per request (cache read, cache write, reasoning), each a subset of the total — never additive. A per-category rate resolved from the model's pricing catalog, with an explicit fallback to the flat rate when a model doesn't publish the breakdown: better to overstate a cost than invent a discount the provider isn't actually giving.