Reasoning effort

reasoning_effort controls how much internal reasoning a model may use before it answers. ModelRelay exposes one provider-neutral ladder:

none → minimal → low → medium → high → xhigh → max

Leave the field empty to use the provider’s default. Model support is a subset of the ladder: a recognized value outside a matched model’s subset is rejected instead of being silently downgraded.

Supported values by model

Models without a mapped reasoning control omit the field and retain the provider default. Do not infer support from the provider alone; use the model-specific discovery response described below.

Mapping semantics

The ladder describes intent, not identical upstream parameters:

• Always-reasoning models cannot disable thinking. For Claude Fable and Mythos, none maps to Anthropic effort low; for Grok 4.6 and other xAI reasoning models, it maps to xAI effort low.
• Claude Opus 5 and Sonnet 5 map none to thinking disabled.
• Gemini 3.7 Flash rejects both none and minimal; low is its lowest supported thinking level.
• Gemini medium forwards to the provider’s distinct medium thinking level; it is not reduced to low.
• Omitting Gemini effort leaves the choice to the model rather than pinning a hidden relay default. Request low explicitly when Gemini 3.7 Flash cost and latency must stay bounded. Thinking tokens consume the output-token budget, so leave enough room for visible output.
• minimal, xhigh, and max are available only where the upstream effort ladder exposes them. They are distinct levels, not aliases for neighboring values.

Why effort matters

Reasoning affects both latency and billed output. In same-prompt production probes, GPT-5.6 Luna at none answered in about 0.7 seconds with 5 output tokens. At the provider’s default medium, equivalent runs took about 2.5–2.8 seconds and used 200–312 output tokens.

Reasoning tokens are provider-billed output tokens. Lower effort can therefore reduce latency and cost when the task does not benefit from deeper reasoning; use higher effort when the expected quality gain justifies that budget.

Discover model support

GET /api/v1/customers/me/models returns a reasoning_efforts array for each customer-visible model. Clients should validate requested values against that array instead of maintaining their own provider table. See Get Model Catalog for the response shape.

RLM subcalls

RLM subcalls default to reasoning_effort: "none" because the root loop is the reasoning layer and subcalls are bounded workers. If the selected model has no none mapping, the implicit default is omitted so the provider default is preserved; an explicit unsupported override is rejected. Set subcall_reasoning_effort only when a delegated task needs additional reasoning. See the RLM API reference and models and subcalls guide.

Validation errors

An unrecognized ladder value is rejected with HTTP 400 and an INVALID_REQUEST classification. Model-gated provider adapters use this message shape:

unsupported reasoning_effort "ultra"

A recognized value outside a matched model’s supported subset is also rejected with HTTP 400. Model-gated adapters name the model and may list its supported values:

reasoning_effort "minimal" is not supported by model claude-sonnet-5

Provider allowlists use the corresponding provider-scoped form. Google AI reports unsupported recognized values with the resolved model and supported subset, and reports an unrecognized value as invalid reasoning_effort "ultra".