Anthropic prompt caching is load-bearing infrastructure. Most teams configure it wrong.

LLM & Model Guides · By Caleb Sakala · April 4, 2026

Anthropic's prompt caching documentation is accurate and technically complete. It's also silent on the failure modes that actually matter in production.

The docs explain the mechanism correctly: mark your cacheable content with cache_control, pay a 25% write premium on the first request, then receive cache hits at 90% off the base input token price. In theory, this compounds beautifully. In practice, three specific patterns make the cache miss almost every time, and nothing in the API response flags that it's happening.

The math before anything else

Anthropic charges $3.00 per million input tokens for Claude Sonnet models and $0.30 per million for cache hits (per Anthropic's pricing page). Cache writes cost $3.75 per million. So the first cached request costs more than the uncached version.

That 25% write premium means you need at least one cache hit before the math flips. In a chat application where users send messages at sub-minute intervals, the break-even arrives almost immediately. In a scheduled automation that runs every 10 minutes, it might never arrive.

DigitalOcean's engineering team published a cost analysis of a production AI system (March 2026) showing that for a request with 6,000 cacheable tokens and 350 dynamic tokens, the uncached cost is $0.00994 per request while a warmed-cache request runs $0.00319. At 10,000 daily requests, that's roughly $24,000 in annual savings. But that scenario assumes the cache stays warm between requests, which is the assumption that kills most implementations.

How Anthropic prompt caching TTL breaks scheduled automation

Anthropic's default cache TTL is 5 minutes. A 1-hour TTL is available via explicit configuration.

A workflow firing every 6 minutes, or nightly, or on irregular webhook triggers cold-starts the cache on nearly every run. Each run pays the write premium and collects zero savings. This is the most commonly cited reason prompt caching "didn't help."

Fixing it requires a configuration step that isn't prominently documented: set the extended TTL explicitly in the cache_control block rather than accepting the 5-minute default. For any automation with a regular cadence longer than 5 minutes, the 1-hour window is almost always the correct choice. The write cost is identical either way.

Bursty batch patterns have the inverse problem. A job that processes 400 records in 8 minutes will warm the cache on record 1, hit it successfully across the batch, then go quiet for hours. The next batch starts cold. Here, caching genuinely helps within each batch run. The correct mental model shifts: the unit of benefit is the batch, not the individual request.

The prompt ordering mistake that kills Anthropic prompt caching

Cache hits depend on prefix matching. The Anthropic caching layer checks whether the beginning of the current prompt matches a stored prefix. If that prefix differs between requests, there's no hit.

Many teams structure their prompts with dynamic content at the top: the current date, retrieved context, then the static system instructions below. That ordering ensures the cacheable content never forms a stable prefix. Cache writes succeed, the cache never warms, and nothing in the API flags the problem. You just never see a non-zero value in cache_read_input_tokens.

Placing all static content first (system instructions, tool schemas, reference documents) with dynamic content below fixes this. In multi-step workflows, every step that calls Claude must have its static context pinned to the top of the prompt, regardless of what makes logical sense to a human reading the message structure.

One practical wrinkle: if you're using RAG and the retrieved documents change between requests, those documents cannot be the first thing in the prompt. Treat retrieval results as dynamic content and push them below the static system instructions. This is the opposite of what most RAG implementation guides show.

Where the economics compound in automation pipelines

Single-request patterns benefit from caching, but the savings are modest unless volume is high. The place caching earns infrastructure status is in multi-step workflows where sequential LLM calls share a large static context.

A contract processing automation with 6 extraction steps per contract and a 5,000-token static legal extraction template burns 30,000 tokens of system prompt per contract at full price without caching. Using Anthropic's published pricing, the system-prompt cost per contract without caching is $0.090. With a correctly ordered cache and the 1-hour TTL, steps 2 through 6 hit the cache. Those 5 steps cost $0.0075 in cache reads (25,000 tokens at $0.30/million), plus $0.01875 for the cache write on step 1 (5,000 tokens at $3.75/million). Total: $0.026 per contract, down from $0.090 (a 71% reduction on the system-prompt token segment).

A document processing pipeline built on Chase Agents handles this naturally: each step's LLM call is constructed independently from the step's configured system prompt. When the static legal template leads each step's prompt (rather than the injected contract text), steps 2-6 send an identical prefix to step 1 every time. The Anthropic API sees the same prefix repeatedly within the 1-hour window and returns cache hits for each subsequent step. The same pipeline built in a chat-style conversational system would fail, because growing conversation history shifts the prefix with every turn.

What to check right now

Inspect the usage object in your Claude API responses and look at cache_read_input_tokens. A value of zero means the TTL is expiring between calls or prompt ordering breaks the prefix match.

The fastest diagnostic: add cache_control with "type": "ephemeral" to a large static block, fire two requests within 5 minutes with identical system content, and check whether the second request shows non-zero cache_read_input_tokens. If it does, caching is working. If it doesn't, check your prompt order. If it still doesn't after reordering, switch to the 1-hour TTL.

Most caching guides measure savings per request. That's the wrong frame for automation. The questions that matter are whether your prefix is stable across steps and whether your run duration fits within the TTL window. Get those right in the design phase. Retrofitting an ordering fix into 8 existing workflows is a full engineering day, not a config change.