How to Cut Your Claude API Bill 70% with Prompt Caching

An AI agent re-sends its entire context on every step of its loop: the system prompt, every tool definition, and the full conversation so far, including every previous tool result. On a 10-step run, the system prompt and tools alone get billed 10 times. That repetition is exactly what prompt caching eliminates.

On the Claude API, input tokens served from the cache bill at roughly 0.1x the base input rate. At current pricing that means:

Do the napkin math for a typical agent: a 6,000-token system prompt plus tools, a conversation that grows to 40,000 tokens, 10 loop iterations. Uncached, that is roughly 250,000 input tokens. With the prefix cached, you pay full price roughly once and 0.1x for the rest - the input side of the bill drops by 85-90%. Because output tokens still bill at full rate, the whole-bill saving for a real agent workload usually lands at 60-75%. That is where the 70% in the title comes from - measured on the total invoice, not cherry-picked on the cached portion.

Everything about Claude prompt caching follows from one invariant: the cache is a prefix match on the exact rendered bytes of your request. The API renders your request in a fixed order - tools, then system, then messages - and the cache key is derived from the bytes up to each breakpoint you mark. A single byte difference at position N invalidates the cache for everything at positions after N.

You mark breakpoints with cache_control on a content block:

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    system=[
        {
            "type": "text",
            "text": LONG_STABLE_SYSTEM_PROMPT,
            "cache_control": {"type": "ephemeral"},  # 5-minute TTL
        }
    ],
    messages=[{"role": "user", "content": user_question}],
)

Because tools render before system, a breakpoint on the last system block caches the tool definitions and the system prompt together - you do not need a separate marker on the tools. You get at most 4 breakpoints per request, and there is a simpler option when you do not need fine-grained placement: a top-level cache_control on the request auto-places a breakpoint on the last cacheable block.

Two constraints people miss:

• Minimum cacheable prefix. Short prefixes silently do not cache - no error, the usage report just shows cache_creation_input_tokens: 0. The minimum is model-dependent: 1,024 tokens on Sonnet 4.5, 2,048 on Sonnet 4.6, 4,096 on Opus 4.8 and Haiku 4.5. A 3,000-token prompt caches on one model and silently does not on another.
• Caches are model-scoped. Switching models mid-conversation starts from a cold cache, and the first request on the new model pays the write premium again.

Cache writes are not free. Writing to the default 5-minute cache costs 1.25x the base input rate; the 1-hour TTL costs 2x. That premium buys you 0.1x reads afterwards, so break-even depends on how many times the prefix is re-read before it expires:

What this means in practice:

• Agent loops always win. A single agent run makes 5-30 requests within minutes, all sharing the prefix. The 5-minute cache pays for itself on the second loop iteration.
• Multi-turn chat wins if users reply within the TTL. Each turn re-reads the whole prior conversation. If replies typically arrive within 5 minutes, the default TTL is enough; if your users think for 20 minutes between messages, the 1-hour TTL keeps the cache alive but needs at least 3 turns to beat no caching.
• One-shot requests with unique prompts lose. If the first 1,000+ tokens differ on every request, there is no reusable prefix. Adding cache_control just pays the 1.25x write premium with zero reads. Leave it off.

Also note the cache only becomes readable once the first response begins streaming. If you fan out 10 parallel requests with the same prefix, all 10 pay full price - none can read what the others are still writing. The fix: send one request, await the first streamed token, then fire the other nine. They read the cache the first one just wrote.

Pattern 1 - big shared system prompt. One breakpoint on the last system block. Tools and system cache together; the varying user question comes after and bills normally.

Pattern 2 - multi-turn conversation. Put the breakpoint on the last content block of the most recently appended turn. Each request then reuses the entire prior conversation as cached prefix, and hits accrue incrementally as the conversation grows:

# before sending, mark the newest turn as the cache frontier
messages[-1]["content"][-1]["cache_control"] = {"type": "ephemeral"}

Pattern 3 - shared preamble, varying question. Many requests share a large fixed block (few-shot examples, retrieved documents, instructions) and differ only at the end. Put the breakpoint at the end of the shared portion, not the end of the whole prompt - otherwise every request writes a distinct cache entry and nothing is ever read:

messages = [{
    "role": "user",
    "content": [
        {
            "type": "text",
            "text": SHARED_CONTEXT,  # same every request
            "cache_control": {"type": "ephemeral"},
        },
        {"type": "text", "text": varying_question},  # no marker
    ],
}]

