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

Anthropic's prompt caching lets the Claude API reuse a previously processed prompt prefix instead of reprocessing it on every stateless request, with cache entries built in a fixed order — tool definitions, then system prompt, then message history — up to a marked breakpoint. For Claude Sonnet 4.6, base input costs $3 per million tokens, a 5-minute cache write $3.75, a 1-hour write $6, and a cache read $0.30, so caching only pays off when the prefix is actually reused. The most common failure is a breakpoint on a block that changes every request, such as a fresh timestamp, which produces a new prefix hash each time and yields cache writes with no reads.

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. 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. 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. 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: 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. 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: cache control field — unless you have sections that change at different frequencies. 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 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.