Claude Prompt Caching: Structure Prompts to Cut Costs

TL;DR: Claude prompt caching reuses a stable prompt prefix instead of reprocessing it on every request. A cache hit costs 10% of the base input price on most current models, 5% on Claude Opus 5.5, and 2.5% on Claude Fable 5.1 — but only if system, tools, and messages are ordered correctly. Here's the exact structure, current per-model pricing (verified September 25, 2026), and how to confirm it's actually working.

If you're sending Claude the same large system prompt, the same tool definitions, or the same reference document on every call, you're paying full price to reprocess it every single time, unless you tell the API which parts are safe to reuse. That's what cache_control does. It isn't a performance toggle you flip once; it's a structural constraint on how you build the request, and getting the structure wrong is the single most common reason teams add caching and see no change in their bill.

None of what follows requires spending a production API key to verify: the request and response shapes below are the documented contract, not a captured live call, and you can confirm the same shapes against your own account before changing anything that touches real traffic.

What Does Claude Prompt Caching Actually Do?

Prompt caching lets Anthropic's API skip reprocessing a prompt prefix it has already seen, storing the model's intermediate state instead of the raw tokens. The mechanism is a prefix match: the cache key is derived from the exact bytes of your rendered prompt up to a marked breakpoint, and a single byte of difference anywhere before that point invalidates every entry after it.

That last part is the one most teams get bitten by. Render order for a Claude request is fixed: tools, then system, then messages. A breakpoint on the last system block therefore caches the tool definitions and the system prompt together. Change a tool's description, reorder your tool list, or interpolate today's date into the system prompt, and everything downstream of that change stops caching, with no error to tell you so.

How Do You Structure a Request So Claude Actually Caches It?

You mark the reusable part of the prompt with a cache_control field, either once at the top level of the request (automatic caching) or on individual content blocks (explicit breakpoints, up to four per request). Automatic caching is the simpler default: add one field and the API places the breakpoint on the last cacheable block, moving it forward as a conversation grows.

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "cache_control": { "type": "ephemeral" },
  "system": "You are a support assistant with a large, mostly-static knowledge base baked into this prompt.",
  "messages": [
    { "role": "user", "content": "Summarize the refund policy for annual plans." }
  ]
}

"ephemeral" is currently the only cache type. It defaults to a 5-minute lifetime, extendable to 1 hour by adding a ttl field inside the same object (more on choosing between the two below).

Explicit breakpoints give you finer control when different parts of the prompt change at different frequencies: your tool definitions never change, your retrieved context updates daily, and the user's question changes every request.

{
  "system": [
    {
      "type": "text",
      "text": "<a large, effectively-static system prompt>",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "<shared reference document, same across many requests>", "cache_control": { "type": "ephemeral" } },
        { "type": "text", "text": "<the one-off question, no marker>" }
      ]
    }
  ]
}

Notice the second breakpoint sits at the end of the shared block, not at the end of the whole message. Put it after the varying question instead, and every request writes a new cache entry that nothing ever reads back.

Where Exactly Should the Breakpoint Go?

Three patterns cover most real prompts:

A large, shared system prompt. Put the marker on the last system text block. Because tools render before system, this one breakpoint covers your tool definitions too.

A growing multi-turn conversation. Put the marker on the last content block of the most recently appended turn (or just use automatic top-level caching). Each new request reuses the entire prior conversation as its cached prefix, and earlier breakpoints stay valid read points as the conversation grows.

A shared prefix with a varying tail. Few-shot examples, a retrieved document, or standing instructions, followed by a different question every time. The marker goes at the end of the shared portion, exactly as in the code block above. This is the pattern people get backwards most often: mark the whole message and you pay the write premium on bytes nobody ever reads back.

One structural rule sits underneath all three: don't change the model or the tool list between requests that are meant to share a cache. Caches are model-scoped with no exception, and tools render at position 0, so reordering or editing even one tool definition invalidates everything after it, for that request and every one after it until the prefix stabilizes again.

How Much Does Prompt Caching Actually Save Right Now?

Cache pricing is a fixed set of multipliers on the base input rate, but the base rate, and on two models the cache-read multiplier itself, differs per model. These figures are from Anthropic's pricing page, accessed September 25, 2026:

Source: platform.claude.com/docs/en/about-claude/pricing, accessed September 25, 2026.

The write multipliers (1.25× and 2×) are the same across every model. The read multiplier is not: it's 0.1× base on Claude Sonnet 5 and Claude Haiku 4.5, but Anthropic prices Claude Opus 5.5's cache hits at 0.05× and Claude Fable 5.1's at 0.025×. That means a cache hit on Claude Fable 5.1 is proportionally four times cheaper relative to its own base price than a cache hit on Claude Sonnet 5 is relative to its base price — which is worth knowing before you assume a flat 10%-of-input-price discount holds everywhere.

Cache write tokens are billed when content is first stored; cache read tokens are billed when a later request retrieves it. The arithmetic on whether caching pays off is: a 5-minute write breaks even after one read (1.25× + 0.1× = 1.35×, versus 2× for processing the same content twice with no caching at all); a 1-hour write needs at least two reads to clear its higher 2× write cost. If you're weighing caching against other levers on a high bill, why your API bill is high covers the other usual culprits: reasoning tokens, mismatched output caps, and vendor-specific naming for the same limit.

