> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Reasoning models

> Every model in the catalog can think before it answers, and shows you the thinking in a separate field.

On a reasoning model the assistant message has two parts: `reasoning` (the chain of thought) and `content` (the answer). The split means you can log, display, or discard the thinking without ever parsing it out of the reply:

```python Python theme={null}
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://inference.pearlresearch.ai/v1",
    api_key=os.environ.get("PEARL_API_KEY"),
)

response = client.chat.completions.create(
    model="zai-org/GLM-5.3",
    messages=[
        {
            "role": "user",
            "content": "A bat and a ball cost $1.10. The bat costs $1 more than the ball. What does the ball cost?",
        }
    ],
)

msg = response.choices[0].message
reasoning = getattr(msg, "reasoning", None)
if reasoning is None and hasattr(msg, "model_extra"):
    reasoning = (msg.model_extra or {}).get("reasoning")

if reasoning:
    print("— thinking —\n", reasoning)
print("— answer —\n", msg.content)
```

```typescript TypeScript theme={null}
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://inference.pearlresearch.ai/v1',
  apiKey: process.env.PEARL_API_KEY,
});

const response = await client.chat.completions.create({
  model: 'zai-org/GLM-5.3',
  messages: [
    {
      role: 'user',
      content:
        'A bat and a ball cost $1.10. The bat costs $1 more than the ball. What does the ball cost?',
    },
  ],
});

const msg = response.choices[0].message as {content: string | null; reasoning?: string};
if (msg.reasoning) {
  console.log('— thinking —\n', msg.reasoning);
}
console.log('— answer —\n', msg.content);
```

How much thinking a reply gets follows from the effort and the model's own reading of the prompt: at high levels even a greeting can produce a long trace, at low levels hard prompts still get their due. When [streaming](/docs/streaming.md), `reasoning` arrives as deltas before `content` does, which makes long thinking phases feel alive instead of stalled.

> [!NOTE]
>
> **Migrating?** The trace used to arrive as `reasoning_content`. That field is no longer emitted anywhere: read `message.reasoning` on a buffered reply and `delta.reasoning` on a streamed one. On the request side, the flat `reasoning_effort` is gone too, replaced by the `reasoning` object below.

## Reasoning effort

Every reasoning control rides one object, `reasoning`, with two members you can use today: `enabled` (a plain on/off) and `effort`. Effort is one of `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. Omit the object for the model's default. In the OpenAI Python SDK pass it via `extra_body`:

```python Python theme={null}
response = client.chat.completions.create(
    model="deepseek-ai/DeepSeek-V4-Pro-0813",
    messages=[{"role": "user", "content": "Plan a 3-step refactor for this module: ..."}],
    extra_body={"reasoning": {"effort": "high"}},
)
```

```typescript TypeScript theme={null}
const response = await client.chat.completions.create({
  model: 'deepseek-ai/DeepSeek-V4-Pro-0813',
  messages: [{role: 'user', content: 'Plan a 3-step refactor for this module: ...'}],
  // @ts-expect-error Pearl extension, not in the OpenAI SDK types
  reasoning: {effort: 'high'},
});
```

```bash cURL theme={null}
curl https://inference.pearlresearch.ai/v1/chat/completions \
  -H "Authorization: Bearer $PEARL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-ai/DeepSeek-V4-Pro-0813",
    "messages": [{"role": "user", "content": "Plan a 3-step refactor for this module: ..."}],
    "reasoning": {"effort": "high"}
  }'
