CONCEPT A breakpoint marks "cache everything up to here"
You turn caching on by attaching cache_control: {"type": "ephemeral"} to a content
block. That marker is a breakpoint: it tells the API to cache the entire prefix
up to and including that block. You don't tag the individual pieces you want cached — you tag the
last block of the stable region, and everything before it is captured. cache_control
can go on a system text block, a tool definition, or a message content block (text,
image, tool_use, tool_result, document).
CONCEPT Max 4 breakpoints — and the minimum length floor
Two hard limits govern breakpoints:
- At most 4
cache_controlbreakpoints per request. Each is a separate cache read/write point, so you can cache several nested prefixes (e.g. one after tools, one after system, one after a stable chunk of history). A 5th marker is rejected. - A minimum cacheable prefix length. A prefix shorter than the model's floor is
silently not cached — no error, just
cache_creation_input_tokens: 0. The floor is model-dependent:
| Model | Minimum cacheable prefix |
|---|---|
| Claude Fable 5 / Mythos 5 | 512 tokens |
| Claude Opus 4.8 · Sonnet 5 · Sonnet 4.6 | 1024 tokens |
| Claude Opus 4.7 · Haiku 3.5 | 2048 tokens |
| Claude Opus 4.6 · Opus 4.5 · Haiku 4.5 | 4096 tokens |
cache_creation_input_tokens is 0 on a fresh prefix, you're
likely under the minimum.cache_control on
messages.create() auto-places the breakpoint on the last cacheable block — the simplest option
when you don't need fine-grained placement.DIAGRAM One request, multiple nested breakpoints
caches tools"] BP1 --> S["system prompt (static)"] S --> BP2["🟢 breakpoint #2
caches tools + system"] BP2 --> H["stable conversation history"] H --> BP3["🟢 breakpoint #3
caches tools + system + history"] BP3 --> V["volatile: newest user turn"] V --> X["🔴 no breakpoint here
→ processed fresh (1×)"] classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef bad fill:#f8d7da,stroke:#dc3545,color:#721c24; classDef neutral fill:#e7f1ff,stroke:#4a90d9,color:#1a4971; class BP1 ok; class BP2 ok; class BP3 ok; class X bad; class T neutral; class S neutral; class H neutral; class V neutral;
CODE Placing breakpoints across tools and system
Render order is tools → system → messages (see 2.3), so a breakpoint on the last system block also caches the tools ahead of it. Here two breakpoints cache the tool catalog and the system prompt independently.
resp = client.messages.create( model="claude-opus-4-8", max_tokens=1024, tools=[ {"name": "search", "description": "...", "input_schema": {...}}, {"name": "lookup", "description": "...", "input_schema": {...}, "cache_control": {"type": "ephemeral"}}, # breakpoint 1: caches all tools ], system=[{ "type": "text", "text": LONG_SYSTEM_PROMPT, "cache_control": {"type": "ephemeral"}, # breakpoint 2: caches tools + system }], messages=[{"role": "user", "content": user_question}], # volatile — no marker ) # Max 4 breakpoints total; a prefix under the model's floor caches nothing.
TRADE-OFFS One breakpoint vs. several
✅ Multiple breakpoints
- Partial reuse — a change late in the prefix still hits earlier breakpoints
- Fits growing agent loops (cache tools, then system, then history)
- Up to 4 nested cache points per request
⚠️ Just one (or top-level auto)
- Simplest to reason about; fewest ways to misplace
- All-or-nothing: a byte change before it invalidates the whole cache
- Enough for a single frozen system prompt shared across calls
EXAM TRAPS
cache_control on every block I want cached." → You tag only the
last block of the stable region. The breakpoint caches the whole prefix up to it — tagging each block
wastes your 4-breakpoint budget.cache_creation_input_tokens.PRACTICE
Q1 · Where do you place cache_control to cache a long system prompt?
On the last content block of the system prompt (or use top-level auto-placement). The breakpoint caches everything up to and including it — which, given render order, also captures any tools ahead of the system prompt.
Q2 · How many breakpoints can one request have, and what happens at the 5th?
Four. A request with more than four cache_control markers is rejected —
budget them across your stable regions (tools, system, history).
Q3 · Your fresh prefix shows cache_creation_input_tokens: 0. Cause?
The prefix is almost certainly below the model's minimum cacheable length (e.g. under 1024 tokens on Opus 4.8, or under 4096 on Haiku 4.5). Short prefixes are silently processed uncached — no error is raised.