🌱 Fundamentals and terms
Before changing anything, understand what prompt caching is and the vocabulary around it. By the end, you’ll know why the cache exists, what hit, miss, write, and TTL mean, and why a long conversation can cost ~10% instead of 100%. Each technical term is defined the first time it appears — no API prerequisites.
Illustration: the beginning of the conversation (the prefix) is always assembled
in the order tools → system → histórico. It is processed once, written
to the cache, and afterward only reread every turn—cheap. Track 1 breaks down this entire mechanism
piece by piece.
Trail map
Detailed content
🧩 What prompt caching is
From the reprocessing problem to the prefix idea: hit, miss, write, the order
tools → system → messages and the breakpoint. Define each term at its first occurrence.
The Claude API is stateless — doesn’t store the conversation. With each message, you resend everything: the system prompt, tools, and entire history.
It’s the problem the cache solves. Without understanding reprocessing, nothing else makes sense.
stateless · system prompt · resend the entire conversation · cost and latency that grow with each turn.
The beginning of the conversation is stable and repeats every turn. The cache stores that beginning after processing and reuses it instead of processing it again.
It’s the turning point: pay once for what doesn’t change, instead of paying every turn.
stable prefix · processed once · reuse · what changes goes at the end.
The cache key is the exact bytes up to the breakpoint. A single different byte in the middle invalidates everything after it.
Explains every "why didn't my cache hit?" It's the invariant that governs the entire track.
prefix · exact bytes · cutoff point · invalidation starting at the byte that changes.
The prompt is assembled in this order. A breakpoint at the end of the system caches tools + system together.
Knowing the order tells you what to put at the beginning (stable) and what to leave at the end (changes).
assembly order · position 0 = tools · stable things at the beginning · volatile things at the end.
Hit = read from the cache (cheap). Write = recorded in the cache (small premium). Miss = not found, processed in full. The 1st message records; the following ones read.
It’s the vocabulary you’ll see in the fields of usage and use it for diagnosis.
hit · miss · write · 1st message writes, next ones read.
The marker that says “cache up to here.” Max. 4 per request; minimum prefix ~1024–4096 tokens (varies by model)—below that, it isn’t cached and no error is returned.
In Claude Code, it's automatic, but understanding the concept explains why short sections aren't cached.
cache_control · max. 4 breakpoints · minimum cacheable · automatic in Claude Code.
💸 Terms and savings
The three fields of usage, the 5-minute and 1-hour TTLs, the relative costs,
and the break-even calculation. The real savings, no mystery.
Tokens served from the cache this turn. They cost ~0.1× the input price.
It’s the field that proves the cache was hit. A repeated zero for the same prefix means something’s wrong.
cache read · ~0.1× · hit signal.
Tokens written to the cache this turn. They cost ~1.25× (TTL 5 min) or ~2× (TTL 1 h).
It’s the “premium” you pay once to read cheaply later. Seeing it high all the time is a sign that the cache never reads.
writing · ~1.25× / ~2× · paid once per new block.
Only the uncached portion, at full price (1×). The total prompt = the sum of the three fields.
Catch: if the agent ran for hours and input_tokens shows little; the rest came from the cache — look at the SUM of the three.
uncached portion · 1× · total = sum of the three.
TTL = how long the cache entry lives. Default is 5 min, renewed with each use. There’s a 1 h option (write ~2×) for traffic with long pauses.
Explains why an active conversation stays "warm" and a long pause makes you pay for another write.
TTL · 5 min renewable · 1 h more expensive · active conversation keeps it warm.
read ~0.1× · write 5 min ~1.25× · write 1 h ~2× · uncached 1×. In a long conversation, most of the input is billed at ~10%.
These are the four numbers that explain any savings calculation in the course.
cost table · cheap read · write with a premium · full price as a reference.
With a 5-minute TTL, 2 requests are enough to pay for the write (1.25× + 0.1× = 1.35× vs. 2× without caching). With 1 hour, you need ~3.
Teaches you NOT to cache a prefix that changes on every request (you only pay for the write; it’s never read).
break-even point · 2 requests (5 min) / ~3 (1 h) · don't cache what changes all the time.