Prompt Caching Explained: How Claude Reuses Your Prompt Prefix and When It Fails

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.

Understanding the Cache Architecture

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.

To implement this efficiently across multiple providers or custom pipelines, developers often integrate with aggregation layers like n1n.ai, which streamlines traffic management and model routing while preserving native API capabilities.

Automatic vs. Explicit Breakpoints

Automatic Caching

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

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.

{
  "model": "claude-3-5-sonnet-20241022",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "You are an expert software engineer...",
          "cache_control": {"type": "ephemeral"}
        }
      ]
    }
  ]
}

Pricing Economics and TTLs

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.

A concrete example: for Claude Sonnet, 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. When scaling high-volume applications through platforms like n1n.ai, these read-to-write ratios translate into substantial cost reductions.

Minimum Token Thresholds and Failure Modes

Not every prompt is eligible. There is a minimum cacheable prompt length, which varies by model — for example, 1,024 tokens for older Sonnet variants, 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 Dynamic Content Trap

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.

Best Practices Checklist

• Order your request: static content first, varying content last.
• Start with automatic caching — one top-level cache_control field — unless you have sections that change at different frequencies.
• Put explicit breakpoints at the end of each stable section, never on a block containing a timestamp or per-request data.
• Check that your stable prefix clears the model's minimum token threshold; otherwise nothing is cached at all.
• If your turns are long, add a second breakpoint so a growing conversation does not push the last cache write outside the 20-block lookback window.
• Choose the 5-minute TTL for active conversations and the 1-hour TTL only when gaps between requests are long enough to justify the 2x write price.

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. To optimize your multi-model workflows further, get a free API key at n1n.ai.