Token accounting

anthropic.usage.input_tokens            ordinary prompt tokens, input rate
anthropic.usage.output_tokens           generated tokens, INCLUDING extended thinking
anthropic.usage.cache_creation_tokens   written into the prompt cache — premium rate
anthropic.usage.cache_read_tokens       served from the prompt cache — deep discount

Why two buckets is not enough

Cache creation is billed at a premium and cache reads at a deep discount. A tool that reports only input and output therefore cannot tell you what a request actually cost — a cache-dominated workload looks expensive when it is cheap, or the reverse.

Take a real shape from our conformance fixtures: 500 fresh input tokens, 220 output, and 40,000 cache reads. A two-bucket tool reports "40,500 input tokens." That is arithmetically true and completely useless — the overwhelming majority of those tokens were billed at the discounted cache rate.

The four buckets also give you cache-hit ratio, the single most actionable efficiency number available on an LLM workload:

cache_read / (input + cache_creation + cache_read)

For the example above that is 0.988 — and it is the number that tells you your prompt caching is working.

The one arithmetic trap

anthropic.thinking.tokens is a subset of output_tokens, not a fifth bucket. Adding it to a total double-counts and inflates every figure downstream.

The reference implementation excludes it from totals deliberately, and a test enforces that — it is the most likely cost bug in any system that consumes this spec.

total = input + output + cache_creation + cache_read     // thinking excluded

Cost is computed at ingest

Cost is calculated when a span arrives, against a versioned price book, and stored alongside the version that produced it.

Computing at read time would mean historical costs silently change whenever prices change — which makes every cost report untrustworthy. Storing the computed value with its price-book version is what makes a number from three months ago reproducible.