The max token cap is not the usage

The cap is a request setting

max_tokens on the request is the ceiling the application asked for. It is a number you set before the call. It is not how many tokens the reply used, and it is not a quality score.

A later call can use a different cap. Each request keeps the cap that was on that request.

Usage is what the response metered

The completion token count, when the response includes it, is the usage for that reply. It can be lower than the cap. It can be absent. If it is absent, write that usage was not in the response. Do not substitute the cap.

This page does not raise the cap and does not retry the call. It only stops the two numbers from being swapped.

Both numbers, labeled

File the request id, the max_tokens value, and the completion count if present. A sentence about how much text was metered uses the count. A sentence about the ceiling uses the cap.

Worked case: a cap of 256 filed as the usage

Request req-830 set max_tokens to 256. The response reports 40 completion tokens. A draft says the model used 256 tokens because that was the setting.

The note says the cap was 256 and the metered completion count was 40. The usage line is 40. The cap stays the request setting.

request: req-830
max_tokens: 256
completion tokens: 40
write: cap and meter
not: used 256