Claude Prompt Caching: A Cost Savings Guide

If you're sending the same large system prompt, document, or tool schema with every Claude API call, prompt caching can cut your input token costs by roughly 90% on repeated requests. This guide explains exactly how the pricing works, when caching actually saves money, and how to implement it without wasting cache writes.

The short answer: prompt caching only helps when you reuse identical, large blocks of context across multiple requests within a short time window. If every request is unique, caching won't save you anything — it might even cost slightly more. The rest of this article breaks down the math so you can decide if it's worth implementing.

How Claude Prompt Caching Works

Prompt caching lets you mark specific parts of your prompt — a system prompt, a long document, a set of tool definitions — as cacheable using a cache_control field in the request. The first time Claude processes that block, it writes it to a cache. On subsequent requests that reuse the exact same block, Claude reads from the cache instead of reprocessing the full text.

The cache has a short lifetime (by default around 5 minutes, refreshed on each hit; Anthropic also offers an extended 1-hour cache option). If no request reuses the cached block within that window, the cache expires and the next request writes it fresh again.

This matters for any workload where context is large and repetitive: RAG pipelines that reuse the same retrieved document across follow-up questions, chatbots with long system prompts, coding assistants that keep the same codebase context loaded, or agents that reuse the same tool definitions across many calls.

The Pricing Math: Writes vs Reads

Prompt caching has two different cost rates, and understanding both is the key to the whole guide:

• Cache write: processing a new block into the cache costs more than a normal input token — typically around 25% more than the base input rate.
• Cache read: reusing a cached block on a later request costs a fraction of the base rate — typically around 10% of the normal input price, a roughly 90% discount.

So the economics are simple: you pay a premium once to write the cache, then get a steep discount every time you read it afterward. The breakeven point depends on how many times you reuse that cached block before it expires.

A simplified example with a 10,000-token system prompt:

• Without caching: every request pays full price for all 10,000 tokens.
• With caching: the first request pays ~12,500-token equivalent cost (the 25% write premium), and every subsequent request within the cache window pays roughly 1,000-token equivalent cost (the 90% discount).

If you make even 3–4 requests that reuse the same cached block within the TTL, you come out ahead. If you only ever make one request per cached block, you lose money on the write premium.

When Prompt Caching Actually Saves Money

Caching pays off in these patterns:

• Multi-turn conversations where the system prompt and early context stay identical across turns.
• Document Q&A where the same long document is referenced by multiple follow-up questions in a session.
• Agent loops that reuse the same tool definitions and instructions across many tool-calling steps.
• High-traffic endpoints serving many users with the same base prompt (e.g., a support bot with one fixed system prompt serving thousands of sessions).

Caching does not help when:

• Each request has unique, non-repeating context (e.g., one-off summarization of different documents).
• Requests are spaced far enough apart that the cache always expires between calls.
• The cacheable block is small — the write premium on a 200-token prompt isn't worth the engineering complexity.

Implementation Example

Here's a basic request using cache_control to mark a large system prompt as cacheable:

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "<your 10,000-token system prompt here>",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {"role": "user", "content": "Summarize section 3."}
    ]
  }'

The response includes usage fields showing cache_creation_input_tokens and cache_read_input_tokens, which let you confirm whether a given request was a cache write or a cache read — essential for verifying your savings are real and not just assumed.

If you're calling Claude through SubToAPI, the same cache_control fields work on the /v1/messages endpoint, and the per-request usage metadata in your dashboard breaks out cache writes and reads separately, so you can see exactly which requests are hitting the cache and which are paying the write premium. See the messages docs for the full request format, or start with the quickstart if you're setting this up for the first time.

Calculating Your Savings

Before implementing caching, estimate the payoff with this quick formula:

1. Identify the cacheable token count (the stable part of your prompt).
2. Estimate average reuses per cache write (how many requests typically land within the TTL window).
3. Compare: write_cost + (reuses × read_cost) vs reuses × full_cost.

If your cacheable block is reused at least 2–3 times before expiring, caching almost always wins. The more reuses per write, the closer your effective cost gets to that ~90% discount rate.

Common Mistakes That Erase Savings

• Changing the cached block slightly between requests. Even a one-character difference (like appending a timestamp inside the cached section) invalidates the cache and forces a new write every time.
• Caching content that's already short. The write premium outweighs any benefit below a few thousand tokens.
• Spacing requests too far apart. If your traffic pattern has long gaps, the cache expires before you get enough reads to offset the write.
• Not checking usage metadata. Without visibility into cache_read_input_tokens vs cache_creation_input_tokens, you're guessing whether caching is actually helping. Track it explicitly — if you're on SubToAPI, that breakdown is visible per request in the pricing and usage views without extra instrumentation.

Questions

Does prompt caching reduce output token costs too? No. Caching only applies to input tokens — the part of the prompt you send, not the response Claude generates. Output pricing stays the same regardless of caching.

How long does a Claude cache last before it expires? The default cache lifetime is around 5 minutes and refreshes on each cache hit. Anthropic also offers an extended 1-hour cache option for workloads with longer gaps between reuses.

Is prompt caching worth it for low-traffic apps? Usually not. If requests reusing the same cached block are infrequent or spaced beyond the cache TTL, you'll pay the write premium repeatedly without enough reads to offset it. Caching pays off with repeated, close-together requests sharing identical context.