Claude Prompt Caching: Cut API Costs and Latency

Claude prompt caching stores the processed state of a stable prompt prefix — your tools, system prompt, and long context — so Anthropic's API reuses it on later requests instead of recomputing it. Cached reads bill at roughly 10% of the normal input price and return faster, cutting both cost and latency on any repeated prefix.

We run a MongoDB-backed CMS that leans on the Claude API for content generation, and prompt caching is the single change that moved our bill the most — more than switching models, more than trimming max_tokens. It sits alongside the broader set of Claude AI features developers reach for, but on the API side it is the one with the clearest payback. Below is exactly what it caches, how to turn it on with cache_control, a real cost example, the 5-minute versus 1-hour TTL trade-off, and the silent mistakes that make the cache miss without any error.

What is Claude prompt caching?

Claude prompt caching is a feature of the Messages API that lets you mark a portion of your request as reusable. The first time Anthropic processes that marked prefix, it stores the computed internal state; on later requests that begin with the identical prefix, the model loads that state instead of reprocessing every token from scratch. You pay a small premium to write the cache once, then a deep discount on every read.

The mechanism is a prefix match, not a fuzzy match. The cache key is derived from the exact bytes of your rendered prompt up to each cache breakpoint. If the first 20,000 tokens of every request are identical, they cache. If a single character early in the prompt changes between requests — a timestamp, a reordered field — the match breaks and nothing downstream is reused. That constraint drives every design decision that follows.

New to calling the model at all? Our Claude API getting-started guide covers request structure first; Claude prompt caching is an optimization you layer on afterward, not something to reach for on request one.

How Claude prompt caching works

Claude assembles a request in a fixed order: tools first, then system, then messages. Caching walks that order and builds a prefix. A breakpoint placed on the last system block therefore caches your tool definitions and system prompt together, because both render before the conversation. The official prompt caching documentation spells out the same hierarchy.

That order creates an invalidation cascade. Changing your tool list invalidates the tools cache, the system cache, and the messages cache — everything, because tools sit at position zero. Changing the system prompt invalidates system and messages but leaves tools intact. Changing only the latest message invalidates nothing earlier. So the golden rule is simple: put stable content first, volatile content last. Freeze the system prompt, keep the tool list deterministic, and let per-request variation live at the end of messages.

Two more rules matter in practice. Caches are model-scoped, so switching models mid-conversation writes a fresh cache. And the minimum cacheable prefix depends on the model — 1,024 tokens on Sonnet 4.5, 2,048 on Sonnet 4.6, and 4,096 on Opus 4.8 and Haiku 4.5 — so a prompt shorter than that silently won't cache even if you mark it, with no error to tell you.

How to use cache_control

Turning on Claude cache control takes one field. You add cache_control to the content block that ends your stable prefix:

"system": [
  {
    "type": "text",
    "text": "<large shared system prompt or document>",
    "cache_control": { "type": "ephemeral" }
  }
]

That marks a 5-minute cache breakpoint. The SDKs also accept a top-level cache_control on the request, which automatically places the breakpoint on the last cacheable block and advances it as the conversation grows — the simplest option when you don't need surgical placement.

The steps we follow to enable Claude prompt caching on any new integration:

1. Identify the stable prefix — the tokens that are byte-identical across requests (tools, system prompt, retrieved documents, few-shot examples).
2. Confirm it clears the model's minimum — 1,024 to 4,096 tokens, depending on the model. Below that, marking it does nothing.
3. Place the breakpoint on the last block of that prefix, before anything that varies per request.
4. Verify the hit by reading usage.cache_read_input_tokens on the response. If it stays at zero across identical requests, a silent invalidator is at work.

You get a maximum of 4 breakpoints per request, which is enough to cache tools, a system prompt, a large document, and a rolling conversation turn independently.

What to cache

The best candidates for anthropic prompt caching are large, stable, and reused. The worst are small or change every request. This table reflects how we sort our own prompts:

Retrieval-augmented generation is the standout use case: the retrieved context is often tens of thousands of tokens, and you reuse it while the user asks several follow-ups. Coding agents are another — a large codebase or repository map in the prefix, cached once, read on every step. If you're pushing near the Claude context window with long documents, Claude prompt caching is what makes that volume affordable to send repeatedly.

Claude prompt cache pricing: a cost example

Claude prompt cache pricing is a set of multipliers on the base input token price. There are only three numbers to remember, and Anthropic's pricing documentation lists the same rates:

You pay the write premium once; the read discount applies to every subsequent request. That asymmetry is the whole game of Claude prompt caching. Consider a support assistant with a 50,000-token knowledge base pinned in the system prompt, handling 1,000 requests inside the cache window:

The break-even is fast. On the 5-minute cache, a single re-read pays the write off (1.25× write + 0.1× read = 1.35× versus 2× for two uncached passes). One caveat worth flagging: cache reads and writes still count as tokens against your account's usage and rate limits, so a heavily cached session consumes throughput differently than the dollar figure suggests. For the full rate picture across models, see our Anthropic Claude API pricing guide.

The 5-minute vs 1-hour cache TTL

By default the cache is ephemeral with a 5-minute TTL, and the timer refreshes on every hit — each time the prefix is reused, the clock resets. An extended 1-hour TTL is available by adding "ttl": "1h" to cache_control, at a higher write cost:

The choice is about traffic shape, not scale. If requests arrive more often than every five minutes, the default TTL stays warm on its own and the cheaper write wins. If your traffic comes in bursts with quiet stretches longer than five minutes, the 1-hour cache keeps the prefix alive across the gap — worth the doubled write only when enough reads land inside the hour to earn it back.

Prompt caching gotchas

Most "caching doesn't work" reports trace to a silent invalidator: something changes in the prefix that you didn't intend to change. The API never errors — cache_read_input_tokens simply stays zero. These are the offenders we grep for first:

• A timestamp or Date.now() in the system prompt. The prefix differs every request, so nothing caches. Move dynamic context to the end of messages.
• Non-deterministic JSON. Serializing a dict or set without sorting keys produces different bytes each time. Sort before you serialize.
• A per-user tool set. Tools render at position zero; if the list varies by user, nothing caches across users.
• Session IDs early in the content. A unique ID near the front makes every request distinct. Push it after the last breakpoint.
• A prefix below the model's minimum — 1,024 to 4,096 tokens depending on the model. Below it, the marker is ignored with no warning.

The fix is always the same: keep the front of the prompt byte-identical and move anything that changes to the back. When a cache mysteriously misses, diff the rendered bytes of two consecutive requests — the divergence point is your invalidator. Claude prompt caching rewards discipline about prompt structure far more than clever breakpoint placement.

Claude pricing at a glance

For the full breakdown of every plan, see our how much Claude costs guide.