```

## How effort levels map

The seven levels are a normalized interface, we adopted the OpenRouter schema for them, so the same control works with every model whatever its worker natively calls its modes. Each model serves only some of those levels: the `supported_efforts` list in the model's `reasoning` block on `GET /models` is the served set, and the [model table](/docs/models.md) repeats it in its Reasoning column. Any level is accepted, and it resolves like this:

* A level the model serves is applied as is.
* Any other level rounds **up** to the next level the model serves, or to its highest level when you ask for more than it has.
* `none` is the disable control, not a rung: it switches thinking off on models not marked `mandatory` and returns `400` on the ones that are, so you never get back reasoning tokens you didn't expect.

For example, Qwen3.8-27B serves `low`, `medium`, and `xhigh`, so `minimal` runs as `low` and `high` or `max` run as `xhigh`. GLM-5.3 serves `low`, `high`, and `max`, so `medium` runs as `high` and `xhigh` as `max`. DeepSeek V4 Pro 0813 serves `high` and `max`, so everything from `minimal` to `medium` runs as `high`: asking for `low` still succeeds even though its `supported_efforts` lists only `max` and `high`. The Responses API echoes the applied level in `reasoning.effort`, which is the quickest way to check.

Omitting the control gets the `default_effort` from the same block, and it varies: GLM-5.3 and GLM-5.3-Flash default to `max`, which thinks at length even on simple prompts. Coding agents and pipelines should set an effort explicitly rather than rely on the default.

> [!NOTE]
>
> `reasoning.max_tokens` (a thinking-only budget) returns `400` on every model today; each model's `reasoning` block reports `supports_max_tokens: false`. To bound thinking, lower the effort or cap the top-level `max_tokens`, which covers the reasoning and the answer together.

> [!NOTE]
>
> On Chat Completions, provider-native reasoning switches are rejected, not ignored: sending `reasoning_effort`, `thinking`, `chat_template_kwargs.enable_thinking`, `thinking_budget`, or any of their siblings returns `400` on the key alone, whatever its value. Use `reasoning`. Clients that only know `reasoning_effort` need a custom body parameter instead; the [integration guides](/docs/integrations.md) show where each one sets it.

## Turning thinking off

Whether reasoning can be switched off entirely is per-model: it works only on models whose `reasoning` block on `GET /models` is not marked `mandatory: true`, and the reply then carries no `reasoning` and you stop paying for thinking tokens. Mandatory models always think and reject the disable with `400` rather than ignoring it; GLM-5.3 and GLM-5.3-Flash are the pair today, so budget for their thinking with `effort` and the top-level `max_tokens` instead. Either `effort: "none"` or `enabled: false` works. The example uses `Qwen/Qwen3.8-27B`, one of the non-mandatory models:

```python Python theme={null}
# The disable works on models not marked "mandatory": true on GET /models;
# GLM-5.3 and GLM-5.3-Flash are marked and reject this request with 400.
response = client.chat.completions.create(
    model="Qwen/Qwen3.8-27B",
    messages=[{"role": "user", "content": "hi"}],
    extra_body={"reasoning": {"effort": "none"}},  # or {"enabled": False}
)
```

```typescript TypeScript theme={null}
// The disable works on models not marked "mandatory": true on GET /models;
// GLM-5.3 and GLM-5.3-Flash are marked and reject this request with 400.
const response = await client.chat.completions.create({
  model: 'Qwen/Qwen3.8-27B',
  messages: [{role: 'user', content: 'hi'}],
  // @ts-expect-error Pearl extension, not in the OpenAI SDK types
  reasoning: {effort: 'none'}, // or {enabled: false}
});
```

```bash cURL theme={null}
# The disable works on models not marked "mandatory": true on GET /models;
# GLM-5.3 and GLM-5.3-Flash are marked and reject this request with 400.
curl https://inference.pearlresearch.ai/v1/chat/completions \
  -H "Authorization: Bearer $PEARL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen3.8-27B",
    "messages": [{"role": "user", "content": "hi"}],
    "reasoning": {"effort": "none"}
  }'
```

## Messages and Responses

The same levels and the same mapping apply on the other API formats, through each format's own field:

* [Anthropic Messages](/docs/reference/messages.md): effort goes in `output_config.effort`, and `thinking: {"type": "disabled"}` turns thinking off. Thinking budgets (`budget_tokens`) are not supported. The trace comes back as `thinking` content blocks.
* [OpenAI Responses](/docs/reference/responses.md): effort goes in `reasoning.effort`, where `none` turns thinking off. The reply echoes the applied level in `reasoning.effort`.

```python Anthropic Messages theme={null}
import os
from anthropic import Anthropic

client = Anthropic(
    base_url="https://inference.pearlresearch.ai",
    api_key=os.environ.get("PEARL_API_KEY"),
)

response = client.messages.create(
    model="Qwen/Qwen3.8-27B",
    max_tokens=8192,
    messages=[{"role": "user", "content": "Plan a 3-step refactor for this module: ..."}],
    extra_body={"output_config": {"effort": "high"}},
    # thinking={"type": "disabled"},  # turn thinking off (not on GLM-5.3 / GLM-5.3-Flash)
)

for block in response.content:
    if block.type == "thinking":
        print("— thinking —\n", block.thinking)
    elif block.type == "text":
        print("— answer —\n", block.text)
```

```python OpenAI Responses theme={null}
response = client.responses.create(
    model="Qwen/Qwen3.8-27B",
    input="Plan a 3-step refactor for this module: ...",
    store=False,
    max_output_tokens=8192,
    reasoning={"effort": "high"},  # "none" turns thinking off (not on GLM-5.3 / GLM-5.3-Flash)
)

print(response.reasoning.effort)  # the level the model applied, after rounding
print(response.output_text)
```

## Multi-turn conversations

Treat `reasoning` as output for humans, not input for models: when you build the next turn's history, append the assistant's `content` only. The model re-thinks each turn, echoing old reasoning back just spends input tokens on text the model neither expects nor needs.

```python theme={null}
# Feed only the answer back into history, drop the reasoning trace.
messages.append({"role": "assistant", "content": msg.content})
```

If you do replay a trace, put it on the assistant message as `reasoning`. An assistant message carrying `reasoning_content` is rejected with `400`: presence is enough, so an explicit `null` fails too.

## What thinking costs

* Reasoning tokens are **output tokens**, billed at the model's output rate and counted inside `completion_tokens`. Some workers itemize them as `completion_tokens_details.reasoning_tokens` in usage.
* Thinking consumes the `max_tokens` budget before the answer does. If you see `finish_reason: "length"` with lots of reasoning and a cut-off answer, raise `max_tokens` or lower the reasoning effort.
* For high-volume pipelines, benchmark GLM-5.3 Flash at `low` effort against DeepSeek V4 Pro 0813 at default, the answer-quality-per-dollar ordering depends on your task, and the [playground](https://platform.pearlresearch.ai/playground) makes the comparison quick.

> [!NOTE]
>
> Chain-of-thought is a working scratchpad, not a guaranteed explanation, audit decisions from the answer and your own evaluations, not from the narrative in `reasoning`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.