In OpenAI Chat Completions, how does max_completion_tokens differ from max_tokens?

## One budget, two names Every Chat Completions request may bound how much the model writes. Historically the parameter was `max_tokens`. OpenAI deprecated it in favour of `max_completion_tokens`. The new name is not cosmetic: it exists because reasoning models generate tokens you never see. ## What max_completion_tokens counts `max_completion_tokens` is an upper bound on **all** tokens generated for the response — the assistant text you receive **plus** reasoning tokens on models that reason internally before answering. Those hidden tokens are billed as output and are reported separately in `usage.completion_tokens_details.reasoning_tokens`. The practical trap: set a tight budget on a reasoning model and the model can spend the entire allowance thinking, returning empty or near-empty content with `finish_reason` `"length"`. You paid, and you got nothing readable. On reasoning models the budget must be generous enough for reasoning *and* the answer. ## Why max_tokens was deprecated Under the old name it was ambiguous whether the cap covered invisible work. Rather than redefine it, OpenAI introduced the clearer name and marked the old one deprecated in Chat Completions; the o-series reasoning models do not accept `max_tokens` at all and reject the request. Non-reasoning models still honour `max_tokens` for compatibility, but new code should send `max_completion_tokens`. ## Neither one limits the prompt A persistent misconception is that this parameter protects you from a giant conversation. It does not. It bounds output only. The relationship you must respect is arithmetic: prompt tokens plus generated tokens must fit the model's context window. If your transcript is already near the ceiling, reserving a large output budget can make the request unsatisfiable and you get a 400 with a context-length error before a single token is generated. That is why history trimming and output budgeting are the same design problem. ## finish_reason is the field that matters When generation stops because the cap was reached, the HTTP status is still 200 and the body still has content — just truncated. `choices[0].finish_reason` is `"length"` instead of `"stop"`. Other values you will see are `"tool_calls"` when the model wants a tool run and `"content_filter"` when output was filtered. Production code should branch on this field explicitly: `"stop"` means the model finished on its own; `"length"` means you cut it off and the payload is probably invalid if you were expecting structured text. Retrying the same request unchanged usually reproduces the truncation — you need a bigger budget, a shorter prompt, or a continuation strategy. ## Sizing the budget in practice Three rules cover most services. First, set a cap deliberately rather than leaving it unset — an unbounded response can run away in latency and cost. Second, size it from what a good answer actually needs, plus headroom for reasoning if the model reasons, and validate it against the remaining context space. Third, log the distribution of `usage.completion_tokens` and set the cap near a high percentile rather than at the mean, so ordinary answers are never clipped. Because the cap also bounds worst-case generation time for a streamed response, it doubles as a latency lever. ## Interview-grade summary The strong answer names the deprecation, explains that the new parameter includes hidden reasoning tokens, states clearly that neither bounds the prompt, and then moves straight to `finish_reason` `"length"` as the thing you must actually handle in code. Candidates who stop at "it limits the response length" sound like they have only read the quickstart.