Mark the cacheable prefix with cache_control. Reads cost ~10% of standard input; writes cost ~125%.
Imagine a barista who has to re-read your 10-page coffee order every time you visit. You hand her a sticky note that says cache this and she photocopies the order once. The first time costs a bit more than usual because she also runs the photocopier. Every visit after, she glances at the photocopy and charges you almost nothing for the reading part. Anthropic's prompt cache works the same way. You stick a small flag on the long shared part of your prompt: the system instructions, the document, the tool definitions. Anthropic stores that processed prefix in fast memory. The first call (the write) is a bit pricier than normal. Every later call that re-uses the same prefix is roughly ten cents on the dollar.
Concept explanation~2 min read
Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example. Click to expand.
Concept explanation~2 min read
Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example. Click to expand.
Anthropic's prompt cache is the single biggest LLMOps cost lever the Claude API ships in 2026. Used well, a workload that re-sends the same 50K-token context dozens of times can run at roughly one fifth of its uncached cost, with a measurable drop in time to first token as a bonus.
This deep dive walks through the opt-in mechanic, the pricing arithmetic that decides when caching is worth it, the prompt-structuring discipline that maximizes hit rate, and the operational signals that catch silent invalidation before the bill spikes.
How the opt-in actually looks on the wire
The cache is per message block, not per-request. You mark the last content block of the prefix you want cached with a small annotation:
{
"role": "system",
"content": [
{
"type": "text",
"text": "<long stable system instructions plus tool schemas>",
"cache_control": { "type": "ephemeral" }
}
]
}
Claude treats every token up to and including the marked block as the cacheable prefix. Anything after the marked block is treated as the variable suffix and is re-encoded on every call. The cache key is the exact byte sequence of the prefix plus the model id plus a few other request parameters (system instructions resolved, tools resolved). Identical bytes everywhere collapse to one cache line; any drift creates a new line.
Situations where this technique stops working.
2–4 min · Everything important, quickly.
Real products, models, and research that use this idea.
- Anthropic Claude API: the cache_control: { type: ephemeral } field on a message content block opts in to caching, with hit metrics on every response.
- Cursor's chat backend caches the editor context and tool schemas across follow-up turns, cutting Claude spend on long conversations.
What an interviewer would ask next. Try answering before peeking at the approach.
QHow would you architect a multi-tenant SaaS so that tenants share a cacheable system-prompt prefix without leaking data across tenants?
Place the truly shared instructions and tool schemas before the cache_control mark; place the tenant id, retrieved tenant context, and user turn after the mark. Verify hit rate per tenant separately and confirm no PII appears in the cached span.
Red flags & common mistakes
The phrases that signal junior thinking. Click to expand.
Red flags & common mistakes
The phrases that signal junior thinking. Click to expand.
Marking only the last user message instead of the long shared prefix, which defeats the cache because the variable suffix changes every call.
60 second bullets to scan on the way to the call.
What field name opts a message block into the Anthropic prompt cache
What the read discount and write premium are relative to base input pricing
Primary sources. Browse if you want the original framing.
Same topic, related formats. Practice these next.