reasoning.effort in Practice: Making Reasoning Depth a Tunable Parameter

reasoning.effort is a per-request OpenAI API parameter controlling how deeply the model reasons before answering: lower tiers are faster and cheaper, higher tiers trade time and cost for accuracy. It turns "same model, different depth of thinking" into one line of configuration. This tutorial covers the syntax, per-tier scenarios, the max_output_tokens interaction, and the two-sided cost of picking the wrong tier.

Note: the code here was verified line-by-line against the official Reasoning guide (docs-checked version); lastTestedAt marks the verification date. The tier system follows the GPT-5.6 family.

1. Syntax: Three Languages

Add the reasoning parameter to the request. The official guide shows equivalent examples across languages:

from openai import OpenAI

client = OpenAI()

resp = client.responses.create(
    model="gpt-5.6-terra",
    reasoning={"effort": "medium"},
    input=[
        {"role": "user", "content": "Classify these log lines by severity and summarize"},
    ],
)

print(resp.output_text)

The JavaScript form is identical (reasoning: { effort: "low" }), and the official guide also includes curl and Ruby equivalents -- the parameter name and values are the same across languages.

2. The Tier Selection Table

The GPT-5.6 family tunes effort continuously from none to max:

Two selection principles: first, mismatched tiers waste in both directions -- too low answers wrong and forces rework, too high pays a reasoning premium for fixed-pattern tasks; second, tiers are per-request, so one product can mix tiers by task difficulty.

3. max_output_tokens: Budget for the Reasoning

At higher effort, internal reasoning consumes output budget. When the budget runs out the response does not error -- it returns with the incomplete status, and the official guide's example demonstrates the handling:

const response = await client.responses.create({
  model: "gpt-5.6-terra",
  reasoning: { effort: "medium" },
  input: [{ role: "user", content: prompt }],
  max_output_tokens: 300,
});

if (response.status === "incomplete" && response.incomplete_details) {
  // Budget exhausted: raise max_output_tokens or lower the effort
  console.log(response.incomplete_details);
}

Make this check standard in production: an incomplete response looks like a normal return, but the content is truncated -- without the status check, the error flows silently downstream.

4. The Cost Link: effort Is a Billing Knob

Higher effort means more reasoning tokens billed at output price, and output costs several times the input price. With Sol as the example (promo $4/$20 from 2026-08-21 per the official changelog): output is 5x the input price, so doubling reasoning tokens doubles the output line of your bill.

curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-5.6-sol",
    "reasoning": {"effort": "high"},
    "input": "Derive step by step the solution to this constraint satisfaction problem"
  }'

There is no universal multiplier -- the most accurate measurement is running the same batch on two adjacent tiers and comparing real token usage and accuracy: if accuracy holds, drop a tier. That is a free optimization.

5. Dynamic Routing: The Biggest Cost Lever

More effective than "picking one tier well" is "tuning per request":

1. Tag difficulty: rules (task type, input length) or a lightweight classifier.
2. Split the traffic: easy to none/low, uncertain to medium, hard-tagged to high and up.
3. Recalibrate: sample accuracy and cost across tiers periodically and adjust thresholds.

The GPT-5.6 family shares a 1.05M context and native multimodality across tiers, so moving up or down requires no prompt restructuring -- that is what makes effort a billing knob. For extreme difficulty, o-series is the dedicated line (effort pinned at max); everyday traffic stays on the GPT-5.6 family with per-request tuning.

Frequently Asked Questions

1. Which tasks fit each effort tier?

none / low: classification, extraction, format conversion, simple rewrites -- fast, cheap, fixed answer patterns. medium: the daily product workhorse -- routine Q&A, summaries, code completion. high / xhigh: multi-step reasoning, math, complex debugging, agent planning. max: must-get-it-right scenarios -- competition math, critical code correctness. The cost of a wrong tier cuts both ways: too low answers wrong, too high burns money.

2. Why is my response truncated?

Most likely max_output_tokens did not budget for reasoning -- higher effort consumes output budget for thinking itself. The official example checks response.status explicitly: incomplete means the budget ran out; raise max_output_tokens or lower the effort.

3. How much does raising effort cost?

Higher effort means more reasoning tokens billed at output price. At Sol's promo $4/$20 (from 2026-08-21): output is 5x the input price, so doubling reasoning tokens doubles the output line of the bill. There is no universal multiplier -- run the same task on two adjacent tiers and compare real token usage.

4. Should effort go in the system prompt or the parameter?

The parameter. effort is an API-level configuration; "please think deeply" in a prompt does not change the reasoning budget the model allocates. Parameterizing also lets a routing layer set it dynamically by task difficulty, while prompts are static.

5. How do I implement dynamic routing?

Three steps: tag request difficulty (rules or a lightweight classifier); send easy traffic to low/none, uncertain to medium, hard-tagged to high and up; sample accuracy across tiers periodically and recalibrate thresholds. The GPT-5.6 family shares context and multimodal capabilities, so tier changes need no prompt restructuring.

6. How does o-series relate to effort?

o-series is the dedicated fixed-deep-reasoning line -- effort pinned at max, slow and expensive, designed for must-be-right scenarios. The GPT-5.6 family's effort parameter makes depth continuously tunable. Default to tuning effort on the GPT-5.6 family; switch to o-series only for the hardest tasks that max effort still cannot solve.

Next Steps

• Family-level selection (prices updated to the 8-21 promo)? Read GPT Models Complete Guide (2026-07): Choosing Between GPT-5.6 Sol / Terra / Luna.
• Structured outputs paired with high effort? Read OpenAI Structured Outputs: The Complete Guide to json_schema, strict Mode, and Common Errors.
• Advanced per-request controls (structured outputs / streaming / Batch)? Read Responses API advanced: structured outputs, streaming SSE, Batch API, prompt caching.