Every Claude Messages API call sets max_tokens: the hard ceiling on how many tokens the model may generate in that response. First, a fact that surprises people: max_tokens is not what you're billed. You pay for tokens actually generated. A request with max_tokens=64000 that produces a 40-token answer bills 40 output tokens. So why budget it at all? Because output tokens are the most expensive thing you buy — $25 per million on Claude Opus 4.8, $50 on Claude Fable 5 — and max_tokens is the only hard bound on the worst case.
What a deliberate ceiling buys you
A capped blast radius. Prompts misfire: a malformed input, an ambiguous instruction, or a model deciding to be exhaustive can turn an expected 100-token answer into a 20,000-token essay. At Opus 4.8 rates that's the difference between $0.0025 and $0.50 of output — per request. Multiply by a production request volume and an unbounded endpoint becomes an incident. A ceiling converts "unbounded" into "annoying but capped."
A truncation signal you can act on. When generation hits the ceiling, the response ends with stop_reason: "max_tokens". That's not just an error state — it's telemetry. An endpoint that never hits its ceiling has headroom to cut; one that hits it often is either under-budgeted or over-generating.
No rate-limit cost. On the Claude API, output-tokens-per-minute limits count only tokens actually generated in real time — max_tokens itself doesn't factor in. So a generous ceiling costs you nothing in throughput; there is no quota reason to squeeze it below what the task can legitimately need.
Budget by task shape, not by model maximum
Current models allow up to 128k output tokens (64k on Claude Haiku 4.5). Almost no task needs that. A sensible starting taxonomy:
| Task shape | Typical real output | Reasonable ceiling |
|---|---|---|
| Classification / routing / yes-no | 1–20 tokens | Tens to low hundreds |
| Extraction into a JSON schema | Tens–hundreds | A few hundred |
| Summaries, drafted emails | Hundreds | ~1–2k |
| Long-form drafting, code generation | Thousands | Sized to the artifact |
| Agentic / reasoning-heavy work | Highly variable | Large — see below |
These are engineering heuristics, not published limits — the right numbers come from your own usage.output_tokens logs. The point is the spread: four orders of magnitude between a classifier and an agent. One shared constant cannot serve both.
max_tokens. A classifier ceiling of 30 tokens will strangle a model that wants to think first — official guidance for Opus 4.8 at xhigh/max effort is to start around 64k. Budget the ceiling for thinking plus answer, and use effort to control the thinking share (see thinking budgets).Ceiling and prompt work together
max_tokens truncates; it doesn't persuade. A hard-capped response that ends mid-sentence is a failed response you still paid for — and often a retry you'll pay for again. The cheap-output play is to make the model want to stop early: instruct "answer with the label only, no explanation," use structured outputs (output_config.format) so the response is exactly the JSON fields you need, and set lower effort on adaptive-thinking models for terser answers. Then set the ceiling comfortably above the honest maximum, as a circuit breaker rather than an editor.
One boundary interaction worth knowing on long-context work: on Claude 4.5 and later models, if input plus max_tokens exceeds the context window, the request is accepted and generation simply stops with stop_reason: "model_context_window_exceeded" — earlier models rejected such requests with a validation error. Generous ceilings are safe; they just get clipped by the window.
Everything above applies identically on Amazon Bedrock, Google Vertex AI, Microsoft Foundry, and Claude Platform on AWS — max_tokens is a core Messages API parameter everywhere Claude runs.
Where to go next
This article gives the principle; right-sizing max_tokens endpoint by endpoint turns it into an audit you can run this week. For the price asymmetry that makes output worth budgeting, see input vs. output economics.