Task statement 5.4 · Model selection and optimization

5.4 · Cost and Token Management

In Shelfwise, the course example, the $0.01 ceiling is a cost model: about three requests an answer, each carrying ≈7,000 input tokens of which ≈6,000 are a cached prefix, at Haiku-family prices. The team must budget those tokens, read what each request used, and price it in a form a week of usage logs can check.

Why it's tested

Two reasonable shortcuts give the wrong cost. One prices a request from its input size alone, but output costs five times as much per token, and thinking is billed as output. The other caches every prompt on the theory that caching always saves money, but a write costs more than plain input, so a prefix that is never read before it expires costs more cached than uncached.

KnowledgeBudgeting tokens per request

A token budget has an output side and an input side. max_tokens caps what one response writes, thinking included (thinking tokens count toward it and are billed as output, 2.3). A response that reaches the cap stops with stop_reason: "max_tokens", so the cap bounds cost but can cut an answer off. Effort is the softer lever where a model supports it, because lower effort uses fewer output tokens (5.1). Input is the system prompt, the tool definitions plus a tool-use system prompt the API adds, the history and any retrieved context. The API keeps no state between requests, so the history is resent and grows every turn. Shelfwise budgets ≈7,000 input tokens a request, starts a new session for each staff chat (2.5), and turns thinking off, because a Haiku-family model has no effort parameter to lower.

KnowledgeToken usage tracking

Every response carries a usage object for billing. input_tokens counts only the input after the last cache breakpoint, and with cache_read_input_tokens and cache_creation_input_tokens it makes up the request's total input. The cache_creation object splits writes into ephemeral_5m_input_tokens and ephemeral_1h_input_tokens, and output_tokens_details.thinking_tokens says how much of output_tokens was thinking. Token usage tracking means logging these fields for every request, tagged with the feature that sent it. The tag is needed because the Usage and Cost Admin API (2.2) reports by API key, workspace, model and service tier, so it sees a feature only if that feature has its own key. A workspace is the cost boundary above a key, with its own monthly spend limit, alerts and per-minute rate limits.

KnowledgeA cost model in multipliers

A cost model prices each usage field as a multiple of the model's base input price. On current models output costs five times the input price. A five-minute cache write costs 1.25 times it and a one-hour write twice, while a read costs a tenth on most models and less on the newest Opus-, Fable- and Mythos-family models. The Message Batches API halves input and output, stacking with the caching multipliers (2.3). The pricing page's "Cost optimization strategies" add the right model (5.3) and monitoring usage. The grid maps each line of the cost model to the field that counts it.

Uncached input× 1

input_tokens: everything after the last breakpoint.

Cache writes× 1.25 or × 2

ephemeral_5m_input_tokens and ephemeral_1h_input_tokens, by lifetime.

Cache reads× 0.1

cache_read_input_tokens: the prefix reused from the cache.

Output× 5

output_tokens, thinking included.

KnowledgeWhen caching pays off

Prompt caching saves money only when reads repay the write premium. Against sending the prefix uncached, a five-minute write pays for itself after one read (1.25 + 0.1 is less than 2) and a one-hour write after two (2 + 0.2 is less than 3). Because each read refreshes the lifetime (2.3), the five-minute lifetime suits requests less than five minutes apart and the one-hour lifetime suits gaps of up to an hour. With longer gaps every request writes and none reads. A prefix below the model's minimum cacheable length, 4,096 tokens on the current Haiku-family model, is processed uncached with no error, and both cache fields read 0. The hit rate is cache-read tokens as a share of all input tokens, as Claude Code's hit_ratio reports it. Cache check-pointing, which the docs call placing cache_control breakpoints (2.3), decides which tokens the reads cover.

SkillPricing a Shelfwise answer from its usage

Shelfwise's first cost log priced each request as input_tokens at the input price plus output_tokens at five times it. A week of logs averaged about $0.005 an answer, yet the logged total came to only about three-quarters of the Cost API's daily figure for Shelfwise's workspace. Costs below are in units of one token at the base input price:

# one warm request, from its AssistantMessage usage
input_tokens 1,000 · cache_read_input_tokens 6,000 · cache_creation_input_tokens 0
# v1 log, per answer: 3 requests, ≈400 output tokens
3 × 1,000 + 5 × 400 = 5,000 units → ≈$0.005, under-counted
# cause: input_tokens stops at the breakpoint, so 18,000 cache reads went unpriced
3 × (1,000 + 0.1 × 6,000) + 5 × 400 = 6,800 units → ≈$0.007, agrees with the Cost API

With caching on, input_tokens stops at the breakpoint, so every answer's cache reads went unpriced. The fixed log prices all four lines and tags each request stock_answer or eval, so the eval runner's 150 questions count apart from staff answers. It also records the hit rate, about 0.86 at the Saturday peak, the most a 6,000-of-7,000 prefix allows. The first answer after more than five quiet minutes writes the prefix instead: (1.25 × 6,000 + 1,000) + 2 × 1,600 + 2,000 = 13,700 units, about $0.014, which is why 2.1 checks the week's mean cost per answer.

Interactive · what one Shelfwise answer costs, line by line

