Claude API Prompt Caching: Cut Costs Fast

Claude API prompt caching reduces costs by letting you reuse large, repeated chunks of a prompt — system instructions, documents, tool definitions — without paying full price to reprocess them on every request. Cached tokens cost roughly 90% less than regular input tokens on a cache hit, and the savings compound fast if your app sends the same context repeatedly, which most production apps do.

If you're researching this because your Claude bill is higher than expected, the short answer is: identify the parts of your prompt that don't change between requests, mark them as cacheable, and let Anthropic's infrastructure store and reuse that processed state. This guide covers how it works, what it actually saves, and where it falls short.

How Prompt Caching Actually Works

When you send a request to Claude, the model has to process every input token before it can generate a response. For long system prompts, reference documents, or few-shot examples, that processing happens on every single call — even if the content is byte-for-byte identical to the last request.

Prompt caching changes this by letting you flag specific blocks of your prompt as cacheable. On the first request, Claude processes and caches that block. On subsequent requests within the cache's TTL (typically 5 minutes, with an extended option available), Claude detects the matching cached block and skips reprocessing it, charging a fraction of the normal input token rate instead.

The mechanics in a raw Anthropic Messages API call look like this:

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": "You are a support agent. Here is the full product manual: ... [10,000 tokens] ...",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      {"role": "user", "content": "How do I reset my device?"}
    ]
  }'

The cache_control block tells Claude to cache everything up to and including that marker. Every subsequent request with the identical prefix hits the cache instead of reprocessing the manual from scratch.

Where the Real Savings Come From

Prompt caching pays off in specific, identifiable patterns:

• Long system prompts — brand voice guidelines, compliance rules, persona instructions that stay fixed across thousands of requests
• RAG and document Q&A — the same retrieved document or knowledge base chunk reused across a conversation or across users asking about the same source
• Few-shot examples — static example sets used to steer output format or tone
• Tool definitions — large JSON schemas for tool use that don't change between calls
• Multi-turn conversations — each turn re-sends the full conversation history; caching the early turns avoids repaying for them every time

The savings scale with how much of your token spend is "static context" versus "actual new input." An app with a 200-token user question and a 8,000-token system prompt sees dramatically more benefit than one where every token is unique user content.

Doing the Break-Even Math

Caching isn't free — writing to the cache costs more than a normal input token (roughly 25% more on a cache write), and cache reads are cheaper (roughly 90% less). That means caching only pays off if the cached content gets reused at least a couple of times within the TTL window.

Rough rule of thumb:

• 1 cache write + 1 cache read ≈ break-even versus no caching
• 1 cache write + 3+ cache reads = clear savings
• Content reused dozens of times per TTL window = the 90% discount dominates and savings are substantial

If your traffic pattern sends the same large system prompt to Claude every few seconds across many users, caching is close to a guaranteed win. If you're sending genuinely unique long prompts that never repeat, caching won't help — there's nothing to cache against.

Common Mistakes That Kill Cache Hit Rates

Putting variable content before the cache marker. The cache only matches on an exact prefix. If you insert a timestamp, a random request ID, or per-user data before your cacheable block, every request becomes a cache miss. Order your prompt so static content comes first, then cache_control, then dynamic content.

Underestimating the TTL window. The default ephemeral cache expires in minutes. If your request volume for a given prompt is sparse — say, one request every 10 minutes — you'll keep paying the write premium without ever hitting cached reads. Batch similar requests closer together when possible, or use the extended TTL option for lower-frequency but still-repeated content.

Not measuring hits vs. misses. Every response includes cache-related usage fields — cache creation input tokens and cache read input tokens — so you can verify caching is actually working rather than assuming it is.

Monitoring Caching Across Many Users

If you're running Claude behind an application with multiple users or team members, tracking cache performance per caller gets complicated fast with raw API keys. This is one of the gaps SubToAPI fills: it sits on top of your existing Claude access and exposes clean per-key usage metadata — including token breakdowns — through a standard HTTPS API, so you can see which parts of your app are actually benefiting from caching and which aren't.

Instead of parsing raw Anthropic usage logs per workspace, you get application-level API keys (sub_live_...) with usage visible in one dashboard. Setup takes a few minutes — see the quickstart and the messages docs for request formatting that carries caching metadata through. Plans start at €9/month on the Solo tier, with team seats on the Team (€19/seat) and Scale (€49/seat) plans — all with a free trial at signup. Full details are on the pricing page.

Practical Checklist

• Identify your largest, most-repeated prompt blocks (system prompts, docs, tool schemas)
• Move static content to the front of the prompt, dynamic content after
• Add cache_control markers around the static blocks
• Confirm cache reads are happening by checking usage metadata, not assumptions
• Align request frequency with the cache TTL — sparse traffic won't benefit
• Re-evaluate periodically as prompts evolve; stale cache markers on changed content silently lose their benefit

Questions

Does prompt caching reduce output token costs too? No. Caching only affects input token processing. Output tokens — the text Claude generates — are always billed at the standard rate regardless of caching.

How long does a cached prompt stay valid? The default ephemeral cache has a short TTL, typically around 5 minutes from last use, with each cache hit refreshing the timer. An extended TTL option exists for content reused less frequently.

Can I cache part of a prompt and not the rest? Yes. You mark specific blocks with cache_control, so you can cache a long system prompt or document while leaving the per-request user message uncached, since that part changes every time anyway.