One agent-specific edge case: each breakpoint looks backward at most 20 content blocks to find a prior cache entry. Agent turns with many parallel tool calls can add more than 20 blocks in one turn, at which point the next request silently misses the previous cache. If your agent does heavy parallel tool use, place an intermediate breakpoint every ~15 blocks.

The most common caching failure is not a missing breakpoint - it is a byte that changes on every request somewhere early in the prompt. The request succeeds, no error is raised, and the cache never gets read. Grep your prompt-assembly code for these:

The fixes are mechanical: move dynamic values after the last breakpoint (put the current date in the user message, not the system prompt), make serialization deterministic (sort keys, sort tools by name), and freeze the system prompt. If you need per-request context like a date or a mode flag, inject it as a message near the end of the conversation - a message at turn 5 invalidates nothing before turn 5.

The same logic explains two architectural rules: never swap the tool set mid-conversation (add a mode parameter to a message instead), and when you fork a conversation for a side task like summarization, copy the parent's system, tools, and model verbatim so the fork reads the parent's cache instead of writing its own.

Every response reports exactly what the cache did. Log these three fields on every call:

u = response.usage
print("written to cache:", u.cache_creation_input_tokens)  # paid ~1.25x
print("served from cache:", u.cache_read_input_tokens)      # paid ~0.1x
print("uncached:", u.input_tokens)                           # paid full rate

A healthy cached agent shows a big write on the first request, then large cache_read_input_tokens and small input_tokens on every subsequent one. Total prompt size is the sum of all three fields - if your agent ran for an hour but input_tokens shows 4,000, the rest was cache reads, which is the goal.

If cache_read_input_tokens stays at zero across repeated identical-prefix requests, do not guess: render two requests, dump the raw bytes, and diff them. The first differing byte is your invalidator - in my experience it is a timestamp about 80% of the time and an unsorted dict most of the rest.

One more production trick: to remove the cold-cache latency on the first real request, you can pre-warm at startup with a max_tokens: 0 request. The API runs prefill, writes the cache at your breakpoint, and returns immediately with empty content - zero output tokens billed. Only worth it when first-request latency is user-visible and the prefix is large; if traffic is continuous the first real request warms the cache on its own.

Numbers from a realistic setup on Claude Sonnet 4.6 ($3/M input, $15/M output): a support agent with a 5,000-token system prompt + tool definitions, averaging 8 loop iterations per ticket, with conversation context growing to ~20,000 tokens by the final step. Roughly 100,000 input tokens and 3,000 output tokens per ticket.

That is a 64% reduction from one change that touches no product behavior. At 1,000 tickets a day the difference is roughly $6,600/month. Stack model routing on top (send easy tickets to Haiku 4.5 at a third of the input price) and the combined saving crosses 80% - the full stack of levers is in our production cost-optimization playbook.

If you are weighing this against running your own models, the caching discount also changes the self-hosting math - a cached Claude workload is much harder for a self-hosted GPU box to beat than the sticker prices suggest. We run that comparison honestly in the self-host vs API break-even analysis.

Marking everything. More breakpoints is not more caching. You get 4; use them at stability boundaries (end of tools+system, end of shared context, end of the latest turn). A breakpoint on content that differs per request is a pure write premium.

Caching below the minimum. A 900-token system prompt does not cache on any current model. Either accept it (the absolute spend is small) or move more stable content - style guides, examples, tool usage notes - into the system prompt to cross the threshold. This is one of the few cases where making a prompt longer makes it cheaper.

Choosing the 1-hour TTL by default. The 2x write premium means it needs 3+ reads to beat no caching at all, and more than that to beat the 5-minute TTL kept warm by steady traffic. Choose 1-hour only when you have measured gaps longer than 5 minutes between requests that share a prefix.

Rebuilding the prompt differently in different code paths. The retry path, the streaming path, and the eval harness must assemble byte-identical prefixes. A subtle difference - one adds a trailing newline, one orders tools differently - and your production traffic and your evals populate two separate caches.

Not logging cache fields. If your observability does not record cache_read_input_tokens per call, you cannot see regressions. A deploy that adds one dynamic line to the system prompt will silently multiply your bill by 5x, and you will find out from the invoice. Wire the three usage fields into whatever tracing you already run - if you have none, start with our agent observability guide.