Reasoning effort

What the five effort levels trade off, how reasoning tokens are billed, and how to choose.

GPT-5.5 is a reasoning model: before producing visible output it can spend tokens thinking. The reasoning_effort parameter (Chat Completions) or reasoning.effort (Responses API) controls how much. It is the single highest-leverage knob you have over both quality and cost.

The trade-off

Higher effort buys depth — more hypotheses considered, more self-checking — at the price of latency and output-token spend. Reasoning tokens are generated before the first visible token, so effort directly moves time-to-first-token as well as total cost.

Effort	Behavior	Typical fit
`none`	Few or no reasoning tokens; fastest time-to-first-token	Extraction, classification, reformatting, simple lookups
`low`	Brief reasoning	Summarization, straightforward Q&A, routine code edits
`medium` (default)	Balanced	General coding, analysis, multi-step tool use
`high`	Extended reasoning; slow and expensive	Hard debugging, mathematical derivation, long-horizon planning
`xhigh`	Maximum reasoning depth; slowest and most expensive	Frontier-difficulty problems where correctness dominates all other costs

Rough intuition on spend: a request that produces a 300-token answer might generate ~0 reasoning tokens at none, a few hundred at medium, and several thousand at high or xhigh on a genuinely hard problem. Check usage.completion_tokens_details.reasoning_tokens (Chat Completions) or usage.output_tokens_details.reasoning_tokens (Responses) on your real traffic before deciding.

Billing

Reasoning tokens are billed as output tokens, at the output rate ($24.00/M base tier). This is the industry standard — OpenAI, Azure, and every reseller of reasoning models bill this way — and Draftworks is no exception. They are included in completion_tokens / output_tokens and count against max_completion_tokens / max_output_tokens. The receipt's output_tokens field includes them, so billed amounts are independently checkable.

Practical consequence: when setting max_completion_tokens for a high-effort request, budget for reasoning. A cap of 1,000 tokens on a high-effort request can be consumed entirely by reasoning, yielding a truncated or empty visible answer with finish_reason: "length".

Choosing a level

Start at medium and move down. Most production traffic is simpler than it looks; if low holds your quality bar, it is meaningfully faster and cheaper.
Reserve high for requests where a wrong answer costs more than a few extra seconds and cents, and xhigh for the rare problems where you would happily wait minutes.
Use none on the hot path. For latency-sensitive UI (autocomplete, live classification), none gets time-to-first-token near the ~450 ms floor.
Effort is per request, not per key or per account. Route each call site independently — one application can use none for routing and high for the final synthesis in the same flow.

Setting it

Chat Completions

Python

completion = client.chat.completions.create(
    model="gpt-5.5",
    reasoning_effort="high",
    max_completion_tokens=16384,  # leave room for reasoning
    messages=[{"role": "user", "content": "Find the bug in this concurrent queue: ..."}],
)
print(completion.usage.completion_tokens_details.reasoning_tokens)

Responses API

TypeScript

const response = await client.responses.create({
  model: "gpt-5.5",
  reasoning: { effort: "none" },
  input: "Classify this ticket as billing, bug, or feature-request: ...",
});
console.log(response.usage?.output_tokens_details?.reasoning_tokens);

The Responses API additionally accepts reasoning.summary (auto, concise, detailed) to receive a natural-language summary of the reasoning in the output items. The raw chain of thought is never returned by either API.