Cost, Tokens, and the Cache That Pays for Itself

A running Claude application has a bill, and that bill is a design output as much as latency or correctness is. Every token in and every token out costs money. At scale the gap between a thoughtful design and a careless one is routinely an order of magnitude. And the amount is set by choices you control: how much you send, how much you ask back, and how much you re-send unchanged. Managing it is a loop of three moves: measure what you actually spend, model the bill before you commit to a design, and cut it with the platform’s levers, chiefly prompt caching for repeated prefixes. This chapter walks that loop, grounded in a live caching run that took 15,602 tokens from full price to a tenth.

Tracking spend: the usage object is your meter

Every response carries a usage object (chapter 1). It is your cost telemetry, so you never have to guess after the fact. The core fields:

• input_tokens — billed at the model’s input rate.
• output_tokens — billed at the output rate, several times higher than input. This asymmetry is the first cost lever: verbose outputs cost far more per token than long inputs. So constraining response length — a tight max_tokens, “answer in one sentence” — saves real money.
• cache_creation_input_tokens / cache_read_input_tokens — the caching accounting, below.

The discipline: log usage on every call. Summed over a day, those numbers are your actual spend by feature, user, and prompt: the data you need to find the expensive path and fix it. Cost management starts with measurement, and the meter is already in every response.

Modeling cost before you commit

Before shipping a feature, model its cost: cost ≈ input_tokens × input_rate + output_tokens × output_rate, per call, times your expected volume. You get input_tokens ahead of time from count_tokens (chapter 1), passed the whole request, system and tools included. You estimate output from the task. Multiply by requests-per-day and you have a bill before you’ve written the feature. This is how you catch a design that’s 10× too expensive while it’s still a spreadsheet: an image-heavy prompt (chapter 3), a giant system prompt resent every turn, an agent that loops more than you’d think. Model first; ship second.

Prompt caching: the big lever

Often you send the same large prefix on many requests: a long system prompt, a big tool set, a document an agent consults repeatedly, a block of few-shot examples. You’re re-sending and re-paying for those tokens every call. Prompt caching lets Claude store that prefix and reuse it cheaply. You mark a cache breakpoint with cache_control:

import anthropic
client = anthropic.Anthropic()
LONG_STABLE_PROMPT = "…a long, stable system prompt reused across many calls…"

resp = client.messages.create(model="claude-haiku-4-5", max_tokens=64,
    system=[{"type": "text", "text": LONG_STABLE_PROMPT, "cache_control": {"type": "ephemeral"}}],
    messages=[{"role": "user", "content": "Hi"}])

Everything from the start of the request up to a breakpoint is cached. On the first call the prefix is written to the cache; on later calls with the identical prefix it’s read from cache at a steep discount.

The numbers, from two back-to-back calls with a large cached system prompt:

call 1 (write):  input=9   cache_creation=15602   cache_read=0
call 2 (read):   input=9   cache_creation=0       cache_read=15602

The 15,602-token prefix was written to cache on call 1 and read from cache on call 2. Only the 9 non-cached tokens (the user turn) billed at the normal input rate each time. That matters because of the pricing: cache reads bill at roughly one-tenth of the input rate, and cache writes at about 1.25× (for the default 5-minute TTL). So the second call paid about a tenth for those 15,602 tokens. Across hundreds of calls sharing that prefix, that’s the difference between an affordable feature and an unaffordable one.

The threshold that silently skips it

This run caught a trap directly: caching is silently skipped below a per-model minimum prefix size. The same code with a short system prompt produced:

short system:   input=22   cache_creation=0   cache_read=0

No error, no warning — cache_creation is simply 0, and you’re billed full price. Each model has a minimum number of tokens a cacheable block must reach before caching engages. It’s larger than people expect — thousands of tokens on some models. If your prefix is below it, cache_control does nothing and you pay as if you’d never added it. So caching pays off for genuinely large stable prefixes, and adding a breakpoint to a small one is a no-op. Verify it: check that cache_creation_input_tokens is non-zero, or you’ve cached nothing.

TTL, checkpointing, and what’s cacheable

A few more facts that round out caching:

• TTL. The default cached entry lives ~5 minutes, refreshed on each hit. A 1-hour option (cache_control with a longer TTL, priced at a higher write multiplier) suits prefixes reused over a longer window. Choose based on how often the prefix is hit.
• Cache checkpointing / multiple breakpoints. You can place several breakpoints (a small number per request) to cache a growing prefix. For example, cache the system prompt and the tool definitions separately so a change to one doesn’t invalidate the other. The cache matches on an exact prefix, so anything before your breakpoint must be byte-identical to hit.
• What’s cacheable. System prompt, tool definitions, and message-history prefixes — the large, stable parts of a request. The moving part (the latest user turn) stays uncached, which is exactly what you saw: 9 live tokens on top of a 15,602-token cached base.
• Invalidation. Changing anything in the cached prefix — or a cache-affecting parameter like the tool set or thinking config — invalidates the cache and forces a rewrite. Keep the cached prefix stable; put the variable content after the breakpoint.

The other lever: batch

Caching is the lever for repeated prefixes; the Batches API (chapter 5) is the lever for latency-tolerant volume — 50% off every request, for work that can wait up to 24 hours. They compose: a nightly job over thousands of documents can use batch pricing and cache a shared instruction prefix. The two biggest cost reductions in the platform stack on top of each other.

Final thoughts

Cost management is measure, model, and cache. Measure with the usage object logged on every call — it’s your meter, and output tokens are the expensive ones. Model the bill from count_tokens and expected volume before you ship, to catch a 10×-too-expensive design on paper. And cache the large, stable prefixes: a 15,602-token prefix read from cache at a tenth of its price while only 9 live tokens billed full rate. But caching is silently skipped below a per-model minimum, so confirm cache_creation is non-zero rather than assuming. Stack caching with batch pricing for latency-tolerant volume, and you control the two biggest costs in the platform. That completes Domain 5.

Next: Arc 5 opens with prompt engineering — writing the instructions that make all of this behave.