Three bars for one Shelfwise answer of three requests, in units of one token at the base input price, against a 0.01 dollar ceiling at about 10,000 units. No caching: 21,000 units of uncached input plus 2,000 of output, 23,000 in all, over the ceiling. Cached, v1 log: 3,000 of uncached input plus 2,000 of output, 5,000, with 1,800 units of cache reads left unpriced. Cached, all fields priced: 1,800 of cache reads, 3,000 of uncached input and 2,000 of output, 6,800, under the ceiling. $0.01 ceiling ≈ 10,000 units 1 · No caching 23,000 ≈ $0.023 INPUT 21,000 2 · Cached, v1 log 5,000 LOGGED ≈ $0.005 1,800 OF READS UNPRICED 3 · All fields priced 6,800 ≈ $0.007 cache reads × 0.1 uncached input × 1 output × 5 units: tokens at the base input price, per answer of three requests

Choose a way of pricing the same answer and compare it with the $0.01 ceiling.

No caching: three requests of ≈7,000 full-price input tokens plus ≈400 output tokens at five times the price come to 23,000 units, about $0.023, more than twice the ceiling.

Cached, priced by the first log: input_tokens holds only the ≈1,000 tokens after the breakpoint, so the 18,000 cache-read tokens (1,800 units) are missing and the answer looks like $0.005.

Cached, every field priced: 1,800 units of cache reads, 3,000 of uncached input and 2,000 of output make 6,800 units, about $0.007, under the $0.01 ceiling.

One answer priced three ways. The dashed ember box in bar 2 is the cache-read cost the v1 log missed; the dashed line is the $0.01 ceiling at Haiku-family prices, checked 2026-10-04.
Ask one question: will this prefix, at or above the model's minimum length, be read again before its lifetime ends? Yes, within five minutes → mark it with cache_control at the default lifetime. Yes, but with gaps of five minutes to an hour → the one-hour TTL. No → leave it uncached, because nothing repays the write premium.
Takeaway
  • With caching on, input_tokens is only the input after the last breakpoint, so total input adds cache reads and writes.
  • Turn usage into cost field by field, each with its own multiple of the input price: reads, writes, uncached input and output.
  • Bound output with max_tokens and effort, and bound input per conversation, because resent history grows every turn.

check yourself

0 / 3 answered

A legal-research tool on a Haiku-family model sends a 3,000-token system prompt of citation rules marked with cache_control, then each lawyer's question. Requests arrive every few seconds and none returns an error, yet every response shows cache_creation_input_tokens: 0 and cache_read_input_tokens: 0, with input_tokens near 3,400.What is the most likely root cause?

Select one.

An HR policy assistant on a Sonnet-family model starts every request with the same 20,000-token handbook, marked with cache_control at the default lifetime. Staff ask about one question every 15 to 20 minutes across an eight-hour day and expect each answer within seconds. The usage logs show a cache write on every request and no reads.Which change most lowers the handbook's daily input cost while keeping answers immediate?

Select one.

Before launch, a team priced its tutoring chatbot at $0.004 a conversation: count_tokens on a typical first message alone, times the input rate. The chatbot also has two tools. The first week's bill averages $0.019. Logs show input per request growing every turn, five times larger by turn eight, and thinking_tokens making up most of output_tokens. Nothing is cached.Which TWO causes best explain the gap between the estimate and the bill?

Select two.

sources

  1. Claude Platform Docs, "Pricing": caching multipliers relative to the base input price (1.25x five-minute write, 2x one-hour write, 0.1x read, with lower read multipliers on some models); caching pays off after one read or two; output at five times input on current models; the Batch API's 50% discount on input and output, stacking with caching; the tool-use system prompt; "Cost optimization strategies". Checked 2026-10-04.
  2. Claude Platform Docs, "Prompt caching": the usage fields and their sum; input_tokens after the last breakpoint; the cache_creation breakdown by TTL; when to use the one-hour cache; refresh on each use; minimum cacheable length per model, no error below it and both fields 0. Checked 2026-10-04.
  3. Claude Code Docs, "Customize your status line": hit_ratio, cache-read tokens as a fraction of all input tokens (reads, writes and uncached input). And "Agent SDK reference - Python": per-message token usage on AssistantMessage.usage. Checked 2026-10-04.
  4. Claude Platform Docs, "Messages" API reference: the usage object, output_tokens_details.thinking_tokens, and service_tier. And "Extended thinking": thinking tokens count toward max_tokens and are billed as output. Checked 2026-10-04.
  5. Claude Platform Docs, "Effort": effort affects all output tokens, and lower effort means fewer and terser tool calls. Checked 2026-10-04.
  6. Claude Platform Docs, "Usage and Cost API": filtering and grouping by API key, workspace, model and service tier. And "Workspaces": workspace spend limits with alerts and rate limits, set no higher than the organisation's. Checked 2026-10-04.
  7. Claude Platform Docs, "Batch processing": all usage charged at 50% of standard prices. Checked 2026-10-04.
  8. Shelfwise's first cost log, the ≈400 output tokens an answer, the stock_answer and eval tags, the 0.86 hit rate and the cold answer are this course's example details; the ≈$0.005, ≈$0.007, ≈$0.014 and ≈$0.023 figures use Haiku-family prices checked 2026-10-04 and are recomputed before each publish.