What you will be able to do
- Read the usage fields of a response and work out which token category dominates spend
- Match the dominant driver to the right lever: shorter output, less thinking, batch processing, prompt caching or a token budget
- Place single, layered and rolling cache breakpoints so that requests read the cache rather than rewrite it
- Calculate the expected saving of a lever before shipping it, including when caching costs more than it saves
- Judge from the usage fields whether a cache checkpoint sits on the right block
Key concept
Dominant cost driver — The dominant cost driver is the token category with the biggest share of the bill once you multiply each token count by its own price. Fresh input, cache writes, cache reads, visible output and thinking each have a different price. A lever only pays off if it acts on that category.
1.Reading usage data to find the dominant cost driver
Cost work begins with the bill, not with a favourite optimization. Every Claude API call is charged per token, and tokens of different kinds carry different prices. On Claude Sonnet 5.5, input is $2 per million tokens and output is $10, so one output token costs as much as five input tokens. Opus 5.5 has the same 1:5 ratio at $4 and $20. A workload with fewer output tokens than input tokens can therefore still spend most of its money on output. The first step is always the same: multiply each token count by its price and see which line is largest.
The usage object in each response splits input into three fields, and together they make up the whole input. cache_read_input_tokens counts tokens served from cache. cache_creation_input_tokens counts tokens written to cache at a breakpoint. input_tokens counts only the uncached tokens after the last breakpoint. A dashboard that charts input_tokens alone will show a cached 200,000-token document as a 50-token request.
| Field | What it counts | Price on Sonnet 5.5 |
|---|---|---|
| input_tokens | Uncached tokens after the last cache breakpoint | $2 / MTok |
| cache_creation_input_tokens | Tokens written to cache at a breakpoint | $2.50 / MTok (5m writes), $4 / MTok (1h writes) |
| cache_read_input_tokens | Tokens read from cache | $0.10 / MTok |
| output_tokens | Generated output | $10 / MTok |
The pattern across these fields often diagnoses the problem without anything else. If cache_creation_input_tokens is large on every request and cache_read_input_tokens stays near zero, something in the prefix changes between calls, so each request writes a new entry and none ever reads one. If output tokens times the output price is larger than everything else, no input-side lever will move the bill much. The levers in the rest of this lesson each act on one of these lines, so the diagnosis decides which one is worth applying.
Checkpoint placement is something the usage fields let you verify. A cache checkpoint (a cache_control breakpoint) is where a write happens, and writes occur only at the block you mark. Put it on the last block that is identical across requests. Then the first request shows cache_creation_input_tokens close to the size of the whole prefix with cache_read_input_tokens at 0, and later requests show that prefix under cache_read_input_tokens. A checkpoint on a block that varies, such as a timestamp or the incoming message, never reaches that second state. Creation tokens keep appearing and reads stay at 0. In a growing conversation, healthy requests show reads for the old turns and creation for only the newest turn or two.
Checkpoint 1 of 10· Match them up
A cost dashboard shows four token counts from the usage object. Match each field to what it actually counts.
Tap a term, then the definition that fits it.
The three input fields add up to the total input, and input_tokens is only the uncached part after the last breakpoint. A dashboard that charts input_tokens alone can make a large cached prompt look tiny. Output has its own, higher price, so you have to multiply each field by its own price to find the dominant cost driver.
“Important: input_tokens does NOT represent all input tokens, only the portion after your last cache breakpoint.”Source: platform.claude.com
Sources1
2.When output dominates: bounding response length
When output dominates, the fix is to generate fewer output tokens. Take a product-description generator whose prompt asks for "thorough" copy when the page only displays about 150 words. Most of what it generates is never shown. Stating the target length and format in the prompt removes the cause. Setting max_tokens a little above that length adds a hard ceiling for the cases where the model runs long anyway. If responses fall from 2,100 to roughly 250 tokens, the cost per million calls drops from $21,900 to about $3,400, a cut of more than 80%.
Input-side levers barely move this bill. Trimming examples out of the 450-token prompt can save at most the 4% of spend that input represents, and it puts output quality at risk. Caching fails twice. It only discounts input, and on current models such as Opus 5.5 and Sonnet 5.5 a prefix shorter than 512 tokens cannot be cached at all.
Checkpoint 2 of 10· Check yourself
On Sonnet 5.5, a product-description generator sends a 450-token prompt and gets back about 2,100 tokens of copy, but the page shows only about 150 words. Which change goes after the dominant cost driver?
Output is about 96% of this call's cost because each output token costs five times as much as an input token. Only a lever that produces fewer output tokens moves the bill. Caching covers only the input prefix, and trimming input can save at most the roughly 4% that input accounts for.
“Prompt caching covers the full prefix: tools, system, and messages (in that order), up to and including the block designated with cache_control.”Source: platform.claude.com
Checkpoint 3 of 10· Exam question
A product-description generator averages 450 input tokens and 2,100 output tokens per call, and output tokens are priced at five times input tokens. The prompt asks for "thorough" copy, but the product page only displays about 150 words. Which change cuts the largest share of spend?
Correct answer: C — State the target length and format in the prompt, and set max_tokens slightly above that length to bound each response.
- A. The input side is a small share of spend, and a 450-token prompt is also below the minimum cacheable length for current models. Caching never reduces output tokens, which are the dominant cost.
- B. Trimming a few hundred input tokens saves little when about 2,100 output tokens at five times the price dominate. It would also risk quality while leaving the verbose output untouched.
- C. Output is roughly 90% of tokens and carries a five-times price, so it is the dominant driver. Capping and specifying length attacks it directly, taking responses from about 2,100 tokens to a few hundred.
- D. Temperature changes sampling randomness, not how long a response runs. Output length is governed by the instructions and
max_tokens, so the large output bill would remain.
3.Thinking tokens as hidden output
Extended thinking is output you pay for even though you may never see it. Thinking tokens are billed at the output rate. A response showing 40 visible tokens can carry thousands of thinking tokens behind it, so a call that looks cheap in the visible response may be the most expensive step in the pipeline.
Take an email router that assigns one of eight labels with budget_tokens set to 16,000. Per call it uses about 300 input tokens, 40 visible output tokens and 9,000 thinking tokens. At Sonnet 5.5 prices, thinking is roughly 99% of the cost. Tests show the labels are just as accurate without thinking, so the right lever is to turn thinking off, or to drop the budget toward the minimum of 1,024 tokens. For simple tasks, start near that minimum and increase only if quality drops.
Two other levers fail here. Caching cannot absorb thinking tokens: it discounts repeated input prefixes, and thinking is billed as output. Lowering max_tokens to 20 also does not work, because thinking tokens count toward max_tokens. With thinking on, budget_tokens must be at least 1,024 and lower than max_tokens, so the API rejects that combination. The fix is to change the thinking configuration itself.
Checkpoint 4 of 10· Check yourself
Your email router on Sonnet 5.5 returns one of eight labels. Each call uses about 300 input tokens, 40 visible output tokens and 9,000 thinking tokens, with budget_tokens at 16,000. Tests show the labels are just as accurate without thinking. Which change cuts this bill?
Thinking tokens are billed at the output rate and make up about 99% of this call's cost, so the fix is to change the thinking configuration. Caching covers only the input prefix, not generated thinking. A max_tokens of 50 below a 16,000 budget is rejected because budget_tokens must be lower than max_tokens. Trimming the prompt reaches only about 1% of spend.
“Prompt caching covers the full prefix: tools, system, and messages (in that order), up to and including the block designated with cache_control.”Source: platform.claude.com
Checkpoint 5 of 10· Exam question
A routing step labels support emails into one of eight categories using extended thinking with a budget_tokens of 16,000. Per call, usage shows about 300 input tokens, 40 visible output tokens and 9,000 thinking tokens. Tests show the labels are equally accurate without thinking. Where is the cost, and which lever fits?
Correct answer: A — Thinking tokens, billed as output, dominate; turn thinking off or set a small budget since the labels need no deep reasoning.
- A. Thinking tokens are billed as output tokens, and 9,000 of them dwarf the 340 other tokens. Since accuracy is unchanged without thinking, removing or capping the budget cuts nearly the entire per-call cost.
- B. Input is only 300 tokens, far less than the thinking tokens, and it is below common minimum cacheable lengths. The reasoning tokens remain uncached output.
- C. The visible response is only 40 tokens. Thinking spend is a separate and much larger portion, so trimming the label would barely change the bill.
- D. Thinking tokens are billed at the output rate, not the input rate. Raising the budget would increase spend rather than shift it into cache reads.
4.Batch processing for work nobody is waiting on
The Message Batches API halves the price of any request that can wait. Every batched token, input and output, is billed at 50% of the standard rate, so Sonnet 5.5 drops to $1 input and $5 output per million tokens. You give up immediacy. Requests are processed asynchronously, most batches finish within an hour, results become available once all requests complete or after 24 hours, and requests still unprocessed at 24 hours expire.
The deciding question is whether a person is waiting for the response, not how large the workload is. A nightly job that summarizes 80,000 closed tickets for people to read the next morning is a good fit for batch: half price, and the morning deadline easily absorbs a 24-hour window. A live chat with a 3-second latency target is not, no matter how much of the bill it represents. Batch output is returned as a single results file, stream: true is rejected, and nothing guarantees the response arrives within seconds.
Batch and caching discounts stack, with one caveat. Batched requests can run concurrently and in any order, so cache hits within a batch are best-effort. To get more hits, first send a single request that writes the shared prefix with a 1-hour TTL. Once it completes, submit the rest of the batch. A batch commonly takes longer than 5 minutes, which is why the 1-hour cache is the right choice here. Cache pre-warming with max_tokens: 0 is not allowed inside a batch.
Checkpoint 6 of 10· Put it in order
Tonight's batch of 80,000 ticket summaries shares one long system prompt. You want more of these requests to read that prompt from cache. Put the steps in order.
- 1.Submit the remaining requests as a batch so they can read the cached prefix
- 2.Identify the requests in the job that share the same long prefix
- 3.Submit a single request that writes the shared prefix to cache with a 1-hour TTL
- 4.Wait until that single request has completed
Requests in a batch can run at the same time and in any order, so cache hits within a batch are not guaranteed. Writing the prefix first with one request means the rest of the batch can find it in cache. The 1-hour TTL keeps the entry alive, because a batch often takes longer than 5 minutes.
“As soon as this is complete, submit the rest of the requests.”Source: platform.claude.com
Checkpoint 7 of 10· Exam question
A cost report shows two workloads on one model: live customer chat with a 3-second latency target (40% of spend), and a nightly job that summarizes 80,000 closed tickets which people read the next morning (35% of spend). Which optimization applies without hurting the product?
Correct answer: B — Move the nightly summarization to the Message Batches API, which bills at a 50% discount and returns results asynchronously within 24 hours.
- A. Batch results are asynchronous, so live chat with a 3-second target would break. Only the delay-tolerant job can use the discount.
- B. The nightly job tolerates delay, which is exactly the Batch API's trade: half price for asynchronous processing. The chat workload keeps its synchronous path.
- C. A latency target is not evidence that chat output can be trimmed, and this ignores the nightly job, a large and delay-tolerant share that a 50% discount fits perfectly.
- D. Batch processing is discounted regardless of the task type. Dropping to a smaller model risks summary quality and forgoes the simpler, larger saving available from batching.
5.Pricing a cache: writes, reads and TTL
Caching does not always save money. A cache write costs more than ordinary input: 1.25× the base input price for a 5-minute TTL and 2× for a 1-hour TTL. Reads cost a small fraction of base input. That fraction is 0.1× on most models, 0.05× on Opus 5.5 and Sonnet 5.5, and 0.025× on Fable 5.2. Caching saves money only when enough reads follow each write to repay the write premium.
The choice of TTL depends on the gap between requests. Each read refreshes the cache at no extra cost. The lifetime is measured from the start of the request, though, so if a response takes 4 minutes to stream, the next request has only about 1 minute left to hit a 5-minute entry. Requests that arrive in bursts suit the 5-minute TTL. Gaps longer than 5 minutes, or long generations, call for the 1-hour TTL, but at 2× per write it only pays off when each write is followed by more reads.
{ "cache_control": { "type": "ephemeral", "ttl": "1h" } }To estimate a saving, price the same token counts both ways. On Opus 5.5, 40,000 cache-read tokens cost 40,000 × $4 × 0.05 / 1,000,000 = $0.008. Billed as ordinary input they would cost $0.16. In a session that also produces 15,000 output tokens at $0.30, though, output remains the biggest line after the cache is working. That tells you which lever to look at next.
Checkpoint 8 of 10· Fill the gap
A research assistant re-sends the same 30,000-token prefix on every turn. Each response takes about 4 minutes to stream, and the user's next question usually arrives 2–3 minutes after the response finishes. Which value completes the cache_control setting so that the follow-up request still reads the cached prefix?
{ "cache_control": { "type": "ephemeral", "ttl": " ? " } }The cache lifetime starts counting when the request begins, so a 4-minute response leaves only about 1 minute of a 5-minute entry, and a follow-up 2–3 minutes later would miss it. The two TTLs the API offers are the default 5 minutes and 1 hour, so this gap needs "1h", even though each write then costs 2× the base input price.
Source: platform.claude.com6.Placing breakpoints: single, layered and rolling
A cache entry covers the full prefix up to the breakpoint, in a fixed order: tools, then system, then messages. The cache key is a hash of that prefix, so changing one byte anywhere before the breakpoint means a miss. Placing breakpoints well comes down to putting each one on content that does not change between requests.
For most applications, a single breakpoint is enough. Put it on the last block that stays identical across requests. If the breakpoint sits on something that changes every call, such as a timestamp or the incoming user message, every request writes a new entry at the 1.25× price and none of them ever reads one. That produces exactly the usage pattern of high creation tokens and zero reads.
Layered breakpoints let content that changes at different rates be cached separately. A request can carry up to four. The standard layout puts one on the last tool definition, one on the static system instructions, one on the RAG documents, and one on the latest conversation turn. A change at any breakpoint invalidates that segment and everything after it, while earlier segments stay valid. Updating the daily RAG documents therefore costs a rewrite of the documents and the conversation, but the tools and instructions are still read from cache. Breakpoints themselves are free; only the tokens written and read are billed.
Rolling breakpoints handle a growing conversation. With automatic caching, a single top-level cache_control moves the breakpoint to the last cacheable block on each request. Each turn reads everything earlier from cache and writes only the newest turns. Lookback is limited to 20 blocks, so if a conversation pushes the breakpoint 20 or more blocks past the last cache write, add an explicit breakpoint to keep the earlier entry reachable. Automatic and explicit breakpoints can be combined, and the automatic one uses one of the four slots.
{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"cache_control": { "type": "ephemeral" },
"system": [
{
"type": "text",
"text": "You are a helpful assistant.",
"cache_control": { "type": "ephemeral" }
}
],
"messages": [{ "role": "user", "content": "What are the key terms?" }]
}Some invalidations come from configuration rather than content. Changing thinking parameters invalidates cached message prefixes, and can also invalidate cached system prompts and tools. So can changing the effort setting, adding or removing images, or changing tool-use settings. A pipeline that switches thinking budgets per request pays for a new cache write every time it switches.
The date sits in front of the instructions and the catalogue breakpoints, so it changes those prefixes every day, and once a day the instructions and the catalogue must be written again. Only the tools segment, which comes before the system prompt, stays valid. Move the date after the last stable breakpoint.
Checkpoint 9 of 10· Check yourself
A support bot on Sonnet 5.5 sends a 12,000-token block of tools and system prompt that never changes, followed by the customer's new message. Its only breakpoint is on that new message. Usage logs show about 12,000 cache_creation_input_tokens on every request and cache_read_input_tokens stuck at 0. Which change makes the cache start paying off?
The cache key is a hash of the whole prefix up to the breakpoint. A breakpoint on the incoming message changes that prefix on every call, so each request writes a new entry and none ever reads one. A longer TTL or a cheaper write does not fix the mismatch. If the breakpoint is on the last stable block, every request reads the same entry.
“Place it on the last block that stays identical across requests, and every subsequent request reads that same entry.”Source: platform.claude.com
Sources1
7.Token budgets that bound spend
Token budgets limit how much a request or an agentic loop can generate, and they differ in how strictly they hold. max_tokens is the hard ceiling on one response, thinking included. budget_tokens sets a target for thinking, not a strict cap. A task budget is an advisory total for a whole agentic loop. Claude sees a running countdown of the remaining tokens and uses it to pace itself and wrap up gracefully, rather than being cut off in the middle of an action. These settings belong to generation parameters. This section is about which of them to use when cost is the goal.
| Budget | Scope | Strength | Use when the cost driver is |
|---|---|---|---|
| max_tokens | One response, thinking plus text | Hard limit | Visible output running past what the product uses |
| budget_tokens | Thinking within a turn | Target, not a strict cap | Thinking tokens on tasks that need little reasoning |
| task_budget (output_config, beta) | A full agentic loop: thinking, tool calls, tool results and output | Advisory countdown that Claude paces against | Long agent runs with no predictable per-task ceiling |
Task budgets and effort control different things. Effort sets how thoroughly Claude reasons at each step, while a task budget caps the total work across the loop. Agent spend that grows with the number of tool calls is a job for a task budget. Spend that comes from deep reasoning on every step is a job for effort or the thinking budget.
Checkpoint 10 of 10· Match them up
Each setting below limits spend in a different way. Match each one to what it bounds and how strictly it holds.
Tap a term, then the definition that fits it.
max_tokens is the only hard ceiling, and it applies to one response. budget_tokens is a target for thinking. A task budget is an advisory total for a full agentic loop, so Claude can finish gracefully instead of being cut off. Effort sets how deeply Claude reasons at each step, while a task budget caps the total work across the loop.
“effort controls how thoroughly Claude reasons about each step, whereas task budgets cap the total work Claude can do across an agentic loop”Source: platform.claude.com
Sources
(7)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens”
↩︎ Reading usage data to find the dominant cost driver“Important: input_tokens does NOT represent all input tokens, only the portion after your last cache breakpoint.”
↩︎ Reading usage data to find the dominant cost driver“Cache writes occur only at the block you mark.”
↩︎ Reading usage data to find the dominant cost driver“512 tokens for Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5”
↩︎ When output dominates: bounding response length“because asynchronous batch requests can be processed concurrently and in any order, cache hits are provided on a best-effort basis.”
↩︎ Batch processing for work nobody is waiting on“Cache hits and refreshes on Claude Opus 5.5 and Claude Sonnet 5.5 are priced at 0.05x the base input price.”
↩︎ Pricing a cache: writes, reads and TTL“The lifetime is measured from the start of the request that writes or reads the cache entry, not from the end of its response.”
↩︎ Pricing a cache: writes, reads and TTL“Changes at any breakpoint invalidate that segment and everything after it, whereas earlier cached segments remain valid.”
↩︎ Placing breakpoints: single, layered and rolling“A growing conversation pushes your breakpoint 20 or more blocks past the last cache write, putting the prior entry outside the lookback window”
↩︎ Placing breakpoints: single, layered and rolling“Changing thinking parameters (switching modes, or changing the budget in extended mode) invalidates cached message prefixes”
↩︎ Placing breakpoints: single, layered and rolling“Important: input_tokens does NOT represent all input tokens, only the portion after your last cache breakpoint.”
↩︎ Exam trap 1“Place it on the last block that stays identical across requests, and every subsequent request reads that same entry.”
↩︎ Exam trap 4“Prompt caching covers the full prefix: tools, system, and messages (in that order), up to and including the block designated with cache_control.”
↩︎ Checkpoint“Prompt caching covers the full prefix: tools, system, and messages (in that order), up to and including the block designated with cache_control.”
↩︎ Checkpoint“As soon as this is complete, submit the rest of the requests.”
↩︎ Checkpoint“5-minute cache writes cost 25 percent more than base input tokens, 1-hour cache writes cost 2x base input tokens”
↩︎ Prediction“Place it on the last block that stays identical across requests, and every subsequent request reads that same entry.”
↩︎ Checkpoint - 2.https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/reduce-latencyOfficial docs
“Use the max_tokens parameter to set a hard limit on the maximum length of the generated response.”
↩︎ When output dominates: bounding response length“Ask Claude directly to be concise.”
↩︎ When output dominates: bounding response length - 3.
“Thinking tokens are billed as output tokens even when the thinking text is not returned to you”
↩︎ Thinking tokens as hidden output“Thinking tokens are billed as output tokens even when the thinking text is not returned to you”
↩︎ Exam trap 2 - 4.
“Thinking tokens count toward the max_tokens limit for the turn, so the budget must leave room for the final response.”
↩︎ Thinking tokens as hidden output“For simple tasks, start near the 1,024-token minimum and increase incrementally to find the optimal range for your use case.”
↩︎ Thinking tokens as hidden output“The budget is a target rather than a strict cap.”
↩︎ Token budgets that bound spend - 5.
“All usage is charged at 50 percent of the standard API prices.”
↩︎ Batch processing for work nobody is waiting on“Batches expire if processing does not complete within 24 hours.”
↩︎ Batch processing for work nobody is waiting on“You can access batch results when all messages have completed or after 24 hours, whichever comes first.”
↩︎ Exam trap 3 - 6.
“Batch API and prompt caching discounts can be combined.”
↩︎ Batch processing for work nobody is waiting on“Cache read tokens | 40,000 × $4 × 0.05 / 1,000,000 | $0.008 USD”
↩︎ Pricing a cache: writes, reads and TTL“Monitor usage patterns: Track token consumption to identify optimization opportunities.”
↩︎ Key concept“Claude Sonnet 5.5The best combination of speed and intelligence | $2 / MTok | $10 / MTok”
↩︎ Prediction - 7.
“Task budgets let you tell Claude how many tokens it has for a full agentic loop, including thinking, tool calls, tool results, and output.”
↩︎ Token budgets that bound spend“effort controls how thoroughly Claude reasons about each step, whereas task budgets cap the total work Claude can do across an agentic loop.”
↩︎ Token budgets that bound spend“effort controls how thoroughly Claude reasons about each step, whereas task budgets cap the total work Claude can do across an agentic loop”
↩︎ Checkpoint