Price and preserve reusable prompt prefixes

Learning objective

Structure requests for prompt caching and evaluate its economics: stable-prefix ordering, breakpoints, write and read pricing, cache lifetime, and invalidation.

Core idea

Prompt caching reuses processing of an identical request prefix. You still supply the content; caching does not create a document identifier that replaces it. Your architectural decision is which prefix repeats, how often it repeats before expiry, and whether discounted reads repay the write premium.

A cache that writes on every request can cost more than ordinary input. Measure usage.cache_creation_input_tokens and usage.cache_read_input_tokens, rather than treating the presence of cache_control as proof of savings. Prompt component maintenance is a separate concern; see 2.5.2.

How it works

Put the breakpoint on the stable prefix

The prefix follows tools, then system, then messages, through and including the block marked with cache_control. Keep tool definitions and common instructions stable, put use-case context after them, and put request-specific dates, identifiers, and user input after the reusable prefix. Matching requires identical content, including ordering.

An explicit marker can sit on a tool definition, a system content block, or eligible message content, including text, images, documents, tool use, and tool results. Empty text and citation sub-blocks cannot be marked directly. Thinking blocks cannot carry cache_control directly, although previous assistant thinking can be cached with surrounding content.

A system block containing reusable guidance can carry this marker:

{
  "type": "text",
  "text": "STABLE_GUIDANCE",
  "cache_control": { "type": "ephemeral", "ttl": "5m" }
}

Replace STABLE_GUIDANCE with the actual reusable instructions. Send the variable brief in a later message. The cached prefix must meet the selected model’s minimum, so this short illustrative string alone does not qualify.

Automatic caching instead places cache_control at request level and moves its breakpoint to the last cacheable block. It suits growing conversations whose history stays identical. For independent requests with arbitrary user briefs, use an explicit marker before that varying suffix; automatic caching otherwise writes a different entry for each brief.

A request permits four breakpoints, including the automatic one. Each breakpoint checks at most 20 prefix positions backward, including itself, for entries that earlier requests actually wrote. It does not discover an unmarked stable region and write it retrospectively. If a growing history moves the breakpoint 20 or more positions past a prior write, another explicit breakpoint near that position can preserve reuse. On the Claude API, consecutive tool_use blocks count as one position, as do consecutive tool_result blocks.

Qualify length, lifetime, and platform

On the Claude API, Claude Sonnet 5.5, Claude Opus 5.5, and Claude Haiku 5.5 require at least 512 cacheable tokens; Claude Sonnet 5 requires 1,024. These minimums also apply on Claude Platform on AWS, Google Cloud, and Microsoft Foundry where those models are available. For AWS-operated Amazon Bedrock, use its per-model caching documentation rather than transferring this table unqualified.

Below the minimum, the request is processed without caching and without an error. If both cache usage counters are zero, check length before changing lifetime. Both automatic and explicit caching support active Claude models. Automatic caching is unavailable on the legacy Amazon Bedrock integration for Opus 4.6 and earlier: a top-level cache_control returns 400 there, so use explicit markers.

The default ephemeral lifetime is five minutes; ttl: "1h" selects one hour. Reads refresh the lifetime without another write premium. The clock starts at the beginning of the writing or reading request, so a long streamed response consumes part of the interval. With mixed lifetimes, one-hour breakpoints must precede five-minute breakpoints. One-hour caching is documented across the Claude API and the listed cloud integrations, including legacy Bedrock.

Price writes and reads separately

Use the deployed model’s base input price and its cache read multiplier:

For a fixed prefix with one write and H hits, the cost in base-price units is W + H × R, compared with 1 + H without caching. This is a calculation, not a separate API discount. At R = 0.05, the five-minute option beats ordinary input with one hit: 1.30 < 2. The one-hour option needs two hits: one write plus one hit costs 2.05 > 2, while two hits cost 2.10 < 3.

Output and uncached suffix costs remain separate. Cache reads and writes still count toward prompt length, including length-based pricing thresholds. Breakpoints themselves add no fee. Do not sum all writes at one price when lifetimes differ: usage.cache_creation.ephemeral_5m_input_tokens and ephemeral_1h_input_tokens split the total cache_creation_input_tokens. Total input is input_tokens + cache_creation_input_tokens + cache_read_input_tokens; input_tokens alone understates it.

Diagnose misses and cold bursts

Changing tools invalidates tool, system, and message prefixes; changing system content invalidates system and messages. Changing tool_choice or adding or removing images affects message caching. Thinking configuration and output_config.effort invalidate messages and can affect earlier layers depending on the model. A different model also cannot reuse the same entry.

Changing tools invalidates all three prefixes, changing system content invalidates two, and adding or removing images affects message caching.

On the Claude API, opt into cache diagnostics with diagnostics: {"previous_message_id": null} on the first request, then send the preceding response’s id as diagnostics.previous_message_id. The response identifies divergence through diagnostics.cache_miss_reason, including type: "system_changed". Diagnostics need no beta header and are Claude API only; they are not available on Bedrock or Google Cloud. Compare diagnostics with usage: matching requests can still miss after expiry.

An entry becomes readable only after its first writing response begins. For a parallel cold burst, wait for that first response before releasing dependent requests. The documented max_tokens: 0 pre-warm produces no output, but rejects streaming, thinking.type: "enabled", output_config.format, forced tool_choice of any or tool, and Message Batches requests. Preserve the real prefix and compatible thinking and effort settings; a different warm-up configuration may warm nothing useful.

Key distinctions and trade-offs

Stability versus lifetime: A longer lifetime bridges idle gaps; it cannot repair a different prefix. Fix assembly before buying longer retention.

Prefix reuse versus context capacity: Cached tokens remain part of the input. Caching reduces their processing cost, not the information the request contains.

Shared text versus shared entry: Caches on the Claude API, Claude Platform on AWS, and Microsoft Foundry are isolated by organization and workspace; Bedrock and Google Cloud use organization-level isolation only. Identical policy text across separate Claude API workspaces does not produce one shared cache.

Architecture / decision scenario

A financial-services helpdesk sends a 10,000-token policy prefix on Sonnet 5.5. Two measured traffic groups differ: 500 requests arrive within four minutes, while a specialist session makes three requests separated by 20 minutes. The finance owner wants to select one-hour caching everywhere; the platform architect owns the alternative.

For the burst, one five-minute write plus 499 reads costs 1.25 + 499 × 0.05 = 26.20 prefix units, versus 500 uncached. One-hour caching adds write premium without improving that group’s reuse. For the specialist, five-minute caching writes three times, costing 3.75 units; one-hour caching costs 2.10. The architect selects lifetimes by group.

Before release, a request timestamp at the start of system causes repeated writes. The team moves it after the explicit policy breakpoint, fixes tool ordering, checks the 512-token minimum, and records both cache counters. It coordinates the first burst response before fan-out. Finance accepts the measured prefix savings separately from output costs, and the platform team owns diagnostics when a policy release changes the prefix.

Common exam traps

• Marking the varying brief and expecting lookback to cache an earlier unmarked policy.
• Reading input_tokens as the complete input bill.
• Assuming every model charges 0.1 times for reads.
• Increasing lifetime to repair a timestamp-induced miss.
• Treating a warm-up request as compatible with every output configuration.

What to remember

Cache the last stable prefix block, verify the model’s minimum, and calculate writes plus actual hits. Use lifetime to bridge measured reuse gaps. Diagnose misses from usage and request differences, and account for cold bursts before claiming steady-state savings.

Knowledge check

References

• Anthropic, Prompt caching
• Anthropic, Pricing
• Anthropic, Cache diagnostics