Claude API Prompt Caching: How cache_control Works

Prompt caching stores a reusable prefix of your API request on Anthropic's servers. Add cache_control: {"type": "ephemeral"} to any content block — system prompt, tool definitions, or long message history — and subsequent requests with a byte-identical prefix skip reprocessing those tokens, cutting input costs by up to 90%.

For CCA-F candidates, prompt caching is a tested cost-optimization pattern — expect questions on breakpoint placement, TTL trade-offs, and how to verify hits via the usage API.

How does Claude prompt caching work under the hood?

Caching is a prefix match. When your request includes a cache_control marker, the API hashes the exact bytes of the prompt up to that breakpoint and stores them. The next request with an identical prefix hits the cache; any byte difference — a changed word, a reordered JSON key, a timestamp — invalidates everything at and after that point.

Requests render to the model in a fixed order: tools first, then system, then messages. A breakpoint on the last system block therefore caches your tool definitions and your system prompt as a single entry. This ordering is why volatile content — the current date, a per-user session ID, the actual user question — must live after any cache marker. Whatever precedes the marker becomes part of the cache key, so it must be byte-for-byte identical across requests that should share a hit.

What is the cache_control parameter syntax?

Place a cache_control object on any supported content block:

{
  "system": [
    {
      "type": "text",
      "text": "You are a senior support agent with access to these 300 pages of product documentation...",
      "cache_control": {"type": "ephemeral"}
    }
  ],
  "messages": [{"role": "user", "content": "How do I reset 2FA?"}]
}

For cases where you do not need fine-grained placement, a top-level cache_control on messages.create() auto-places the marker on the last cacheable block:

{
  "model": "claude-opus-4-8",
  "max_tokens": 1024,
  "cache_control": {"type": "ephemeral"},
  "system": "Your large system prompt here...",
  "messages": [...]
}

You can place up to four cache_control breakpoints per request. Each creates an independent cache entry at that prefix boundary, so you can have separate entries for your tool schemas, your system prompt, and a long few-shot block.

What TTL options are available for Claude prompt caching?

Two time-to-live settings are available:

• 5 minutes (default) — {"type": "ephemeral"} — suited to bursts of related requests arriving within a short window
• 1 hour — {"type": "ephemeral", "ttl": "1h"} — suited to sporadic traffic where requests arrive more than five minutes apart

The TTL choice directly affects cost. Cache writes at the 5-minute TTL are priced at 1.25× the normal input token rate; at the 1-hour TTL the write cost is 2×. The economics differ accordingly: with the default TTL you break even after just two requests (1.25× write + 0.1× read versus 2× uncached), while the 1-hour TTL requires at least three requests to offset its higher write premium. For steady API traffic the default TTL is almost always the right call. For nightly batch pipelines or weekly report generation, the 1-hour TTL keeps your cache warm across the gaps.

How much does prompt caching cost?

Cache reads cost approximately 0.1× the standard input token price for that model. On Claude Opus 4.8 — priced at $5.00 per million input tokens — a cache-read token costs roughly $0.50 per million, a 90% reduction. Cache write tokens carry a premium because Anthropic is processing and storing the prefix: 1.25× at the 5-minute TTL, or 2× at the 1-hour TTL.

The practical effect is significant for any prompt with a large shared prefix. A 50,000-token system prompt sent 100 times a day without caching costs $25.00 at Opus 4.8 rates. With caching: one write at roughly $0.31, plus 99 reads at roughly $0.025 each — a total under $3.00. You keep the same system prompt quality; you eliminate 88% of the daily token spend on it.

What can be cached — system prompts, tools, or messages?

The cache_control marker can appear on any of these block types:

• System prompt text blocks — the most common case; cache a large instruction set, policy document, or knowledge corpus that most requests share
• Tool definitions — cache a stable schema array so Claude does not re-read 30 tool definitions on every call; because tools render first in wire order, a breakpoint on the last system block caches tools automatically
• Message content blocks — useful in multi-turn agents for caching the growing conversation history prefix, with the breakpoint moving forward each turn
• Document blocks — cache a large PDF or uploaded reference document that many questions will reference in the same session

The key architectural decision is always where to place the breakpoint. Everything before it must be byte-identical across requests that should share a cache hit. Everything after it can vary freely per request.

What is the minimum token threshold for caching to activate?

Anthropic enforces a minimum prefix length before a cache entry is created. If your prompt is below the threshold, the API silently skips caching — you receive no error, but cache_creation_input_tokens stays at zero.

Current Opus-class models (Opus 4.6, 4.7, and 4.8) and Haiku 4.5 require a minimum of 4,096 tokens before a cache entry is written. Claude Sonnet 4.6 requires 2,048 tokens. Older Sonnet models (Sonnet 4.5 and earlier) require 1,024 tokens.

This matters in practice: a 3,000-token system prompt caches on Sonnet 4.6 but silently does not cache on Opus 4.8. If you switch model tiers without adjusting your prompt length, your cache hit rate can drop to zero without any visible error. Always verify with the usage fields described below when testing a new model.

How do you verify that prompt caching is actually working?

Check the usage object in every API response. Three fields are relevant:

{
  "usage": {
    "input_tokens": 318,
    "cache_creation_input_tokens": 49850,
    "cache_read_input_tokens": 0
  }
}

On the first request, cache_creation_input_tokens shows how many tokens were written to cache (and charged at the write-premium rate). On subsequent requests with the same prefix, cache_read_input_tokens should be non-zero and input_tokens should show only the non-cached tail of the prompt. If cache_read_input_tokens is persistently zero despite identical-looking prompts, a silent invalidator is breaking your prefix.

What silently breaks prompt caching?

These patterns are responsible for the majority of unexpected cache misses:

• Timestamps or IDs in the system prompt — datetime.now() or uuid4() interpolated into the prompt header before your breakpoint changes the prefix every request
• Non-deterministic serialization — json.dumps(d) without sort_keys=True, or iterating a Python set, can produce different byte sequences across runs even with the same logical data
• Changing the tool set — adding, removing, or reordering tools invalidates the entire prefix because tool definitions render at position zero, before your system prompt
• Switching models mid-session — cache entries are scoped to a specific model; changing the model string forces a full cache miss on every subsequent call
• Conditional system sections — logic like if user_tier == "pro": system += "..." creates a distinct cache key per tier, fragmenting what could be a shared entry

To diagnose a miss, diff the rendered prompt bytes between two consecutive requests that should share a cache hit. The culprit is almost always a timestamp, a UUID, or a JSON key that found its way into content before the breakpoint.

Why does the CCA-F exam cover prompt caching?

The Claude Certified Architect — Foundations exam tests production architecture patterns, and prompt caching is a first-class technique in that domain. It appears in cost-optimization questions (when and why to cache, how to calculate break-even across TTL choices) and in system-design questions (where to place breakpoints, how to keep a prefix stable when multiple services share a prompt, how to handle tool-set changes without thrashing the cache).

Candidates should be able to identify which content belongs before a cache breakpoint — stable, shared, frequently reused — versus after it — volatile, per-request, user-specific. Understanding the silent-invalidator patterns and how to verify cache hits via the usage API are also fair game. Prompt caching is one of the few platform features where a correct architectural decision directly translates into a measurable and immediate cost reduction, which makes it a reliable exam topic.