A Worked Example: What Does Caching Actually Save on a Real Workload?

Say you're running a support bot on Claude Sonnet 5 with an 8,000-token system prompt (product docs, refund policy, tone guidelines) that almost never changes, answering roughly 500 questions a day during business hours. Without caching, every one of those 500 requests reprocesses the full 8,000-token system prompt at the base $2/MTok rate: 500 requests × 8,000 tokens = 4,000,000 tokens a day, at $2/MTok, comes to $8.00 a day for the system prompt alone, before a single user question or model response is counted.

Add a cache_control breakpoint on the last system block, and the shape of that bill changes. Requests arriving within the default 5-minute window read the same cached prefix instead of reprocessing it: the first request of a "warm" cluster pays the 1.25× write premium once (on 8,000 tokens at $2.50/MTok, that's about $0.02), and every subsequent request in that cluster reads the same prefix at $0.20/MTok, about $0.0016 each. Across a full day of clustered traffic, that's a small number of writes plus several hundred reads rather than 500 full-price passes, and the system-prompt line item drops from roughly $8.00 a day to well under $1.00. Nothing about the model, the questions, or the answers changed; only the request's structure did. Actual savings on any specific workload will depend on how tightly your own requests cluster inside the TTL window, but the direction and the rough order of magnitude hold wherever the same prefix repeats often enough to be worth marking.

Should You Use the 5-Minute or the 1-Hour Cache?

Choose by the gap between requests that share a prefix, not by habit:

• Under 5 minutes apart (continuous traffic, an agent loop whose turns run well under 5 minutes): stay on the default 5-minute cache. Every request refreshes the timer, and the 1-hour option only adds a doubled write cost for no benefit here.
• 5 to 60 minutes apart (a user who replies twenty minutes later, a background task that runs between reads): set "ttl": "1h" inside cache_control. This is the one window where the 2× write cost is worth paying.
• Over an hour apart: neither TTL helps directly. Either re-warm the cache on a schedule with a max_tokens: 0 request just before the entry would expire, or accept the occasional cold write.

A cache read refreshes the entry's timer at no extra cost, on either TTL, and the lifetime is measured from when a request starts, not when its response finishes; a four-minute generation leaves only about a minute of runway on a 5-minute cache before the next request needs to land.

How Do You Verify Caching Is Actually Working?

Every response carries the answer in its usage object, and this is the step teams skip:

{
  "usage": {
    "input_tokens": 42,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 3120,
    "output_tokens": 187
  }
}

cache_creation_input_tokens is what got written this request. cache_read_input_tokens is what got served from cache. input_tokens is only the uncached remainder, so if a long-running session shows a small input_tokens number, don't panic; add all three fields to see the real prompt size. If cache_read_input_tokens sits at zero across several requests that should share a prefix, something is invalidating the cache before you ever see an error for it.

What Silently Breaks a Claude Cache Hit?

Grep your prompt-assembly code for these before you ship caching and call it done:

• A timestamp or request ID rendered into the system prompt. Every request becomes its own unique prefix, so nothing downstream of it ever matches a prior write.
• Non-deterministic JSON serialization (an unsorted dict, or iterating a set) that changes byte order between otherwise-identical requests, even when the underlying data hasn't changed at all.
• A tool list that varies per user or per request. Tools render at position 0; any variation there invalidates the entire cache, every time, for every user whose tool set differs.
• Conditional system-prompt sections (if flag: system += "..."). Every flag combination becomes a distinct, separately-cached prefix, so a feature flag rolled out to half your users can quietly double your cache-write volume.
• A breakpoint placed after the volatile content instead of before it. The single most common mistake, covered above.

Fix each by moving the dynamic piece after the last breakpoint, making the serialization deterministic, or removing it if it isn't load-bearing. None of these produce an error message; all of them show up as a cache_read_input_tokens that never moves, which is exactly why the verification step above isn't optional.

Is Prompt Caching Worth Setting Up for a Small App?

Only if you can answer yes to both: does a real prefix repeat across multiple requests (a shared system prompt, a standing reference document, a growing conversation), and does your request volume make the write premium recoverable within the TTL you pick? A one-off script that calls Claude once per prompt with no repetition gets nothing from caching: there's no second request to read the entry it would write. A support bot answering hundreds of questions against the same 3,000-token policy document is the textbook case: one write, hundreds of reads, at a tenth (or a twentieth) of the price each. If you're also comparing this against how other providers structure the same idea, prompt caching parameters across providers lines up Anthropic's cache_control against OpenAI's and Gemini's equivalents side by side, and provider settings compared covers the sampling and generation controls that sit next to caching in a request but don't affect it.

Two related limits worth knowing before you scale a caching setup: caching doesn't change your context window or your output ceiling, and max tokens vs max output tokens and what token limits actually mean for your prompts both cover ceilings that apply whether or not a given request hits cache.