Prompt Caching, Explained: How Claude Reuses Your Prompt Prefix — and When It Doesn't Pay Off

If you build anything that talks to Claude more than once — a chatbot, a coding agent, a document Q&A tool — you are probably paying to process the same text over and over again. Every API request is stateless: the model re-reads your system prompt, your tool definitions, and the whole conversation history each time. Prompt caching is Anthropic's answer to that waste. It lets the API reuse a previously processed prefix of your prompt instead of processing it again.

This is not a different model or a new endpoint. It is a way of marking part of your request as reusable. Here is how it works, what it costs, and where it quietly stops working.

What gets cached: a prefix, not a paragraph

A cache entry covers the start of your request, up to a breakpoint you mark. Anthropic's docs describe the prefix as being built in a fixed order: tool definitions first, then the system prompt, then the message history. Everything from the very first token up to and including your breakpoint becomes one cacheable unit.

That ordering is the whole design discipline. Put the content that rarely changes at the beginning — your tools, your system instructions, your background documents, your few-shot examples — and put the thing that changes every request at the end. If the variable part sits inside the cached prefix, the prefix is different on every request and nothing is ever reused.

Two ways to turn it on

Automatic caching is the simplest start: add a single cache_control field at the top level of your request, and the system places the breakpoint on the last cacheable block for you. As a multi-turn conversation grows, the breakpoint moves forward automatically, so each new request reads the earlier turns from cache and writes only the newest exchange.

Explicit breakpoints give you finer control. You place cache_control directly on individual content blocks — for example, one breakpoint after your system prompt and another after a large reference document that updates daily. You can define up to 4 breakpoints in a request, which also helps when a long conversation grows past the 20-block lookback window the docs describe: each breakpoint gets its own backward search for a prior cache entry.

Breakpoints themselves cost nothing. You pay only for cache writes, cache reads, and the uncached tokens in each request.

What it costs

By default, a cache entry lives for 5 minutes, and reading it refreshes that lifetime at no extra charge. The lifetime is measured from the start of the request that writes or reads the entry, not from the end of the response — so a response that takes 4 minutes to stream leaves only about 1 minute for the follow-up to reuse the same prefix.

The price structure, per Anthropic's documentation:

• Cache writes (5-minute TTL) cost 25% more than base input tokens.
• Cache reads cost 10% of the base input price for most models, with exceptions: 0.025x for Claude Fable 5.1 and Claude Mythos 5.1, and 0.05x for Claude Opus 5.5 and Claude Sonnet 5.5.
• A 1-hour TTL is available at 2x the base input price for writes.

A concrete example from the pricing table: for Claude Sonnet 4.6, base input is $3 per million tokens, a 5-minute cache write is $3.75, a 1-hour write is $6, and a cache read is $0.30. So the second request that reuses a large prefix is dramatically cheaper than the first — but the first request is slightly more expensive than it would be without caching. Caching only pays off when the prefix is actually reused.

The minimums and the traps

Not every prompt is eligible. There is a minimum cacheable prompt length, which varies by model — for example, 1,024 tokens for Claude Sonnet 4.6 and Sonnet 4.5, and 512 tokens for newer models such as Claude Sonnet 5.5, Opus 5.5, and Haiku 5.5. A short system prompt will simply never be cached, silently.

The most common failure mode is documented with unusual clarity: a breakpoint placed on a block that changes every request — say, a message containing a fresh timestamp — produces a different prefix hash each time. The lookback walks backward looking for entries that prior requests actually wrote, and since no prior request wrote an entry at an earlier position, there is no hit. You pay for a fresh cache write on every request and never get a read. The fix is to move the breakpoint to the last block that stays identical across requests.

Two more rules worth knowing:

• The cache is per model. Switching models mid-conversation starts cold.
• Automatic and explicit breakpoints can conflict. If the last block already has an explicit breakpoint with a different TTL, the API returns a 400 error, and if 4 explicit breakpoints already exist there is no slot left for automatic caching.

A practical checklist

1. Order your request: static content first, varying content last.
2. Start with automatic caching — one top-level cache_control field — unless you have sections that change at different frequencies.
3. Put explicit breakpoints at the end of each stable section, never on a block containing a timestamp or per-request data.
4. Check that your stable prefix clears the model's minimum token threshold; otherwise nothing is cached at all.
5. If your turns are long, add a second breakpoint so a growing conversation does not push the last cache write outside the 20-block lookback window.
6. Choose the 5-minute TTL for active conversations and the 1-hour TTL only when gaps between requests are long enough to justify the 2x write price.

Prompt caching does not make the model smarter, and it does not change what the model outputs. It just stops you from paying full price to re-read the same instructions for the hundredth time. Used with the prefix discipline above, that is one of the cheapest wins available in a production LLM app.

All pricing and behavior details in this article are from Anthropic's prompt caching documentation: https://platform.claude.com/docs/en/build-with-claude/prompt-caching — re-check the page before relying on a number, since pricing and minimums change.