Anthropic prompt caching: budget the write before celebrating the hit
Plan Anthropic prompt caching with separate write, read and ordinary input costs. Worked TTL examples and a measurement checklist explain when reuse pays off.
Anthropic prompt caching is useful when requests reuse substantial context. But a discounted cache read is only one line in the bill. You also need to account for creating the cache, new input, generated output and the number of useful reuses before expiration. A high-looking hit percentage can coexist with an expensive workload if you repeatedly rewrite long prefixes or generate much more output.
This guide turns those components into a worksheet and a small evaluation plan. It is about Anthropic's Claude API, not a Claude subscription allowance and not Ollama-hosted pricing. ModelBudgetCalc's Ollama calculator does not implement Anthropic cache-write accounting; do not enter these rates there and treat the result as an Anthropic invoice.
The four quantities to keep separate
The official prompt-caching guide exposes three input categories: input_tokens for ordinary uncached input, cache_creation_input_tokens for writes, and cache_read_input_tokens for reads. Add those categories to obtain total input. Output is separate. Unlike some other providers' usage schemas, the first field alone is not the whole input count.
For your accounting sheet, create one column per category rather than one universal “tokens” column. Give each row a model, platform, price date and cache duration. If the API reports writes at different durations, retain that breakdown. A reporting layer that merges every input category before pricing loses the information needed to reconcile the result.
Current multipliers are model-specific
Anthropic's pricing documentation lists five-minute writes at 1.25 times the base input rate and one-hour writes at twice that rate. Reads are generally 0.1 times base input, but Claude Fable 5.1 and Claude Mythos 5.1 use 0.025 times. Retrieve the selected model's actual rates; “all Claude cache reads cost one tenth” is no longer an accurate universal rule.
Use this simplified input-only formula: ordinary tokens times their rate, plus five-minute write tokens times their rate, plus one-hour write tokens times their rate, plus read tokens times their rate, all divided by one million when rates are quoted per million tokens. Then add output and any other applicable charges. Keep units explicit. A dollars-per-million rate cannot be multiplied by a raw token count without that conversion.
An original break-even worksheet
Let one unit represent the ordinary input cost of one fixed prefix. For illustration, use the standard 0.1 read multiplier, assume every reuse is a complete hit, and exclude new questions and output. The following table is derived arithmetic, not measured customer savings. It compares the same number of prefix uses under different cache lifetimes.
| Total uses of the prefix | Without caching | One five-minute write, then hits | One one-hour write, then hits |
|---|---|---|---|
| 1 | 1.00 | 1.25 | 2.00 |
| 2 | 2.00 | 1.35 | 2.10 |
| 3 | 3.00 | 1.45 | 2.20 |
| 6 | 6.00 | 1.75 | 2.50 |
A one-use prefix does not earn back its write premium in this example. Two uses make the five-minute arrangement cheaper than processing the prefix twice normally. The one-hour arrangement needs three total uses before it beats the uncached total under these assumptions. None of this establishes that a real second request will hit the cache; matching and timing must be verified from actual usage.
Now choose an illustrative base rate of $3 per million tokens and a 20,000-token prefix. One ordinary use costs $0.06. Six uncached uses cost $0.36. One five-minute write plus five hits costs 1.75 times $0.06, or $0.105. One one-hour write plus five hits costs $0.15. These are hypothetical prefix costs, not a quote for a named model; the questions, answers and any tools still have their own cost.
Pick a lifetime from gaps between requests
Anthropic documents a default five-minute cache lifetime and an optional one-hour duration. It supports a top-level cache_control setting for automatic breakpoint placement or explicit markers on content blocks. Minimum eligible lengths depend on the model. A marker alone is not proof that a short prompt was cached. Check enablement, lifetime and eligibility.
For a synthetic workload arriving at minutes zero, nine and eighteen, a five-minute entry would need a new write each time if it has expired between requests. At a 1.25 write multiplier, that prefix costs 3.75 units. A one-hour write followed by two full hits at 0.1 costs 2.20 units. This example shows why the lowest write price is not always the lowest session cost.
Before selecting a duration, inspect the distribution of real gaps, including time spent waiting for people or external tools. A daily average hides whether work arrives in a tight burst or scattered requests. Maintain a conservative case with more misses than you hope to see. Do not manufacture extra calls merely to improve a cache-hit metric; that can increase total spend.
Design a stable prefix without preserving stale facts
Our suggested starting structure is stable task instructions, stable tool definitions where applicable, a versioned reference package, then the changing question. Keep the content needed for correctness. A reference package should have a clear version so you can intentionally change it when policies or product facts change. Saving processing on obsolete material is not a successful optimization.
As a concrete example, an internal documentation assistant might reuse a reviewed product manual while receiving different troubleshooting questions. Give the manual a release identifier and keep the user's question separate. When the manual is revised, test the new prefix and expect its first use to behave differently from a warm reuse. Never retain an outdated manual merely to protect an attractive chart.
The official prompt-caching cookbook provides implementation examples. Use it to validate an SDK request shape, then build your own small fixture. This page intentionally avoids pasting an untested application or requiring readers to send paid requests from a public browser tool.
A measurement plan that can disprove your assumption
Choose a non-sensitive reference document and several realistic questions. Record model, platform, SDK version, request time, prompt version, ordinary input, writes, reads, output and completion status. Run an initial request and a controlled follow-up through your own authorized API environment. Observe the usage fields instead of assuming a successful response implies a cache hit.
Then vary one factor: change the question while retaining the intended prefix, introduce a realistic pause, or publish a new reference version. Document each case separately. These checks reveal whether your intended reuse pattern survives the way your application actually assembles requests. Do not claim observed latency or cost improvement until you have measured it.
Define two metrics instead of hiding everything in one. Token-weighted read share is read input divided by all input. Request hit share is the fraction of requests with some read input. Ten tiny warm requests and one huge cold request can make the second metric look excellent while the first remains poor. For the business decision, also measure total cost per successfully completed task.
Common accounting and rollout mistakes
Do not subtract cached reads from Anthropic's ordinary input_tokens field as though that field already included them. Do not ignore cache creation because a dashboard calls it input. Do not apply a standard read multiplier to a model with a different published rate. Finally, do not turn a percentage reduction in prefix cost into the same percentage reduction in the entire invoice.
Introduce one change at a time in a limited workload. Keep an uncached or prior-configuration comparison with equivalent tasks where you can legitimately measure it. Review answer quality and operational failures alongside spend. A lower bill caused by more abandoned or incomplete tasks is not a useful success signal.
Frequently asked questions
Is a cache hit a saved answer?
This guide concerns reused prompt processing, not serving a previously generated answer from your own response database. Continue to validate the current answer. Do not let a caching optimization bypass ordinary quality or authorization checks.
Are these Claude subscription limits?
No. This is API token accounting. A subscription interface can have its own usage rules. Identify the billing product before comparing a monthly allowance with API consumption.
Can I copy these rates to another host?
No. Confirm the host's own pricing and usage schema. A model name appearing on two platforms does not establish identical cache mechanics or billing. The separate OpenAI caching guide illustrates why provider-specific accounting matters.
What is the safe next step?
Collect a small, redacted usage sample, reproduce its cost with the current rate table, then test realistic reuse. Review applicable data-handling requirements before caching sensitive content. Our methodology explains this site's boundaries; it does not replace your API agreement or account invoice.