Your cache hit rate is cache read tokens divided by total input tokens, where total input is cache reads plus cache writes plus uncached input. Log the three fields from every response, aggregate by feature, and watch the ratio over time. A low or falling ratio means the prefix is changing.
The fields
The Claude usage object reports cache_read_input_tokens, cache_creation_input_tokens, and input_tokens. The documentation notes that input_tokens only counts tokens after the last cache breakpoint, so it is not total input on its own. Total input is the sum of the three. A 200,000 token cached document plus a 50 token question shows input_tokens of 50.
There is also a cache_creation breakdown that splits writes into five minute and one hour entries.
A small calculation
def cache_hit_rate(usage):
read = usage.get("cache_read_input_tokens", 0)
write = usage.get("cache_creation_input_tokens", 0)
fresh = usage.get("input_tokens", 0)
total = read + write + fresh
return read / total if total else 0.0
Do not average per request ratios. Sum reads and totals across a window, then divide, so large requests carry their true weight.
Slice it by the right keys
One blended number hides problems. Record the feature name, model, workspace, and prompt template version next to each usage record. Then compare:
- By feature: which flows get hits and which never do.
- By template version: did last week's prompt edit break the prefix?
- By hour: do hits drop when traffic gets quiet and entries expire?
Reading the result
- Zero reads and zero writes: the prompt is under the minimum length, or no breakpoint is set.
- Writes on every request, no reads: the prefix changes, or traffic gaps exceed the lifetime.
- Reads high, then a sudden drop: a deploy changed something early in the prompt, such as a tool description.
- Healthy ratio, high bill anyway: the cost is in output or reasoning tokens, not input.
Where to look in the console
The rate limits documentation says the Usage page shows the cache rate for input tokens, the share read from cache, next to your input token limit. Use it as a cross check on your own logs. For org level history, the Usage and Cost Admin API reports uncached input, cached input, cache creation, and output tokens, grouped by model or workspace.
Set an alert
Pick a floor for each flow after you have a week of data, and alert when the daily ratio falls below it. A cache regression is invisible to users and shows up first on the invoice.
Quick check
Is a 90 percent hit rate always good?
It is good for input cost on that flow. It says nothing about output tokens, reasoning tokens, or whether the answers are correct.
Why is my hit rate zero on a short prompt?
Prompts below the model's minimum cacheable length are processed without caching and no error is returned. Check the minimum for your model.
Sources
Last reviewed: 19 October 2026.
