Prompt Caching in Practice
Structure prompts so stable content is cached, verify cache hits in usage data, and avoid the silent invalidators that quietly double your bill.
Look at the requests your AI features send and you'll notice something wasteful: most of every request is the same as the last one. The system prompt, tool definitions, few-shot examples, the customer's account context. You pay full input price to send those identical tokens again and again, and the model spends time re-reading them before it writes a word.
Prompt caching fixes that. The provider keeps the processed form of a prompt's beginning for a few minutes, and when the next request starts the same way, it reads that part from the cache at a fraction of the price and faster. Turning it on takes one field. Getting it to actually hit, and keep hitting as your code changes, is the real work. In this lesson you'll structure a real feature's prompt for caching, verify hits in usage data, diagnose misses, and learn the silent invalidators that can double your bill.
How a cache hit actually works
The rules are short, and every practical decision in this lesson follows from them. These describe Anthropic's API; other providers' caching differs in the details (some cache automatically with no markers at all), but the prefix principle is universal.
- It's a prefix match. The API assembles each request in a fixed order:
tools, thensystem, thenmessages. A hit requires every byte from the start of that sequence up to a cache breakpoint to be identical to an earlier request. One changed character invalidates that point and everything after it. - You mark breakpoints. A breakpoint is a
cache_control: { type: "ephemeral" }field on a content block meaning "cache everything up to and including this block." You can place up to four. Alternatively, a top-levelcache_controlfield on the request places one automatically on the last cacheable block. - Entries expire. The default lifetime is five minutes, refreshed for free every time the entry is read. A one-hour lifetime is available with
ttl: "1h". - Short prefixes don't cache. Below a minimum length (512 tokens on Claude Opus 5.5, Sonnet 5.5, and Haiku 5.5; check the model page for others), a breakpoint is silently ignored. No error, no cache.
- Caches are scoped. They're per model and per workspace. Different organizations never share caches.
Caching never changes the answer. The model sees exactly the same input either way; only the price and speed change.
The pricing math
Three numbers, as multiples of the normal input price:
| Event | Price |
|---|---|
| Cache write, 5-minute lifetime | 1.25× |
| Cache write, 1-hour lifetime | 2× |
| Cache read | 0.05× on Claude Opus 5.5 and Sonnet 5.5; 0.1× on Haiku 5.5; 0.025× on Fable 5.1 |
Those are the multipliers at the time of writing (November 2026), so check the current pricing page. The important consequence: with the five-minute lifetime, caching pays off on the first reuse. Sending a prefix twice without caching costs 2×. With caching it costs 1.25× for the write plus at most 0.1× for the read. The one-hour lifetime needs two reuses to beat no caching at all, which is why it's for specific traffic patterns, covered below.
Caching also helps latency. A long cached prefix doesn't have to be reprocessed, so time to first token drops on big prompts. And for rate limits, cache reads don't count against your input-tokens-per-minute limit on current models, which can matter as much as the price.