What you will be able to do
- Build a cost model and forecast from usage data split by token category, model and service tier
- Judge a model route or cascade by cost per accepted result rather than cost per request
- Design a caching strategy for a fleet and diagnose why a cache is missing
- Decide which workloads belong on the Message Batches API and what they give up
- Enforce per-tenant budgets before calls run, not after the bill arrives
Key concept
Token mix — A fleet's spend is the sum of four token categories (uncached input, cache writes, cache reads and output), each priced per model and per service tier. Every cost lever moves tokens from one category, model or tier to a cheaper one, so you only understand a change once you know which category it moved.
1.Modelling and forecasting spend from usage data
At fleet scale, cost architecture starts with data you can trust. A single request's usage object shows what that call cost. A fleet needs the aggregate: which model, which workspace, which service tier and which token category the money went to. The Usage and Cost Admin API gives historical access to this data. Its /v1/organizations/usage_report/messages endpoint reports uncached input, cached input, cache creation and output tokens separately. You can filter and group them by API key, workspace, model, service tier, context window, data residency or speed, in 1-minute, 1-hour or 1-day buckets.
The cost report answers a different question. /v1/organizations/cost_report returns spend in USD, as decimal strings in cents. It can be grouped by workspace or description, and it only offers daily buckets. Use the usage report to find out why spend moved: token mix by model and tier. Use the cost report to reconcile against the bill. Neither one is a real-time control, because both describe traffic that has already run.
A forecast multiplies each category's token volume by that category's price for the model in use. The categories differ by more than an order of magnitude. Take a million requests a month on Claude Sonnet 5.5, each carrying a 20,000-token shared prefix. Sent uncached at $2 / MTok, the prefix alone costs $40,000. Read from cache at $0.10 / MTok, it costs $2,000, plus the cache writes. A forecast that ignores cache hit rate can be wrong by a factor of twenty on its largest line.
| Model | Input | Output | 5m cache write | 1h cache write | Cache hits and refreshes |
|---|---|---|---|---|---|
| Claude Fable 5.2 | $8 | $40 | $10 | $16 | $0.20 |
| Claude Opus 5.5 | $4 | $20 | $5 | $8 | $0.20 |
| Claude Sonnet 5.5 | $2 | $10 | $2.50 | $4 | $0.10 |
| Claude Haiku 5.5 (prompts up to 100,000 tokens) | $0.10 | $0.50 | $0.125 | $0.20 | $0.01 |
| Claude Haiku 5.5 (prompts over 100,000 tokens) | $0.50 | $2.50 | $0.625 | $1 | $0.05 |
The last two rows of the table matter for forecasting. Claude Haiku 5.5 prices change at 100,000 tokens: input goes from $0.10 to $0.50 / MTok. A retrieval feature whose prompts drift past that line as documents grow will see its unit cost jump fivefold with no code change. Group usage by context window so the drift shows up before the invoice does. For trace-level attribution of spend, see telemetry and instrumentation.
Checkpoint 1 of 9· Check yourself
A Claude Haiku 5.5 retrieval feature's unit cost has gone up roughly fivefold, and nobody changed the code. You suspect its prompts have grown past 100,000 tokens. Which data will confirm this?
Of these two reports, only the usage report can be grouped by context window. That grouping shows the token volume moving into the over-100,000-token band. The cost report only groups by workspace or description and only offers daily buckets. A single usage object shows one call, not the fleet-wide drift.
“Filter by API key, workspace, model, service tier, context window, data residency, or speed, and group results by these dimensions.”Source: platform.claude.com
2.Model routing and cascades across the Claude family
Routing sends each request to the cheapest model that does the task well. The price spread is wide: Claude Haiku 5.5 input costs one-twentieth of Claude Sonnet 5.5 and one-eightieth of Claude Fable 5.2. Haiku 5.5 is positioned for high-volume classification, extraction and routing. The recommended way to choose is to start with a faster, cheaper model such as Haiku 5.5, test the use case thoroughly, and move up only when performance falls short. Token counting also supports routing: you can count a request's input before sending it and send long prompts to whichever model prices them best.
Switching models is not the only lever. On several models an effort parameter trades intelligence against latency and cost within a single model, and tuning effort is often a better lever than switching. Before adding a second model to the route, check whether the current model at a lower effort setting already meets the quality bar on easy traffic.
A cascade is only as cheap as its cost per accepted result, not its cost per request. Every attempt is billed: failed attempts, retries and the final escalation call to the larger model. Suppose the small route costs 0.6 units against the large model's 1.0, and failures stick to particular inputs, so an input that fails once tends to fail its retries too. Each failing input then costs four small attempts plus one escalation: 3.4 units. With 35% of inputs failing, the average comes to about 1.58 units per accepted result, well above running the large model directly. Cascades pay off when the price gap is wide, like Haiku against Sonnet, when the cheap model's acceptance rate is high, and when failure is detected cheaply and escalated once instead of retried.
Checkpoint 2 of 9· Check yourself
Your team sends a large volume of support-ticket classification to Claude Sonnet 5.5 and wants to cut cost. Following the recommended way to choose a model, what should they do first?
Haiku 5.5 is positioned for high-volume classification, extraction and routing, and its input costs one-twentieth of Sonnet 5.5. The recommended approach is to start with the cheaper model, test it thoroughly and move up only when it falls short. A cascade that retries the same failing input on the same model adds billed attempts without changing the outcome.
“Claude Haiku 5.5For high-volume, latency-sensitive tasks such as classification, extraction, and routing”Source: platform.claude.com
3.Prompt caching economics and strategy
Prompt caching lets the API resume from a prefix it has already processed. The prefix covers tools, then system, then messages, up to and including the block marked with cache_control. Put stable content first (tool definitions, instructions, reference documents, examples) and variable content after the breakpoint. Automatic caching does this with one top-level field. It places the breakpoint on the last cacheable block and moves it forward as a conversation grows.
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
cache_control={"type": "ephemeral"},
system="You are a helpful assistant that remembers our conversation.",The pricing is a premium on writes and a discount on reads. A 5-minute write costs 25% more than base input. A 1-hour write costs 2x base input. Reads cost 10% of base input as the standard rate, with per-model exceptions: 0.05x on Claude Opus 5.5 and Sonnet 5.5, and 0.025x on Claude Fable 5.2. On Sonnet 5.5, one write plus one read costs 1.30x base input against 2x uncached, so a 5-minute entry pays for itself on its first reuse. A 1-hour entry costs about the same as no caching after one reuse and only comes out ahead on the second.
The TTL should match how far apart reuses are. The default lifetime is 5 minutes, and each read refreshes it at no extra cost, so busy traffic keeps an entry alive indefinitely. The clock starts when the request that writes or reads the entry starts. If a response takes 4 minutes to stream, the next request has about a minute to arrive. Use the 1-hour TTL when gaps between reuses regularly exceed 5 minutes, for example an agent waiting on a human or a slow tool. Prefixes also need a minimum length to be cached at all: 512 tokens on current models such as Opus 5.5, Sonnet 5.5 and Haiku 5.5, and more on some older ones.
Breakpoints cost nothing, and they are useful when sections change at different rates. One breakpoint can sit after the tools and system prompt, which change on deploy, and another after a per-session document. Up to four slots are available per request, and automatic caching uses one of them when you combine the two approaches.
Checkpoint 3 of 9· Fill the gap
This request enables automatic caching, so the API places the breakpoint on the last cacheable block. Which top-level field completes it?
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
? ={"type": "ephemeral"},
system="You are a helpful assistant that remembers our conversation.",Automatic caching needs only one cache_control field at the top level of the request. The system then puts the breakpoint on the last cacheable block and moves it forward as the conversation grows. The same cache_control marker, placed on individual content blocks instead, sets explicit breakpoints.
Sources5
4.Why caches miss, and how to diagnose it
A cache hit needs the prefix to match a recent write exactly. Marking a block writes a single entry: a hash of everything up to and including that block. Because the hash is cumulative, changing any block at or before the breakpoint produces a different hash. A timestamp at the top of the system prompt therefore turns every request into a fresh write. The fix is to move the volatile value after the breakpoint, for example into the user message. A longer TTL doesn't help, because no later request ever matches the old entry. Neither does padding, if the prefix is already above the minimum length.
Adding breakpoints doesn't rescue a prefix that changes on every call either. On a miss, the system walks backward up to 20 blocks looking for a position where an earlier request wrote an entry. It is searching for prior writes, not for content that happens to be stable. If the volatile line comes before every breakpoint, no earlier position was ever written with a matching hash.
Concurrency causes the other common miss. The entry is created once the response starts. Forty parallel requests fired the instant a shared 90,000-token document loads all arrive before any entry exists, so each pays its own write premium and none reads. To warm the cache, send one request first, wait for its response to begin, then fan out the rest so they read the entry it wrote. Random delays or a longer TTL don't change the order in which requests arrive relative to the write.
Cache diagnostics replaces guesswork with a named cause. Include a diagnostics object on each request, with previous_message_id: null on the first turn and the previous response's id after that. The API compares the two requests' fingerprints and reports the first divergence: model, system prompt, tools or message history. A null cache_miss_reason inside the object means the comparison was still running, so check the next turn. Fingerprints store only hashes and token-count estimates, never prompt text.
{
"id": "msg_01Xyz...",
"type": "message",
"role": "assistant",
"content": [{ "type": "text", "text": "..." }],
"usage": {
"input_tokens": 42,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 41850,
"output_tokens": 210
},
"diagnostics": {
"cache_miss_reason": {
"type": "system_changed",
"cache_missed_input_tokens": 41850
}
}
}Something before the breakpoint changes on every request, such as a timestamp, a request ID or reordered tools, so each hash is new. Or the gap between requests exceeds the TTL, measured from the start of the previous request. Diagnostics separates the two: a *_changed reason points to the first, and no divergence points to the second.
Checkpoint 4 of 9· Check yourself
Forty workers each send a request the moment a shared 90,000-token contract finishes loading. Each request marks the contract with cache_control. Usage shows forty cache writes and zero cache reads. Which change makes 39 of the requests read from the cache?
A cache entry is created only once a response starts, so requests that all arrive before the first response begins find no entry, and each one pays for its own write. Holding the rest back until the first response has started lets them read that entry. A longer TTL, random jitter or extra breakpoints don't change the fact that the requests arrive before the entry exists.
“Otherwise, it processes the full prompt and caches the prefix once the response starts.”Source: platform.claude.com
Checkpoint 5 of 9· Exam question
Yarrow Grocers runs a customer support agent in production that handles order and delivery questions. Each call resends the same 6,000-token system prompt, with a cache breakpoint on its last block. The prompt opens with the line Current time: <ISO timestamp>, followed by static policy and tone instructions that the team has not edited in weeks. Calls arrive every few seconds through the day, so entries are not expiring between requests. Usage shows cache_creation_input_tokens near 6,000 and cache_read_input_tokens of 0 on every request, and the token count shows the prompt is well above the model's minimum cacheable size. The team wants to stop paying to rewrite the prompt on each call without changing the agent's behaviour. What is the most direct fix?
Correct answer: C — Move the timestamp line from the system prompt into the user message, placing it after the breakpoint instead of ahead of the instructions.
- A. Entry lifetime is not what is failing. The prefix begins with a timestamp that differs on each call, so each request writes a fresh entry that later requests cannot match. A 1-hour TTL only keeps unread entries around longer and raises the write cost.
- B. The timestamp is the opening line, so any prefix that starts at the beginning of the system prompt contains it and differs from call to call. An extra breakpoint gives the lookback nothing identical to match, and reads stay at 0.
- C. Correct. A cache hit needs a byte-identical prefix, and a timestamp at the top of the prompt changes it on each call. Putting the timestamp in the user message, after the breakpoint, lets the static instructions be written once and read on later calls.
- D. The usage numbers show about 6,000 tokens being written to the cache, so the prefix already clears the minimum cacheable length. The prefix is not too short. It changes between calls because of the timestamp, so extra static text would not produce a read.
Checkpoint 6 of 9· Exam question
Zephyr Learning runs a production ingestion service for its course-authoring platform. It loads a 90,000-token document and immediately fires 40 parallel requests that share it as a cached prefix, with the cache breakpoint already placed after the document block. Usage logs show every one of the 40 requests performing a full cache write and zero reads, so the bill carries 40 write premiums. All 40 start timestamps fall within the same few milliseconds, and no request had begun returning output before the last one was sent. A staging trial that staggered the starts by a second or two still showed some requests writing. Finance does not want a costlier write tier, and the job's latency budget has room for one extra response to begin but not for running all 40 sequentially. What should the team change?
Correct answer: D — Send one request on its own first and wait for its response to begin, so the other 39 can then read the entry it wrote.
- A. A second breakpoint only adds another place to look up or write an entry. All 40 requests still start before any entry exists, so each one still pays its own write.
- B. TTL sets how long an entry lives, not when it can first be read. The 40 requests still start before any entry exists, and the 1-hour write costs more than the 5-minute write.
- C. An entry becomes readable when the first response begins, not after a replication delay. A random 1-2 second wait does not guarantee that point has passed, so some requests would still write instead of read.
- D. Correct. An entry can be read only once the first response begins, so requests fired together each write their own copy. Priming with one request and waiting turns the other 39 into discounted reads.
5.Batch versus realtime economics
The Message Batches API halves the price of every token in exchange for giving up immediacy. All batch usage is billed at 50% of standard prices: Claude Sonnet 5.5 drops to $1 input and $5 output per MTok. Most batches finish within an hour, but results become available only when every request has finished or after 24 hours, and requests still unprocessed at 24 hours expire. The work suited to batches is work nobody is waiting on: evaluations, moderation backlogs, bulk summaries, product descriptions.
| Model | Standard input / output | Batch input / output |
|---|---|---|
| Claude Fable 5.2 | $8 / $40 | $4 / $20 |
| Claude Opus 5.5 | $4 / $20 | $2 / $10 |
| Claude Sonnet 5.5 | $2 / $10 | $1 / $5 |
| Claude Haiku 5.5 (up to 100,000 tokens) | $0.10 / $0.50 | $0.05 / $0.25 |
Moving a workload to batch involves real constraints, not only a price change. Each batch holds at most 100,000 requests or 256 MB, whichever comes first. Results can be downloaded for 29 days. Most Messages features work inside a batch, including tools, extended thinking and multi-turn conversations. Some do not: stream: true, fast mode's speed parameter, server-side fallbacks and max_tokens: 0 all return validation errors. Cache pre-warming is excluded because an ephemeral entry written during batch processing would probably expire before the follow-up request ran. A batch design should therefore not assume that a cache written by one request will be warm for its neighbours.
Checkpoint 7 of 9· Check yourself
Which of these four workloads is the best candidate to move to the Message Batches API for the 50% discount?
Batch suits work nobody is waiting on. Results are guaranteed only once every request has finished or after 24 hours, so an overnight moderation backlog fits. A 30-minute deadline depends on the typical finish time, which is not guaranteed. Streamed chat and an agent waiting on approval both need immediate responses, and stream: true is rejected inside a batch.
“You can access batch results when all messages have completed or after 24 hours, whichever comes first.”Source: platform.claude.com
Sources7
6.Enforcing per-tenant budgets
A tenant budget only works if it is checked before tokens are spent. Usage and cost reports describe historical traffic, and the cost report is daily-only. A nightly or even hourly job that reads them is reacting after the money is gone. An agent loop that misbehaves can burn a month's allowance between two report runs. A system-prompt instruction asking the agent to stop at its fair share enforces nothing, because the model cannot see the bill.
Platform limits are useful backstops, but none of them is a per-tenant gate. Workspace spend limits cap monthly spending per workspace. That helps if each tenant has its own workspace, but batches can run slightly past the limit. Rate limits cap requests and tokens per minute. Lowering them throttles every tenant without tracking anyone's monthly total. Treat both as guards against throughput and runaway spend, covered in scale and throughput management, rather than as budget enforcement.
The direct control is a gateway that every call passes through, holding an atomic per-tenant counter. Before each call it:
- Estimates the input tokens, using the token counting endpoint or a local estimate.
- Adds the request's
max_tokensas the output ceiling and prices both at the target model's rates. - Atomically reserves that amount against the tenant's remaining budget, refusing the call if the reservation does not fit.
- After the response, reconciles the reservation to the actual
usageand releases the difference.
The atomic reservation stops parallel agent calls from all passing the check at once. Token counting rejects some inputs, such as server tools and URL-sourced documents. For those, the response's usage object supplies the true figure at reconciliation.
Checkpoint 8 of 9· Check yourself
A platform gives each tenant its own workspace with a monthly workspace spend limit. Tenants submit large Message Batches overnight. A finance lead says this spend limit is all the per-tenant budget enforcement the platform needs. What gap does that leave?
Workspace spend limits do cap monthly spending per workspace, but batches can overshoot them because of high throughput and concurrent processing. That makes the limit a backstop, not a budget gate. To refuse an overspend reliably, check the tenant's budget before each call and reserve the request's maximum cost atomically.
“Because of high throughput and concurrent processing, batches might go slightly over the spend limit configured in the Claude Console for your Workspace.”Source: platform.claude.com
Checkpoint 9 of 9· Exam question
Umber Grocers runs a SaaS platform for independent grocery chains. Each chain is a tenant with a contractual monthly token budget, and all tenants call Claude through one shared organization API key. A nightly job reads the usage dashboard, which trails real consumption, and emails any tenant that exceeded its budget. Last week one tenant's agent loop, running across several concurrent workers, consumed four times its monthly budget in a single day, most of it within a few minutes. Other tenants have legitimate bursty traffic when stores open, and that traffic must not be throttled. The agent has no visibility into the tenant's cumulative usage. Engineering wants overspend to be prevented rather than reported afterwards. What is the most direct control to prevent a repeat?
Correct answer: C — Check the tenant's budget in an atomic gateway counter before each call, reserving input estimate plus max_tokens; reconcile later.
- A. A faster report still detects overspend after it has happened, and a loop can burn through a budget in minutes. Detection that lags the spend is not prevention.
- B. A prompt instruction depends on the model estimating its own usage, which it cannot do reliably, and a looping agent may ignore it. It is not an enforced limit.
- C. Correct. A pre-call check against an atomic per-tenant counter blocks the call that would exceed the budget, and reserving the worst case handles concurrency. Reconciling with real usage keeps the counter accurate.
- D. An organization-wide rate limit throttles every tenant together, so it punishes well-behaved tenants and cannot express per-tenant monthly budgets.
Sources
(8)
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“Filter by API key, workspace, model, service tier, context window, data residency, or speed, and group results by these dimensions.”
↩︎ Modelling and forecasting spend from usage data“Time buckets: Only daily granularity (1d) is available.”
↩︎ Modelling and forecasting spend from usage data“All costs are in USD, reported as decimal strings in lowest units (cents).”
↩︎ Modelling and forecasting spend from usage data“provides programmatic and granular access to historical API usage and cost data for your organization”
↩︎ Enforcing per-tenant budgets“Measure uncached input, cached input, cache creation, and output tokens.”
↩︎ Key concept“provides programmatic and granular access to historical API usage and cost data for your organization”
↩︎ Exam trap 4 - 2.
“$0.50 / MTokfor prompts over 100,000 tokens”
↩︎ Modelling and forecasting spend from usage data - 3.
“starting with a faster, more cost-effective model such as Claude Haiku 5.5 can be the optimal approach”
↩︎ Model routing and cascades across the Claude family“Tuning effort is often a better lever than switching models.”
↩︎ Model routing and cascades across the Claude family“Tuning effort is often a better lever than switching models.”
↩︎ Exam trap 5 - 4.
“Make smart model routing decisions”
↩︎ Model routing and cascades across the Claude family“Proactively manage rate limits and costs”
↩︎ Enforcing per-tenant budgets - 5.
“Prompt caching covers the full prefix: tools, system, and messages (in that order), up to and including the block designated with cache_control.”
↩︎ Prompt caching economics and strategy“Cache writes: When new content is written to the cache (25 percent more than base input tokens for 5-minute TTL)”
↩︎ Prompt caching economics and strategy“You can specify a 1-hour TTL at 2x the base input token price:”
↩︎ Prompt caching economics and strategy“The lifetime is measured from the start of the request that writes or reads the cache entry, not from the end of its response.”
↩︎ Prompt caching economics and strategy“512 tokens for Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5”
↩︎ Prompt caching economics and strategy“When used together, the automatic cache breakpoint uses one of the 4 available breakpoint slots.”
↩︎ Prompt caching economics and strategy“It is looking for prior writes, not for stable content.”
↩︎ Why caches miss, and how to diagnose it“Otherwise, it processes the full prompt and caches the prefix once the response starts.”
↩︎ Why caches miss, and how to diagnose it“changing any block at or before the breakpoint produces a different hash on the next request.”
↩︎ Exam trap 1“Otherwise, it processes the full prompt and caches the prefix once the response starts.”
↩︎ Exam trap 2“Cache hits and refreshes on Claude Opus 5.5 and Claude Sonnet 5.5 are priced at 0.05x the base input price.”
↩︎ Exam trap 3“Claude Haiku 5.5For high-volume, latency-sensitive tasks such as classification, extraction, and routing”
↩︎ Checkpoint“Adding more cache_control breakpoints doesn’t increase your costs”
↩︎ Prediction - 6.
“A reordered tool, a timestamp interpolated into your system prompt, or an edit to an earlier message can silently invalidate the cache.”
↩︎ Why caches miss, and how to diagnose it“Fingerprints contain only hashes and token-count estimates (never raw prompt content)”
↩︎ Why caches miss, and how to diagnose it - 7.
“All usage is charged at 50 percent of the standard API prices.”
↩︎ Batch versus realtime economics“Batches expire if processing does not complete within 24 hours.”
↩︎ Batch versus realtime economics“an ephemeral cache entry written during batch processing would likely expire before the follow-up request runs.”
↩︎ Batch versus realtime economics“A Message Batch is limited to either 100,000 Message requests or 256 MB in size, whichever is reached first.”
↩︎ Batch versus realtime economics“batches might go slightly over the spend limit configured in the Claude Console for your Workspace.”
↩︎ Enforcing per-tenant budgets“You can access batch results when all messages have completed or after 24 hours, whichever comes first.”
↩︎ Checkpoint“Because of high throughput and concurrent processing, batches might go slightly over the spend limit configured in the Claude Console for your Workspace.”
↩︎ Checkpoint - 8.
“Spend limits: Cap monthly spending for a workspace.”
↩︎ Enforcing per-tenant budgets“Rate limits: Limit requests per minute, input tokens per minute, or output tokens per minute.”
↩︎ Prediction