Glossary/M/max tokens
Model limits Also called: max_tokens, max_completion_tokens, max_output_tokens, output token limit, output cap

What is max tokens?

max_tokens is a request parameter that caps how many tokens the model may generate in one call. It limits output only: your prompt is not counted against it, and the model can stop well before the cap. When generation hits the cap, the API cuts the reply off and reports it with stop_reason max_tokens on Anthropic or finish_reason length on OpenAI. Reasoning or thinking tokens count against the same cap, and OpenAI's newer APIs call it max_completion_tokens or max_output_tokens.

Written by Derek Wonk · last updated October 2026

Ask ChatGPT Ask Claude View as Markdown

What does max_tokens limit, and what does it leave alone?

max_tokens is a ceiling on generated tokens for a single request. Anthropic's Messages API describes it as "the maximum number of tokens to generate before stopping" and notes that the model may stop before reaching it. The model does not aim for the number; it writes until it finishes its turn, hits a stop sequence, or runs into the cap, whichever comes first.

It does not limit your input. The system prompt, the message history, tool definitions and documents are all input tokens, and they are bounded by the context window, not by max_tokens. Each model also has its own ceiling on the parameter: on Anthropic's 1M-token models a single request can generate up to 128k output tokens.

"Tokens" covers two different limits. The context window bounds input plus output for the whole request, and the output cap bounds what one call can write. When a model is described as supporting 1M tokens, that is the window; max_tokens is the smaller number you pass on each request.

How do thinking and reasoning tokens count against the cap?

On reasoning models the cap covers the thinking as well as the visible answer. Anthropic's docs state that thinking tokens are a subset of max_tokens and are billed as output tokens. OpenAI's spec describes max_completion_tokens and the Responses API's max_output_tokens as an upper bound that includes visible output tokens and reasoning tokens.

A cap that worked for a plain chat model can leave nothing for the answer once reasoning is turned on. The model spends the budget thinking, the cap fires, and you get a truncated response with little or no visible text. Size the cap for thinking plus answer, and check the stop reason rather than the length of the text.

OpenAI renamed the parameter along the way. In Chat Completions, max_tokens is deprecated in favour of max_completion_tokens and is not compatible with o-series reasoning models. The Responses API uses max_output_tokens and marks a capped response as incomplete with the reason max_output_tokens.

What happens when a reply hits the cap?

Generation stops at the cap, often mid-sentence or mid-JSON, and the response says why. Anthropic returns stop_reason: "max_tokens"; OpenAI Chat Completions returns finish_reason: "length". Anthropic's guidance is to raise max_tokens or continue the response. If the cut-off content ends in an incomplete tool_use block, retry with a higher cap, because a partial tool call cannot be run.

The context window can end a run before your cap does. On Claude 4.5 models and newer, if input tokens plus max_tokens exceed the window, the API still accepts the request; if generation then reaches the window limit, it stops with stop_reason: "model_context_window_exceeded". Earlier models return a validation error instead. Treat both stops as truncation.

  • Branch on the stop reason before you parse the text as a finished answer.
  • Give structured outputs and tool calls enough room for the whole object.
  • When streaming, read the stop reason from the final event; the text deltas look the same either way.

A cap that is too small, and the response that reports it

POST /v1/messages
{
  "model": "claude-sonnet-4-5",
  "max_tokens": 20,
  "messages": [
    {"role": "user",
     "content": "Explain what max_tokens does in three sentences."}
  ]
}

response:
{
  "content": [{"type": "text",
    "text": "max_tokens sets the maximum number of tokens the model can generate in a single response. It does not"}],
  "stop_reason": "max_tokens",
  "stop_sequence": null,
  "usage": {"input_tokens": 18, "output_tokens": 20}
}

output_tokens equals the cap and stop_reason is max_tokens, so the text is a truncated answer. The 18 input tokens are counted separately from the cap.

Common questions

Max tokens: frequently asked

Is max_tokens the same as the context window?

No. The context window bounds everything in the request plus the generated output. max_tokens bounds only the output of one call, and each model has its own maximum for it. On Anthropic's 1M-token models the window is 1M tokens and a single request can generate up to 128k.

Do I pay for the full max_tokens value?

No. You are billed for the output tokens the model actually generated, which the response reports in its usage field. The cap is an upper bound, and the model often stops well before it. Thinking tokens count toward the cap and are billed as output tokens.

Why did my reasoning model return an empty or half-finished answer?

The cap probably fired while the model was still thinking. Thinking or reasoning tokens count against max_tokens, max_completion_tokens or max_output_tokens, so a cap sized for a plain answer can run out before any visible text appears. Check for stop_reason max_tokens, finish_reason length, or an incomplete status, and raise the cap.

Should I use max_tokens or max_completion_tokens with OpenAI?

In Chat Completions, use max_completion_tokens. OpenAI's spec marks max_tokens as deprecated and says it is not compatible with o-series reasoning models. In the Responses API the parameter is max_output_tokens.

Sources

Where these facts come from

context window token stop sequence reasoning streaming structured outputs