Study guide
2.1 Prompt Caching Mechanics & Breakpoints
Claude Certified Developer - Foundations CCDV-F
Track your progress as you read
Finished sections get a check mark.
1 Chapter 1: Core Messages API & Streaming
1.1 Messages API Fundamentals & Request Lifecycle 1.2 Streaming & Server-Sent Events (SSE) 1.3 Thinking: Adaptive Mode, Effort & Reasoning Budgets
2 Chapter 2: Optimization & Asynchronous Batches
2.1 Prompt Caching Mechanics & Breakpoints 2.2 Message Batches API & Asynchronous Workloads
3 Chapter 3: Structured Outputs, Documents & Files API
3.1 Structured Outputs & JSON Extraction 3.2 Files API, Document Blocks & Citations
4 Chapter 4: Application Design, Resilience & Delivery Life Cycle
4.1 API Resilience, Error Handling & Retries 4.2 Production Backend Architecture & State Management 4.3 Requirements Analysis & Claude Application Design 4.4 The Claude Application Life Cycle & Configuration Management
5 Chapter 5: LLM Fundamentals, Model Selection & Versioning
5.1 LLM & Technical Fundamentals: Tokens, Context Windows & Sampling 5.2 Claude Model Family Selection 5.3 Model Versioning, Snapshot Pinning & Migration 5.4 Latency & Throughput Optimization
6 Chapter 6: Cost Engineering & Context Management
6.1 Production Cost Optimization Strategies 6.2 Context Window Management & Compaction
7 Chapter 7: Foundations of Workflows & Deterministic Patterns
7.1 Agent vs. Workflow Architectural Foundations 7.2 Workflow Patterns: Prompt Chaining & Routing 7.3 Workflow Patterns: Parallelization & Voting
8 Chapter 8: Autonomous Agents & Multi-Step Systems
8.1 Workflow Patterns: Orchestrator-Workers & Evaluator-Optimizer 8.2 Agent Loop Implementation & State Tracking 8.3 Agent Frameworks & Human-in-the-Loop (HITL)
9 Chapter 9: Prompt and Context Engineering
9.1 System Prompt Design & Role Framing 9.2 XML Tags & Structural Prompt Delimiters 9.3 Few-Shot Prompting & In-Context Learning 9.4 RAG Context Injection & Document Formatting
10 Chapter 10: Tool Calling & Model Context Protocol (MCP)
10.1 Tool Schema Design & Parameter Validation 10.2 Tool Execution, Multi-Tool Calls & Error Handling 10.3 MCP Architecture & Core Primitives 10.4 MCP Transports & Client/Server Integration 10.5 Agentic Customization: Built-in Tools, Custom Tools, Skills & MCP
11 Chapter 11: Security, Safety & Governance
11.1 Direct & Indirect Prompt Injection Defenses 11.2 Tool Permissions, Sandboxing & Least Privilege 11.3 Data Privacy, Redaction & Audit Logging 11.4 Identity, Secrets & API Key Management
12 Chapter 12: Claude Code Developer Tooling
12.1 Claude Code Architecture & Project Configuration 12.2 Permissions, Modes & Hooks
13 Chapter 13: Evaluation, Testing & Production Observability
13.1 Evaluation Design & Golden Datasets 13.2 Production Observability, Tracing & Debugging
2.1 Prompt Caching Mechanics & Breakpoints
Key Takeaways Explain This Topic AI
Prompt caching can be enabled automatically with one top-level cache_control field, which moves the breakpoint forward as a conversation grows, or explicitly on individual content blocks for fine-grained control.
A request supports at most 4 cache breakpoints, automatic caching consumes one of them, and a fifth returns a 400 error.
Cache writes cost 1.25x base input for the 5-minute TTL and 2x for the 1-hour TTL, while reads cost 0.1x on most models (0.05x on Claude Opus 5.5 and Claude Sonnet 5.5, 0.025x on Claude Fable 5.1), so a 5-minute cache pays for itself after one read and a 1-hour cache after two.
Minimum cacheable prefix length is model-specific and does not track the tier hierarchy: 512 tokens on every current model (Claude Fable 5.1, Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5), 1,024 on the legacy Claude Sonnet 5, and 4,096 on the legacy Claude Haiku 4.5.
The cache prefix is built in the order tools, then system, then messages, so any change to tool definitions invalidates the entire cache including system and message breakpoints.
Last updated: October 2026
2.1 Prompt Caching Mechanics & Breakpoints
Core Concept: Anthropic prompt caching reuses transformer prefix key-value (KV) tensors so a repeated prompt prefix is read back at 0.1x the base input price on most models (0.05x on Claude Opus 5.5 and Claude Sonnet 5.5, 0.025x on Claude Fable 5.1 and Claude Mythos 5.1), with improved time-to-first-token for long prompts. Caching is configured with cache_control: {"type": "ephemeral"} , either automatically with one top-level field or explicitly on individual content blocks. Prompt caching is the single highest-leverage cost lever in the Cost and Token Management sub-skill.
The Prefix Caching Mechanism
When a large language model processes a sequence of input tokens, it computes Key and Value (KV) vector embeddings for each token at every transformer attention layer. In a conventional stateless API, every invocation forces the inference engine to recalculate these KV projections from token 0 through the end of the prompt—even if 95% of the prompt is identical to the preceding call. This redundant recomputation creates substantial GPU overhead, inflates time-to-first-token (TTFT) latency, and drives up token processing costs.
Anthropic's Prompt Caching introduces a stateful prefix caching layer across Anthropic's distributed inference infrastructure. When a prompt is submitted with designated caching instructions, the inference cluster calculates the KV representations for the designated prefix and saves them in an ephemeral, high-speed memory cache. On subsequent requests that share the exact same prefix sequence:
The inference cluster detects the prefix match starting from token 0.
It bypasses the transformer prefill computation for all cached tokens.
It streams the precomputed KV tensors directly into GPU memory.
The model begins generating completion tokens sooner, which improves TTFT for long prompts.
Because serving pre-computed KV tensors takes far less work than running forward attention passes over thousands of tokens, Anthropic passes the efficiency through as a 0.1x multiplier on cache read tokens on most models — a 90% discount off base input price. Claude Opus 5.5 and Claude Sonnet 5.5 read at 0.05x , and Claude Fable 5.1 and Claude Mythos 5.1 at 0.025x ($0.25 per MTok). Standard Request (No Cache):
[System Prompt (3,000 tok)] + [Tools (1,500 tok)] + [User Query (50 tok)]
==> GPU recomputes attention for all 4,550 tokens from scratch every request.
Cached Request (Prefix Hit):
- [System Prompt (3,000 tok)] + [Tools (1,500 tok)] ==> READ FROM KV CACHE (0.1x cost or less, faster TTFT)
- + [User Query (50 tok)] ==> Standard computation (1.0x cost)
- Two Ways to Enable Caching
- Automatic caching (the recommended starting point)
Add a single cache_control field at the top level of the request . The system places the breakpoint on the last cacheable block and moves it forward automatically as the conversation grows: {
- "model": "claude-sonnet-5-5",
- "max_tokens": 1024,
- "cache_control": { "type": "ephemeral" },
- "system": "You are an enterprise support intelligence agent...",
- "messages": [{ "role": "user", "content": "..." }]
- }
This is the right default for a chat or agent loop, because it removes the most common source of cache misses: a hand-placed breakpoint that stops moving as history grows.
Explicit cache breakpoints (fine-grained control)
Place cache_control directly on individual content blocks when you need to control exactly what is cached — for example, to cache tool definitions and a document corpus under separate breakpoints so a tool change does not invalidate the corpus: "cache_control": { "type": "ephemeral" }
"ephemeral" is the only supported cache type.
Placement Rules and Limits
Maximum Breakpoints: A request may carry at most 4 cache breakpoints . Automatic caching consumes one of those 4 slots; if 4 explicit breakpoints already exist, the request returns a 400 error .
Supported Structures: Breakpoints can be declared inside:
System Prompts: Within individual content blocks of the system parameter array.
Tool Definitions: Directly inside individual tool schemas within the tools parameter array.
Message History: On content blocks within user or assistant messages in the messages array.
Cumulative Prefix Evaluation: A cache breakpoint marks the boundary of a cached prefix. Everything from token 0 up to and including the block carrying the cache_control marker forms one cached checkpoint. The prefix is built in a fixed order: tools -> system -> messages , so a change to tools invalidates everything after it.
The 20-position lookback. If the hash at your breakpoint does not match, the system walks backward one block at a time for up to 20 positions , checking whether an earlier prefix hash matches a previously cached entry. Consecutive tool_use blocks count as one position, as do consecutive tool_result blocks. This is why a well-placed breakpoint still often hits after a small edit — and why an agent that appends more than 20 blocks between requests can fall off the lookback window entirely.
Python SDK Implementation Example
The following code illustrates a production setup placing cache breakpoints across system instructions, tool definitions, and conversation turns: import anthropic
client = anthropic.Anthropic()
- response = client.messages.create(
- model="claude-sonnet-5-5",
- max_tokens=1024,
- # 1. Cache Breakpoint on Static System Prompt
- system=[
- {
- "type": "text",
"text": "You are an enterprise support intelligence agent. Here is the operational compliance handbook...\n[3,000 tokens of guidelines]",
- "cache_control": {"type": "ephemeral"} # Breakpoint 1
- }
- ],
- # 2. Cache Breakpoint on Tools Library
- tools=[
- {
- "name": "lookup_customer_record",
- "description": "Retrieves comprehensive CRM record by customer ID.",
- "input_schema": {
- "type": "object",
- "properties": {"customer_id": {"type": "string"}},
- "required": ["customer_id"]
- }
- },
- {
- "name": "execute_refund",
- "description": "Issues refund transaction against payment gateway.",
- "input_schema": {
- "type": "object",
- "properties": {
- "transaction_id": {"type": "string"},
- "amount_cents": {"type": "integer"}
- },
- "required": ["transaction_id", "amount_cents"]
- },
- "cache_control": {"type": "ephemeral"} # Breakpoint 2: caches all tools up to here
- }
- ],
- # 3. Cache Breakpoint on Historical Multi-Turn Conversation
- messages=[
- {
- "role": "user",
- "content": "Here is the customer diagnostic dump from server logs: [1,200 tokens of log lines]"
- },
- {
- "role": "assistant",
- "content": [
- {
- "type": "text",
- "text": "I have parsed the diagnostic logs and identified three memory pressure warnings.",
- "cache_control": {"type": "ephemeral"} # Breakpoint 3: caches log context + assistant turn
- }
- ]
- },
- {
- "role": "user",
- "content": "What remediation actions should I execute first?" # Dynamic tail (not cached)
- }
- ]
- )
- Token Thresholds and Silent Bypass Mechanics
To ensure GPU memory allocations remain efficient, Anthropic enforces minimum token thresholds for prompt caching. The caching engine will only write a prefix to the KV cache if the cumulative number of tokens from token 0 up to the breakpoint meets or exceeds the model's threshold.
Model Minimum Cacheable Prefix Threshold
Claude Fable 5.1, Claude Opus 5.5, Claude Sonnet 5.5, Claude Haiku 5.5 (the current lineup), Claude Opus 5 512 tokens
- Claude Sonnet 5 , Claude Opus 4.8, Claude Sonnet 4.6 1,024 tokens
- Claude Opus 4.7 2,048 tokens
- Claude Haiku 4.5 , Claude Opus 4.6, Claude Opus 4.5 4,096 tokens
Note the shape of that table: the thresholds do not track the tier hierarchy or the release order. Every current model, the fast Claude Haiku 5.5 included, caches from 512 tokens, while the legacy Claude Haiku 4.5 needs an 8x larger prefix before anything is cached at all. A 2,000-token system prompt caches on every current model and on Claude Sonnet 5, and silently does not cache on Haiku 4.5 — which is exactly the trap on a cost-optimisation question that routes cheap traffic to the legacy Haiku 4.5.
The Silent Bypass Rule
A frequent trap on the certification exam involves sub-threshold behavior. If a developer includes cache_control: {"type": "ephemeral"} on a prompt block where the cumulative prefix contains fewer tokens than the threshold (for example, 650 tokens on Claude Sonnet 5, or 3,000 tokens on Claude Haiku 4.5):
The API does not reject the request.
No HTTP 400 error or validation exception is thrown.
The request silently bypasses caching : no cache write occurs, no cache read occurs, and all input tokens are billed at standard base input rates.
In the response telemetry, cache_creation_input_tokens and cache_read_input_tokens will both register as 0 .
Cache Lifetime, Eviction, and Economic Modeling
Prompt cache entries have a default Time-to-Live (TTL) of 5 minutes , with an opt-in 1-hour tier: { "cache_control": { "type": "ephemeral", "ttl": "1h" } }
The TTL is measured from the start of the request that writes or reads the cache , not from when the response finishes — so a long generation spends part of its own cache lifetime.
The Sliding TTL Window
The 5-minute TTL is not an absolute, immutable timer; it operates as a sliding refresh window :
When a prompt is first cached, the system writes the entry and sets the 5-minute expiration countdown.
Whenever a subsequent request matches the cached prefix and triggers a cache read , the 5-minute TTL automatically resets back to 5 minutes .
As long as your application hits the cache at least once every 4 minutes and 59 seconds, the cached prefix can remain active indefinitely in memory.
If 5 minutes pass without any request hitting the prefix, the entry is evicted. The next request with that prefix must perform a fresh cache write .
Token Pricing Economics
Caching introduces three input-token billing tiers, expressed as multipliers on the model's base input price:
- Cache operation Multiplier Duration
- Base (un-cached) input 1.0x n/a
- 5-minute cache write 1.25x base input Cache valid 5 minutes
- 1-hour cache write 2x base input Cache valid 1 hour
Cache read (hit) 0.1x base input on most models; 0.05x on Claude Opus 5.5 and Claude Sonnet 5.5; 0.025x on Claude Fable 5.1 and Claude Mythos 5.1 Same duration as the preceding write
Break-Even Analysis
The multipliers make break-even arithmetic simple and exam-testable:
A 5-minute cache write costs 1.25x and a read costs 0.1x or less, so caching pays off after a single read. A 1-hour write costs 2x, so it pays off after two reads.
Worked example on Claude Sonnet 5.5 ($2.00/MTok base input):
- Cache write (5m): $2.50 per MTok ($2.00 x 1.25)
- Cache read: $0.10 per MTok ($2.00 x 0.05)
For a 4,000-token stable prefix:
Without caching, 2 calls: 2 x 4,000 x $2.00/M = $0.0160
With caching, 2 calls (1 write + 1 read): (4,000 x $2.50/M) + (4,000 x $0.10/M) = $0.0100 + $0.0004 = $0.0104 — a 35% saving after one read.
Over 20 calls in a session:
Un-cached: 20 x 4,000 x $2.00/M = $0.160
Cached: (4,000 x $2.50/M) + 19 x (4,000 x $0.10/M) = $0.0100 + $0.0076 = $0.0176 — an 89% reduction.
The same calculation on the legacy Claude Sonnet 5 , also $2.00/MTok base but reading at 0.1x ($0.20 per MTok), gives $0.0108 (a 32.5% saving) and $0.0252 (an 84.25% reduction). Write multipliers are the same on every model, but read multipliers differ (0.1x, 0.05x, or 0.025x), so the savings ratio depends on the model , not just the absolute dollars.
Comprehensive Cost Reference Table
- Model Base Input / MTok 5m Write (1.25x) 1h Write (2x) Cache Read Base Output / MTok Min Cache Tokens
- Claude Haiku 5.5 (prompts up to 100,000 tokens) $0.10 $0.125 $0.20 $0.01 (0.1x) $0.50 512 tokens
- Claude Sonnet 5.5 $2.00 $2.50 $4.00 $0.10 (0.05x) $10.00 512 tokens
- Claude Opus 5.5 $4.00 $5.00 $8.00 $0.20 (0.05x) $20.00 512 tokens
- Claude Fable 5.1 $10.00 $12.50 $20.00 $0.25 (0.025x) $50.00 512 tokens
- Claude Sonnet 5 (legacy) $2.00 $2.50 $4.00 $0.20 (0.1x) $10.00 1,024 tokens
- Claude Haiku 4.5 (legacy) $1.00 $1.25 $2.00 $0.10 (0.1x) $5.00 4,096 tokens
Claude Haiku 5.5 prompts over 100,000 tokens are priced higher ($0.50 base input, $0.05 cache read, $2.50 output per MTok).
These multipliers stack with other pricing modifiers , including the 50% Batch API discount.
Telemetry: Inspecting the usage Object
Production observability requires monitoring how effectively your application hits the prompt cache. Every response from the Messages API returns a usage object containing granular token attribution: {
- "id": "msg_01ABcDeF...",
- "type": "message",
- "role": "assistant",
- "content": [{"type": "text", "text": "Customer account balance is verified."}],
- "model": "claude-sonnet-5-5",
- "stop_reason": "end_turn",
- "usage": {
- "input_tokens": 42,
- "cache_creation_input_tokens": 2850,
- "cache_read_input_tokens": 0,
- "output_tokens": 68
- }
- }
- Understanding Telemetry Fields
cache_creation_input_tokens : The count of tokens written to the cache during this request. Billed at 1.25x base rate for the 5-minute TTL and 2x for the 1-hour TTL.
cache_read_input_tokens : The count of tokens successfully read from the existing cache. Billed at 0.1x base rate on most models (0.05x on Claude Opus 5.5 and Claude Sonnet 5.5, 0.025x on Claude Fable 5.1).
input_tokens : The un-cached delta tokens. These are tokens appearing after the last cache breakpoint, or tokens that fell below minimum thresholds. Billed at standard 1.0x base rate.
output_tokens : Completion tokens generated by the model. Billed at standard output rates.
- On a successful second request hitting the cache: "usage": {
- "input_tokens": 42,
- "cache_creation_input_tokens": 0,
- "cache_read_input_tokens": 2850,
- "output_tokens": 74
- }
- Architectural Best Practices: Prefix Stability & Invalidation Traps
The single most critical architectural principle for prompt caching is Prefix Stability . The caching engine performs strict, deterministic prefix matching starting from token 0. If even one character, whitespace, or token changes early in the prompt, the cache lookup fails for that point and invalidates all subsequent breakpoints .
1. Optimal Content Ordering Hierarchy
To maximize cache hit rates, structure prompts strictly from most static to most dynamic: [Token 0] ──────────────────────────────────────────────────────────> [End of Prompt]
- ┌────────────────────────┬───────────────────┬──────────────────────┬────────────────┐
- │ Static System Prompt │ Tool Definitions │ Long Reference Docs │ Dynamic User │
- │ & Base Instructions │ (Schemas) │ & Few-Shot Examples │ Query & Turns │
- │ [Breakpoint 1] │ [Breakpoint 2] │ [Breakpoint 3] │ [Breakpoint 4] │
- └────────────────────────┴───────────────────┴──────────────────────┴────────────────┘
- STATIC ──────────────────────────────────────────────> DYNAMIC
- 2. Common Cache Invalidation Anti-Patterns
Developers frequently inadvertently destroy caching benefits through these common traps:
Dynamic Timestamps in System Prompts: Placing "Current Date/Time: 2026-09-10 05:33:38" at the top of a system prompt alters token 0-15 on every request. This ensures every request produces a 100% cache miss, forcing a continuous stream of expensive 1.25x cache creation writes! Dynamic timestamps must be placed at the very end of the prompt (in the dynamic user message) or after all static cached blocks.
Randomized or User-Specific Identifiers: Prepending session IDs, user IDs, or tracing headers in the system prompt fragments the cache per user rather than sharing a single global cache across all users.
Changing tool definitions at all: because the prefix order is tools -> system -> messages , editing, adding, or removing a tool invalidates the entire cache, including system and message breakpoints. Toggling web search or citations invalidates system and message caches. Changing tool_choice , adding or removing images, or changing the thinking or effort configuration invalidates the message blocks.
Unordered Tool Schemas: In languages like Python or Go where dictionary iteration order can vary if not sorted, serializing tool lists non-deterministically causes tools to appear in random order, breaking prefix token sequences. Always sort tool definitions deterministically before passing them to the API.
Variable JSON Formatting: Subtle changes in formatting (such as changing indentation from 2 spaces to 4 spaces, or altering key order in few-shot JSON examples) changes the token sequence and triggers cache eviction.
3. Multi-Turn Conversation Breakpoint Strategy
In multi-turn chat interactions, each turn appends new tokens. If you place a breakpoint only on the system prompt, you benefit from caching the system prompt, but each turn recomputes all prior dialogue history.
The recommended pattern is to maintain a sliding breakpoint on the penultimate turn :
Keep Breakpoint 1 on the static system prompt.
Keep Breakpoint 2 on the tool declarations.
Place Breakpoint 3 on the last assistant response before the user's latest query.
This ensures that the entire dialogue history up to the current turn is read from cache at the cache-read rate (a 90% to 97.5% discount, depending on the model), while only the user's latest message and Claude's new reply are processed at standard rates.