D5 · Context & Reliability › Cluster 2 · Prompt Caching

2.2 · cache_control & Breakpoints

Mark the reusable prefix

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).

🔑 A breakpoint is a boundary, not a wrapper. Place it on the last block of the reusable prefix; the cache key is the hash of all bytes preceding and including it.

CONCEPT Max 4 breakpoints — and the minimum length floor

Two hard limits govern breakpoints:

ModelMinimum cacheable prefix
Claude Fable 5 / Mythos 5512 tokens
Claude Opus 4.8 · Sonnet 5 · Sonnet 4.61024 tokens
Claude Opus 4.7 · Haiku 3.52048 tokens
Claude Opus 4.6 · Opus 4.5 · Haiku 4.54096 tokens
⚠️ Do not guess the floor. A 3K-token prompt caches on Opus 4.8 (1024) but silently won't on Haiku 4.5 (4096). If cache_creation_input_tokens is 0 on a fresh prefix, you're likely under the minimum.
Convenience shortcut: a top-level 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

flowchart TD T["tools (static)"] --> BP1["🟢 breakpoint #1
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

Trap: "Put 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.
Trap: "I can use as many breakpoints as I like." → Maximum 4 per request.
Trap: "My small prompt didn't cache, so caching is broken." → It's likely below the model's minimum (512–4096 tokens depending on the model). Short prefixes are silently not cached — check cache_creation_input_tokens.
Trap: "The minimum is the same for all models." → It varies by model: 1024 on Opus 4.8/Sonnet, up to 4096 on Haiku 4.5 and Opus 4.6/4.5. Verify per model.

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.