max_tokens
APIDefinition
API parameter that sets the maximum number of tokens Claude will generate in a single response. If generation would exceed this limit it is truncated and `stop_reason` is set to `"max_tokens"`. This is a required parameter — omitting it returns a 400 error.
Example Usage
Set max_tokens to the largest output you genuinely need. If response.stop_reason == 'max_tokens', the response was cut short — retry with a higher value or chunk the task.
In Depth
What `max_tokens` Controls
max_tokens is a hard upper bound on the number of tokens Claude will generate in a single response. It does not affect how much input you can send — that is governed by the context window. It controls only the output side of the budget.
When Claude hits the limit mid-generation, it stops immediately and sets stop_reason to "max_tokens". The response is truncated at that token boundary — Claude does not detect the cut-off point and does not add a trailing marker. The result looks like a complete response until you inspect stop_reason.
The Truncation Trap
This is one of the most common production bugs in Claude integrations. A pipeline that works in testing with short outputs silently truncates in production when responses grow longer. Detection is a one-liner:
response = client.messages.create(
model="claude-opus-4-8",
max_tokens=2048,
messages=[{"role": "user", "content": prompt}]
)
if response.stop_reason == "max_tokens":
# Output was cut short — handle retry, chunking, or error
raise ValueError(f"Response truncated at {response.usage.output_tokens} tokens")Per-Model Output Maximums
Setting max_tokens above the model's own output ceiling returns a validation error. The caps are:
| Model | Max output tokens |
|---|---|
| Claude Fable 5 | 128 K |
| Claude Opus 4.8 | 128 K |
| Claude Opus 4.7 | 128 K |
| Claude Sonnet 4.6 | 64 K |
| Claude Haiku 4.5 | 64 K |
Sizing Strategy
Set max_tokens to the largest output you genuinely need, not the model maximum. Over-sizing wastes budget and inflates worst-case latency. A classification endpoint that returns one word needs max_tokens: 10, not max_tokens: 128000. For document generation or long code tasks, size conservatively above your p95 expected output length and monitor stop_reason distributions in production to catch systematic truncation early.
How It Compares
| Dimension | `max_tokens` | Context window |
|---|---|---|
| Controls | Output length only | Total input + output budget |
| Exceeded signal | stop_reason: max_tokens | stop_reason: model_context_window_exceeded |
| Set by | API caller (required param) | Model architecture (fixed) |
| Effect of hitting limit | Response truncated silently | Request rejected before generation |
| Mitigation | Increase value or chunk output | Compress/summarise input history |
Example
max_tokens is required on Messages API calls; if generation hits the cap, stop_reason is max_tokens.
message = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
messages=[{"role": "user", "content": "List three risks in this design."}],
)How It's Tested & Common Confusions
Exam questions typically present a scenario where an agentic loop or data pipeline produces incomplete outputs and ask you to diagnose why. The correct diagnosis is stop_reason == "max_tokens" combined with an undersized max_tokens setting. You may also be asked to identify the correct model-level output ceiling or to explain why setting max_tokens above the model maximum produces a 400 error.
Frequently Asked Questions
Does a higher `max_tokens` value make requests slower?
Not by itself — Claude streams tokens as they are generated, so latency to first token is unaffected. However, if the model actually generates more tokens because the ceiling is higher, time-to-complete (and cost) will increase proportionally. Setting a generous ceiling does not force the model to use it; it merely permits longer output.
Can I omit `max_tokens`?
`max_tokens` is a required parameter in the Messages API. Omitting it returns a 400 validation error. There is no default — you must always provide an explicit value. This is intentional: the API refuses to surprise you with unexpectedly large (and expensive) outputs.