💸 Terms and savings
Now for the numbers. Three fields of usage tell the story of each turn,
the TTL determines how long the cache stays warm, and four relative costs explain why a long conversation costs ~10% — and when
the cache has already paid for itself.
📖 cache_read_input_tokens
Every API response includes an accounting block called usage.
The first field that matters is cache_read_input_tokens: the tokens
that were served from the cache in this turn. They cost ~0.1× the input price—
that’s the money the cache saves you.
New here? "usage" and "token"
- usage — the brief usage summary the API returns with the response, saying how many tokens were used and where they came from.
- token — the little piece of text the model counts (~a syllable or short word). Price and size are measured in tokens.
Illustration: the larger this range, the more the cache is working for you. This is the field that proof that there was a hit.
✓ Healthy signal
- ✓
cache_read_input_tokenshigh and growing between turns - ✓Most of the input in a long conversation comes from the cache
✗ Sign of a problem
- ✗Stays 0 even when repeating the same prefix — something is breaking the cache
- ✗Disappears after an action — something changed the prefix
What it is
The field for usage that counts the tokens served from the cache this turn, billed at ~0.1× the input price.
Why learn
It’s objective proof that the cache was hit. Without checking this field, you’re only assuming you’re saving money.
Key concepts
✍️ cache_creation_input_tokens
The second field is cache_creation_input_tokens: the tokens
written to the cache in this turn. Writing has a small premium—it costs ~1.25×
(with a 5 min TTL) or ~2× (with a 1 h TTL). It’s the price you pay once so you can read cheaply later.
The trade-off behind the premium
You pay a little more to write (1.25×), and in return, each subsequent read costs almost nothing (0.1×). It’s an investment: one write now buys many cheap reads later.
- •Write with 5 min TTL ≈ 1,25×
- •Write with 1 h TTL ≈ 2× (more expensive write, longer lifetime)
When this field gets high
It’s normal for it to appear in the first turn (writes the prefix) and whenever a new block is added (a loaded skill, for example). See write all the time, without read, however, signals a cache that writes but never reads—a likely invalidator (you’ll see this in Track 2).
What it is
The tokens written to the cache in this turn, billed at ~1.25× (TTL 5 min) or ~2× (TTL 1 h).
Why learn
Understanding that the write is a one-time cost prevents the shock of seeing a number larger than the full input — and teaches you to wait for the payback.
Key concepts
🧮 input_tokens (the rest)
The third field is input_tokens: only the part
not cached, charged at the full price (1×). And here's the golden rule
for reading usage: the total prompt is the sum
of the three fields — don’t look at one in isolation.
Illustration: if you look only at input_tokens, think the turn was tiny. The true size is the sum — and it's normal for most of it to come from the cache.
The “small input” gotcha
Your agent ran for hours and input_tokens shows a small number? It's not a bug or magical savings: the rest came from the cache. Add the three fields to see the actual amount that was processed.
"usage": {
"cache_read_input_tokens": 98000, // lido do cache · 0,1×
"cache_creation_input_tokens": 1200, // gravado agora · 1,25×
"input_tokens": 300 // não-cacheado · 1×
}
// total processado no turno = 98000 + 1200 + 300 = 99500 tokensWhat it is
The portion of the prompt that didn’t come from the cache, charged at the full price (1×). Added to the other two fields, it gives the actual size of the turn.
Why learn
Avoids the most common misreading: thinking the prompt was small by looking at just one field. The truth is in the total.
Key concepts
⏱️ TTL: 5 minutes and 1 hour
A cache entry doesn’t live forever. The TTL (lifetime) is 5 min by default, and it is renewed with every use — in other words, an active conversation keeps the cache warm on its own. There is also the option to 1 h (more expensive write, ~2×) for traffic with long pauses.
New here? "TTL"
TTL = time to live, how long the entry remains valid in the cache. If it goes unused past the TTL, the entry expires and the next request pays to write it again.
The cache clock
You respond within ~5 min
Each use resets the 5-minute timer. While the conversation is active, the cache stays warm and you pay the cheaper read price.
You pause for more than ~5 min
The TTL expires, the entry disappears from the cache, and the next message pays a cold write — writes the prefix again.
Traffic with pauses: 1 h TTL
If pauses often exceed 5 min, the 1-hour TTL keeps the cache alive longer—at the cost of a more expensive write (~2×).
What it is
The cache entry's time to live: 5 min by default (renewed with each use) or 1 h (write ~2×) for longer pauses.
Why learn
Explains why the active conversation is cheap and why coming back after a long time costs a new write.
Key concepts
💸 Relative costs
Four numbers explain any calculation in the course, all relative to the price of one uncached input token (1×): read ~0.1×, write 5 min ~1.25×, write 1 h ~2× e uncached 1×. In a long conversation, most of the input (system + history) is charged at ~10% of the price.
Illustration: read is the tiny bar — that’s where the savings are. Write costs a little more than full price, but you pay once; you’d pay full price every turn.
The cost table
| Operation | Relative cost | When |
|---|---|---|
| read | ≈ 0,1× | cache reread |
| uncached | 1× | reference (full price) |
| write 5 min | ≈ 1,25× | write, short TTL |
| write 1 h | ≈ 2× | write, long TTL |
What it is
The relative pricing table that governs all cache savings: cheap reads, writes with a premium, full price as the baseline.
Why learn
With these four numbers, you can estimate the cost of any course scenario in your head, without relying on an absolute price table.
Key concepts
⚖️ Break-even point
Caching is worthwhile when you read enough for the write to pay for itself. With TTL 5 min, 2 requests already pay for themselves (1.25× to write + 0.1× to read = 1.35×, versus 2× paying full price twice). With TTL 1 h (write ~2×), you need ~3.
New here? "break-even"
break-even = the break-even point: how many reads it takes for the cost with caching to match (and then beat) the cost without caching. Before this point, you only paid the write premium.
sem cache, 2 turnos: 1× + 1× = 2,00×
com cache, 2 turnos: 1,25× (write) + 0,1× (read) = 1,35×
────────
já no 2º turno o cache sai mais barato → economia
(com TTL 1 h, write ≈ 2×, o empate chega por volta do 3º turno)✓ Worth caching
- ✓Stable prefix that will be reread over multiple turns
- ✓Active conversation: system + history repeat
✗ Don’t cache
- ✗Prefix that changes the each request — only pays for write, never reads
- ✗Single call, no repetition—the write doesn’t pay for itself
What it is
The point at which the cache starts paying off: ~2 requests with a 5-minute TTL, ~3 with a 1-hour TTL.
Why learn
Teaches you NOT to cache what changes on every request (you’d only pay for the write) and to trust the cache when it’s read again.
Key concepts
Module summary
Next track
Track 2 — Technical: the cache within a growing conversation, skills and tools (append vs. break), and invalidation in depth, with copy-and-run examples.