5.5 Token Cost Modeling and Usage Tracking

Claude usage is billed per token — but not at a single flat rate. Input and output tokens are priced differently, with output tokens typically the more expensive side of the pair. That asymmetry matters when estimating cost for a feature: a task that generates a long response (a report, a detailed explanation) carries a different cost profile than a task with a long input but a short response (a classification over a big document), even if the total token count looks similar at a glance.

On top of the input/output split, there are separate, distinct rates for cache writes and cache reads — covered in depth in Lesson 5.6 — which add a third and fourth price point into the same overall structure. None of this is a single number you can quote in the abstract; it's a small pricing table with several rows, and cost modeling means applying the right row to the right kind of token.

Modeling expected cost for an application is basic arithmetic once you frame it correctly: estimate the token volume for each distinct request type — input tokens per call, expected output tokens per call, and any cached content — multiply each by the applicable per-token price, and sum across the expected traffic volume for that request type. Do this once per distinct kind of request your system makes (a classification call looks nothing like a long-form generation call, cost-wise), then add the totals together for a full picture.

This is the calculation behind any "what will this cost at scale" question: 100,000 classification calls a day at a few hundred input tokens and a handful of output tokens each costs very differently from 1,000 long-form report-generation calls a day with large inputs and large outputs. Getting the cost model right means not collapsing distinct request types into one average — the averages hide exactly the asymmetry (input vs. output pricing, high-volume-cheap vs. low-volume-expensive) that the model needs to capture.

• 1.Identify each distinct request type your system makes (classification, extraction, generation, synthesis, etc.).
• 2.Estimate expected input tokens and expected output tokens per call, for each request type separately.
• 3.Multiply input tokens by the input rate and output tokens by the output rate — don't average the two together.
• 4.Multiply by expected call volume for that request type, then sum across all request types for total expected cost.

Cost modeling estimates what a workload should cost before you run it. The `usage` field, present on every API response, reports the actual input, output, and cache token counts for that specific call — turning the estimate into a measured fact. Instrumenting this field, rather than only trusting the upfront model, does two distinct jobs: it tracks real, observed spend so a team can see whether the estimate was accurate, and it detects context bloat or unexpectedly large requests — a tool result that ballooned, a conversation history that grew further than expected — before that bloat becomes a recurring, silent cost problem.

Treat cost modeling as a hypothesis and the `usage` field as the ongoing experiment that checks it. A model that assumed 200 input tokens per call but is actually seeing 2,000 because of an unaccounted tool result is a real and common failure mode — one that only shows up if someone is watching the `usage` field, not just the upfront spreadsheet.

Cost modeling (5.5.2) estimates what a workload should cost before you run it, in aggregate, across expected traffic. The `usage` field (5.5.3) reports what a specific call actually cost, after it has run. There's a third tool that sits in between those two, checking a single request's size before you spend anything on it at all: the **`count_tokens` endpoint**. It accepts the exact same request body you'd send to a real messages call — the same system prompt, the same messages, the same tool definitions — but instead of running inference and generating a response, it returns only the token count that request would consume.

Because it never runs inference, `count_tokens` gives you a way to check a request's size against a budget — most commonly, against the context window — before spending anything on the real call. This is meaningfully different from the `usage` field: `usage` tells you what a call DID cost, after the fact, once it already ran; `count_tokens` tells you what a call WOULD cost, before you send it, with the option to adjust the request first if the number is too high.

This is the natural gate to put in front of a request that might be oversized: check whether a growing conversation history, a large tool result, or a big batch of retrieved documents would push a request over the context window before you actually send it — rather than sending it, paying for a failed or truncated call, and finding out the hard way. It's also useful during development to verify that assumptions about how many tokens a system prompt, a tool schema, or a document actually costs match reality, instead of eyeballing character or word counts (the classic Lesson 5.1 mistake resurfacing in a different form).

Because output tokens are typically the more expensive side of the pricing pair, and because generation is autoregressive (Lesson 5.1) — meaning a model that doesn't naturally stop keeps generating, and keeps costing, token after token — an unbounded or overly generous `max_tokens` setting is a direct cost risk. A malfunctioning prompt, an edge-case input, or a task that occasionally spirals into much longer output than typical can generate far more tokens (and far more cost) than the feature was ever meant to produce.

Setting `max_tokens` to a realistic ceiling for the feature's expected output length closes off that risk. This isn't purely a cost lever, either — a runaway generation also takes longer and adds latency, so a sensible cap protects both budget and responsiveness. The right ceiling comes from what the feature actually needs to produce, not from picking the largest number the API will accept "just in case."

Task Statement 5.5 questions typically hand you a pricing structure, a call volume, or a `usage`-field scenario, and ask you to compute, compare, or diagnose cost. The traps cluster around treating input and output tokens as equivalent, and around treating modeling as a one-time exercise rather than something continuously checked.

• •Assuming input and output tokens cost the same. ✗ An answer that prices a response by total token count at one flat rate. ✓ The answer applying the (typically higher) output rate separately from the input rate.
• •Treating cost modeling as "set once, never revisit." ✗ An answer that models cost upfront and never checks it against real traffic. ✓ The answer instrumenting the usage field to continuously verify the model and catch bloat.
• •Leaving max_tokens unbounded. ✗ An answer that omits or maximizes max_tokens "to be safe." ✓ The answer capping max_tokens to the feature's realistic expected output length.