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

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.5 and other xAI reasoning models, it maps to xAI effort low.
• Claude Opus 4.8 and Sonnet 5 map none to thinking disabled.
• minimal and xhigh are available only where the upstream effort ladder exposes them. They are not aliases for low and high.

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 "max"

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

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

Provider allowlists use the corresponding provider-scoped form, such as reasoning_effort "minimal" is not supported by provider googleai. Google AI reports an unrecognized value as invalid reasoning_effort "max".