Place cache_control marker
What you'll learn
The cache marker says 'everything above this is the same every call — please cache it.' Put it right after the stable stuff and before anything that changes.
- cache_control: ephemeral marks a cache breakpoint. Above = cached; below = fresh.
- Place after the largest stable prefix, before per-request content.
- Cache reads ≈ 10% of input cost. Cache writes ≈ 125% of input cost (one-time).
Prompt caching with `cache_control: {type: "ephemeral"}` lets you mark a point in the prompt where the prefix above is cached and can be re-used at ~10% of the input cost on subsequent calls. The marker creates a *cache breakpoint*; everything before it is cached, everything after is fresh on every call. Placement is the entire game — wrong placement either caches nothing useful (marker too early) or caches too much volatile content (marker too late, cache misses constantly).
The placement rule: put the cache_control marker *after* the largest stable prefix and *before* the per-request content. Stable = identical bytes on every call (system prompt, large reference doc, schema). Per-request = anything that varies (today's date, the user's question, retrieved context). The marker goes at the boundary. Place it too early and you fail to cache the second large stable block; too late (mid-volatile-content) and the cache key changes per call and you cache-miss every time.
The economics matter and the exam tests them. A 30,000-token system prompt + 200-token user question, called 500 times/day: without caching, that's 15M input tokens/day. With caching at the boundary, only the first call pays full price; the next 499 read from cache at ~10% of the input rate — order-of-magnitude cost reduction. The break-even is small (a handful of calls); for any non-trivial reuse, caching is the highest-leverage cost lever.
Two operational notes. First, the cache has a TTL (typically 5 minutes, refreshable on hit) — high-frequency callers get sustained cache hits; sporadic callers may pay the write cost more often. Second, the *exact bytes* of the prefix must match — even one character difference invalidates the cache. This is why volatile-data leaks into the system prompt (B3.6) are so expensive: they make every call a cache miss.
Key points
- cache_control: ephemeral marks a cache breakpoint. Above = cached; below = fresh.
- Place after the largest stable prefix, before per-request content.
- Cache reads ≈ 10% of input cost. Cache writes ≈ 125% of input cost (one-time).
- TTL ~5 minutes, refreshes on hit. High-frequency = sustained savings.
- Exact-byte match required. Volatile content in the prefix = perpetual cache miss.
Examples
system: [10K reference doc] [cache_control: ephemeral] [today's date] user: <question> The doc is cached; date + question are fresh. 500 calls/day → 1 cache write + 499 cache reads on the doc.
system: [10K reference doc] [today's date] [cache_control: ephemeral] user: <question> Date changes daily → entire prefix changes daily → cache invalidates daily. The doc is in the cache key but moves with the date. Net: 1 cache write per day, no useful reuse.
Pitfalls
- Marking too early — cache is set but the second large stable block (e.g. tool definitions) goes uncached.
- Marking too late — volatile content above the marker invalidates the cache key on every call.
- Putting per-request data in `system` and then trying to cache. The system prompt's bytes change per call; caching is impossible.
- Caching when the call frequency is too low to amortise the cache-write cost. Math the breakpoint.
Source notes: 00-academy-basics/notes/04-claude-api.md
Ask Claude
Build a prompt with this lesson + your question, copy it, and open the Claude Project in a new tab.