Reasoning models

Reasoning models like GPT-5.5 use internal reasoning tokens before producing a response. This helps the model plan, use tools effectively, inspect alternatives, recover from ambiguity, and solve harder multi-step tasks. Reasoning models work especially well for complex problem solving, coding, scientific reasoning, and multi-step agentic workflows. They're also the best models for Codex CLI, our lightweight coding agent.

Start with gpt-5.6 for most reasoning workloads. If you need the highest-intelligence API option for more challenging problems that can tolerate more latency, use gpt-5.5-pro. For lower cost, consider gpt-5.4 and for lower cost and latency, consider gpt-5.4-mini.

Reasoning models work better with the Responses API. While the Chat Completions API is still supported, you'll get improved model intelligence and performance by using Responses.

Get started with reasoning

Call the Responses API and specify your reasoning model and reasoning effort:

Using a reasoning model in the Responses API

import OpenAI from "openai";

const openai = new OpenAI();

const prompt = `
Write a bash script that takes a matrix represented as a string with 
format '[1,2],[3,4],[5,6]' and prints the transpose in the same format.
`;

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

console.log(response.output_text);

from openai import OpenAI

client = OpenAI()

prompt = """
Write a bash script that takes a matrix represented as a string with 
format '[1,2],[3,4],[5,6]' and prints the transpose in the same format.
"""

response = client.responses.create(
    model="gpt-5.6",
    reasoning={"effort": "low"},
    input=[
        {
            "role": "user", 
            "content": prompt
        }
    ]
)

print(response.output_text)

curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-5.6",
    "reasoning": {"effort": "low"},
    "input": [
      {
        "role": "user",
        "content": "Write a bash script that takes a matrix represented as a string with format \"[1,2],[3,4],[5,6]\" and prints the transpose in the same format."
      }
    ]
  }'

Reasoning effort

The reasoning.effort parameter guides the model on how much to think when performing a task.

Supported values are model-dependent and can include none, minimal, low, medium, high, and xhigh. Lower effort favors speed and lower token usage, while at higher effort the model thinks more completely to provide higher quality responses. The models also reason adaptively across reasoning efforts, using fewer tokens for simpler tasks and thinking harder for complex tasks.

Defaults are also model-dependent rather than universal. gpt-5.5 defaults to medium reasoning effort. This is the best starting point for gpt-5.5’s full balance of quality, reliability and performance.

Effort	Best for
`none`	Latency-critical tasks that do not benefit from any reasoning or multi-chained tool calls. For latency-sensitive use cases with `gpt-5.5`, we recommend trying `low` to begin with and then moving to `none` if required. Common use cases include voice, fast information retrieval, and classification.
`low`	Efficient reasoning with a modest latency increase. Ideal for use cases requiring tool-use, planning, search, or multi-step decision making, while optimizing for speed and cost. Common use cases include data analysis, drafting, execution-oriented coding, and customer support / chat assistant workflows.
`medium`	When quality and reliability matter, and the task involves planning, complex reasoning, and judgement. Default configuration for most workloads, and a well-balanced point on the pareto curve of latency, performance and cost. Common use cases include agentic coding, research, working with spreadsheets & slides, and delegating long-horizon work.
`high`	Hard reasoning, complex debugging, deep planning, and high-value tasks where quality and intelligence matters more than latency. Recommended for complex workflows and agentic tasks. Common use cases include agentic coding, long-horizon research, and knowledge work. Depending on the complexity of the task, evaluate both `medium` and `high`.
`xhigh`	Deep research, asynchronous workflows and agentic tasks that require long runs. Only use when your evals show a clear benefit that justifies the extra latency and cost. Common use cases include security and code review, enterprise productivity, deeper research tasks, and challenging coding workflows.

For faster time to first visible token in latency-sensitive applications, ask the model to generate a short preamble before continuing with deeper reasoning.

Some models support only a subset of these values, so check the relevant model page before choosing a setting.

Reasoning mode

GPT-5.6 models support standard and pro reasoning modes in the Responses API. standard is the default. Set reasoning.mode to pro for difficult tasks that need more model work and can tolerate higher latency and token usage.

Reasoning mode and reasoning effort are independent. Mode selects standard or pro execution, while reasoning.effort controls how much reasoning the model applies within that mode. If you omit reasoning.effort, GPT-5.6 defaults to medium in both modes.

Using pro reasoning mode

curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-5.6",
    "reasoning": {
      "mode": "pro",
      "effort": "medium"
    },
    "input": "Review this database migration plan and identify potential failure modes."
  }'

Pro mode aggregates the model work performed to produce the final answer and bills those tokens at the selected model's standard token rates. Pro mode performs more model work than standard mode, increasing token usage and cost. Existing Pro model IDs keep their current behavior and pricing.

How reasoning works

Reasoning models introduce reasoning tokens in addition to input and output tokens. The models use these reasoning tokens to "think," breaking down the prompt and considering multiple approaches to generating a response. Our reasoning models like gpt-5.5 and gpt-5.4 support interleaved thinking, where the model is able to generate visible output tokens before and in between thinking, and is able to think in between tool calls.

Here is the default behavior for a multi-step conversation between a user and an assistant. Input and output tokens from each step are carried over, while reasoning from earlier turns is not rendered into the next sample. Models that support persisted reasoning can change this behavior with reasoning.context.

Reasoning tokens with current-turn context

While reasoning tokens are not visible via the API, they still occupy space in the model's context window and are billed as output tokens.

Managing the context window

It's important to ensure there's enough space in the context window for reasoning tokens when creating responses. Depending on the problem's complexity, the models may generate anywhere from a few hundred to tens of thousands of reasoning tokens. The exact number of reasoning tokens used is visible in the usage object of the response object, under output_tokens_details:

{
  "usage": {
    "input_tokens": 75,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 1186,
    "output_tokens_details": {
      "reasoning_tokens": 1024
    },
    "total_tokens": 1261
  }
}

Context window lengths are found on the model reference page, and will differ across model snapshots.

Controlling costs

To manage costs with reasoning models, you can limit the total number of tokens the model generates, including reasoning tokens, visible output tokens, and non-visible formatting tokens, by using the max_output_tokens parameter. See output token counts for details about how generated tokens are reflected in usage and output limits.

Allocating space for reasoning

If the generated tokens reach the context window limit or the max_output_tokens value you've set, you'll receive a response with a status of incomplete and incomplete_details with reason set to max_output_tokens. This might occur before any visible output tokens are produced, meaning you could incur costs for input and reasoning tokens without receiving a visible response.

To prevent this, ensure there's sufficient space in the context window or adjust the max_output_tokens value to a higher number. OpenAI recommends reserving at least 25,000 tokens for reasoning and outputs when you start experimenting with these models. As you become familiar with the number of reasoning tokens your prompts require, you can adjust this buffer accordingly.

Handling incomplete responses

import OpenAI from "openai";

const openai = new OpenAI();

const prompt = `
Write a bash script that takes a matrix represented as a string with 
format '[1,2],[3,4],[5,6]' and prints the transpose in the same format.
`;

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

if (
    response.status === "incomplete" &&
    response.incomplete_details.reason === "max_output_tokens"
) {
    console.log("Ran out of tokens");
    if (response.output_text?.length > 0) {
        console.log("Partial output:", response.output_text);
    } else {
        console.log("Ran out of tokens during reasoning");
    }
}

from openai import OpenAI

client = OpenAI()

prompt = """
Write a bash script that takes a matrix represented as a string with 
format '[1,2],[3,4],[5,6]' and prints the transpose in the same format.
"""

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

if response.status == "incomplete" and response.incomplete_details.reason == "max_output_tokens":
    print("Ran out of tokens")
    if response.output_text:
        print("Partial output:", response.output_text)
    else: 
        print("Ran out of tokens during reasoning")

Keeping reasoning items in context

When doing function calling with a reasoning model in the Responses API, we highly recommend you pass back any reasoning items returned with the last function call (in addition to the output of your function). If the model calls multiple functions consecutively, you should pass back all reasoning items, function call items, and function call output items, since the last user message. This allows the model to continue its reasoning process to produce better results in the most token-efficient manner.

The simplest way to do this is to pass in all reasoning items from a previous response into the next one. Our systems will smartly ignore any reasoning items that aren't relevant to your functions, and only retain those in context that are relevant. You can pass reasoning items from previous responses either using the previous_response_id parameter, or by manually passing in all the output items from a past response into the input of a new one.

For advanced use cases where you might be truncating and optimizing parts of the context window before passing them on to the next response, just ensure all items between the last user message and your function call output are passed into the next response untouched. This will ensure that the model has all the context it needs.

Check out this guide to learn more about manual context management.

Preserve reasoning across calls

Conversation state and reasoning state serve different purposes. Passing messages across calls gives the model the visible conversation history. On supported models, persisted reasoning also lets the model render compatible reasoning items from earlier turns into its next context.

Persisted reasoning provides continuity; it does not expose the model's raw reasoning. The reasoning items remain opaque, and the API does not return their reasoning text. Set reasoning.context to control which available reasoning items the model can use:

Support for reasoning.context modes is model-dependent. Replace YOUR_MODEL_ID in the examples with a model that supports the mode you select.

Value	Behavior
`auto`	Uses the selected model's default. Omitting `reasoning.context` has the same effect as `auto`.
`current_turn`	Makes reasoning from the active turn available, but does not render reasoning from earlier turns into the next sample.
`all_turns`	Renders available, compatible reasoning items from earlier turns into the next sample. Only supported models accept this value.

The response's reasoning.context field contains the effective mode, either current_turn or all_turns. Check this field on each response to confirm which mode the model used. The setting does not create reasoning items that are not already available.

all_turns has an effect only when the request has access to earlier response items. Use previous_response_id, attach the response to a conversation, or manually replay the complete response history. On the first request, current_turn and all_turns behave the same because no earlier reasoning exists.

Continue reasoning with stored responses

Use previous_response_id for the shortest stateful integration:

Preserve reasoning with a previous response

import OpenAI from "openai";

const client = new OpenAI();

const first = await client.responses.create({
  model: "YOUR_MODEL_ID",
  input: "Inspect this repository and identify the likely bug.",
  reasoning: { context: "current_turn" },
});

const second = await client.responses.create({
  model: "YOUR_MODEL_ID",
  previous_response_id: first.id,
  input: "Now patch the bug and explain the change.",
  reasoning: { context: "all_turns" },
});

console.log(second.output_text);

from openai import OpenAI

client = OpenAI()

first = client.responses.create(
    model="YOUR_MODEL_ID",
    input="Inspect this repository and identify the likely bug.",
    reasoning={"context": "current_turn"},
)

second = client.responses.create(
    model="YOUR_MODEL_ID",
    previous_response_id=first.id,
    input="Now patch the bug and explain the change.",
    reasoning={"context": "all_turns"},
)

print(second.output_text)

Use current_turn when replaying older response items that the model no longer needs. Those reasoning items can remain in the API payload for continuity, but the service does not render them into the new sample. This can reduce the rendered context for long-running workflows.

Preserve reasoning without stored responses

When using the Responses API in a stateless mode, either with store set to false or for an organization enrolled in zero data retention, request reasoning.encrypted_content in the include parameter on every call:

curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-5.6",
    "reasoning": {"effort": "medium"},
    "input": "What is the weather like today?",
    "tools": [ ... function config here ... ],
    "include": [ "reasoning.encrypted_content" ]
  }'

Reasoning items in the output array will include an encrypted_content property containing encrypted reasoning tokens that you can pass to future calls.

To use all_turns with store: false, request encrypted reasoning content on every call, preserve every output item, append the next user message, and replay the complete history:

Preserve reasoning without storing responses

import OpenAI from "openai";

const client = new OpenAI();

const history = [
  {
    role: "user",
    content: "Inspect this repository and identify the likely bug.",
  },
];

const first = await client.responses.create({
  model: "YOUR_MODEL_ID",
  store: false,
  input: history,
  include: ["reasoning.encrypted_content"],
  reasoning: { context: "current_turn" },
});

// Keep every output item, including encrypted reasoning and assistant phase.
history.push(...first.output);
history.push({
  role: "user",
  content: "Now patch the bug and explain the change.",
});

const second = await client.responses.create({
  model: "YOUR_MODEL_ID",
  store: false,
  input: history,
  include: ["reasoning.encrypted_content"],
  reasoning: { context: "all_turns" },
});

console.log(second.output_text);

from openai import OpenAI

client = OpenAI()

history = [
    {
        "role": "user",
        "content": "Inspect this repository and identify the likely bug.",
    }
]

first = client.responses.create(
    model="YOUR_MODEL_ID",
    store=False,
    input=history,
    include=["reasoning.encrypted_content"],
    reasoning={"context": "current_turn"},
)

# Keep every output item, including encrypted reasoning and assistant phase.
history.extend(item.model_dump() for item in first.output)
history.append(
    {
        "role": "user",
        "content": "Now patch the bug and explain the change.",
    }
)

second = client.responses.create(
    model="YOUR_MODEL_ID",
    store=False,
    input=history,
    include=["reasoning.encrypted_content"],
    reasoning={"context": "all_turns"},
)

print(second.output_text)

Reasoning summaries

While we don't expose the raw reasoning tokens emitted by the model, you can view a summary of the model's reasoning using the summary parameter. See our model documentation to check which reasoning models support summaries.

Different models support different reasoning summary settings. For example, our computer use model supports the concise summarizer, while o4-mini supports detailed. To access the most detailed summarizer available for a model, set the value of this parameter to auto. auto will be equivalent to detailed for most reasoning models today, but there may be more granular settings in the future.

Reasoning summary output is part of the summary array in the reasoning output item. This output will not be included unless you explicitly opt in to including reasoning summaries.

The example below shows how to make an API request that includes a reasoning summary.

Include a reasoning summary with the API response

import OpenAI from "openai";
const openai = new OpenAI();

const response = await openai.responses.create({
  model: "gpt-5.6",
  input: "What is the capital of France?",
  reasoning: {
    effort: "low",
    summary: "auto",
  },
});

console.log(response.output);

from openai import OpenAI
client = OpenAI()

response = client.responses.create(
    model="gpt-5.6",
    input="What is the capital of France?",
    reasoning={
        "effort": "low",
        "summary": "auto"
    }
)

print(response.output)

curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-5.6",
    "input": "What is the capital of France?",
    "reasoning": {
        "effort": "low",
        "summary": "auto"
    }
  }'

This API request will return an output array with both an assistant message and a summary of the model's reasoning in generating that response.

[
  {
    "id": "rs_6876cf02e0bc8192b74af0fb64b715ff06fa2fcced15a5ac",
    "type": "reasoning",
    "summary": [
      {
        "type": "summary_text",
        "text": "**Answering a simple question**\n\nI\u2019m looking at a straightforward question: the capital of France is Paris. It\u2019s a well-known fact, and I want to keep it brief and to the point. Paris is known for its history, art, and culture, so it might be nice to add just a hint of that charm. But mostly, I\u2019ll aim to focus on delivering a clear and direct answer, ensuring the user gets what they\u2019re looking for without any extra fluff."
      }
    ]
  },
  {
    "id": "msg_6876cf054f58819284ecc1058131305506fa2fcced15a5ac",
    "type": "message",
    "status": "completed",
    "content": [
      {
        "type": "output_text",
        "annotations": [],
        "logprobs": [],
        "text": "The capital of France is Paris."
      }
    ],
    "role": "assistant"
  }
]

Before using summarizers with our latest reasoning models, you may need to complete organization verification to ensure safe deployment. Get started with verification on the platform settings page.

`phase` parameter

For long-running or tool-heavy flows with GPT-5.5 and GPT-5.4 in the Responses API, use the assistant message phase field to avoid early stopping and other misbehavior. phase is optional at the API level, but OpenAI recommends using it. Use phase: "commentary" for intermediate assistant updates, such as preambles before tool calls, and phase: "final_answer" for the completed answer. Don't add phase to user messages. Using previous_response_id is usually the simplest path because prior assistant state is preserved. If you replay assistant history manually, preserve each original phase value. Missing or dropped phase can cause preambles to be treated as final answers in those workflows. For model-specific prompt guidance, see Prompting GPT-5.5.

Round-trip assistant phase values

import OpenAI from "openai";
const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-5.6",
  input: [
    {
      role: "assistant",
      phase: "commentary",
      content:
        "I’ll inspect the logs and then summarize root cause and remediation.",
    },
    {
      role: "assistant",
      phase: "final_answer",
      content: "Root cause: cache invalidation race.",
    },
    {
      role: "user",
      content: "Great—now give me a rollout-safe fix plan.",
    },
  ],
});

console.log(response.output_text);

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5.6",
    input=[
        {
            "role": "assistant",
            "phase": "commentary",
            "content": "I’ll inspect the logs and then summarize root cause and remediation.",
        },
        {
            "role": "assistant",
            "phase": "final_answer",
            "content": "Root cause: cache invalidation race.",
        },
        {
            "role": "user",
            "content": "Great—now give me a rollout-safe fix plan.",
        },
    ],
)

print(response.output_text)

Advice on prompting

Consider these differences when prompting a reasoning model. Reasoning-capable GPT-5 models usually work best when you give them a clear goal, strong constraints, and an explicit output contract without prescribing every intermediate step.

Give the model the task, constraints, and desired output format.
Treat reasoning.effort as a tuning knob, not the primary way to recover quality.
For agentic or research-heavy workflows, define what counts as done and how the model should verify its work.

For more information on best practices when using reasoning models, refer to this guide.

Prompt examples

Use case examples

Some examples of using reasoning models for real-world use cases can be found in the cookbook.

<a href="https://cookbook.openai.com/examples/o1/using_reasoning_for_data_validation" target="_blank" rel="noreferrer"

Evaluate a synthetic medical data set for discrepancies.

<a href="https://cookbook.openai.com/examples/o1/using_reasoning_for_routine_generation" target="_blank" rel="noreferrer"

Use help center articles to generate actions that an agent could perform.

guides/reasoning.md +201 −22

2 2

3**Reasoning models** like [GPT-5.5](https://developers.openai.com/api/docs/models/gpt-5.5) use internal reasoning tokens before producing a response. This helps the model plan, use tools effectively, inspect alternatives, recover from ambiguity, and solve harder multi-step tasks. Reasoning models work especially well for complex problem solving, coding, scientific reasoning, and multi-step agentic workflows. They're also the best models for [Codex CLI](https://github.com/openai/codex), our lightweight coding agent.3**Reasoning models** like [GPT-5.5](https://developers.openai.com/api/docs/models/gpt-5.5) use internal reasoning tokens before producing a response. This helps the model plan, use tools effectively, inspect alternatives, recover from ambiguity, and solve harder multi-step tasks. Reasoning models work especially well for complex problem solving, coding, scientific reasoning, and multi-step agentic workflows. They're also the best models for [Codex CLI](https://github.com/openai/codex), our lightweight coding agent.

4 4

5Start with `gpt-5.5` for most reasoning workloads. If you need the highest-intelligence API option for more challenging problems that can tolerate more latency, use [`gpt-5.5-pro`](https://developers.openai.com/api/docs/models/gpt-5.5-pro). For lower cost, consider `gpt-5.4` and for lower cost and latency, consider `gpt-5.4-mini`.5Start with `gpt-5.6` for most reasoning workloads. If you need the highest-intelligence API option for more challenging problems that can tolerate more latency, use [`gpt-5.5-pro`](https://developers.openai.com/api/docs/models/gpt-5.5-pro). For lower cost, consider `gpt-5.4` and for lower cost and latency, consider `gpt-5.4-mini`.

6 6

7**Reasoning models work better with the [Responses7**Reasoning models work better with the [Responses

8 API](https://developers.openai.com/api/docs/guides/migrate-to-responses)**. While the Chat Completions API8 API](https://developers.openai.com/api/docs/guides/migrate-to-responses)**. While the Chat Completions API

26`;26`;

27 27

28const response = await openai.responses.create({28const response = await openai.responses.create({

~~29 model: "gpt-5.5",~~29 model: "gpt-5.6",

30 reasoning: { effort: "low" },30 reasoning: { effort: "low" },

31 input: [31 input: [

32 {32 {

50"""50"""

51 51

52response = client.responses.create(52response = client.responses.create(

~~53 model="gpt-5.5",~~53 model="gpt-5.6",

54 reasoning={"effort": "low"},54 reasoning={"effort": "low"},

55 input=[55 input=[

56 {56 {

68 -H "Content-Type: application/json" \68 -H "Content-Type: application/json" \

69 -H "Authorization: Bearer $OPENAI_API_KEY" \69 -H "Authorization: Bearer $OPENAI_API_KEY" \

70 -d '{70 -d '{

~~71 "model": "gpt-5.5",~~71 "model": "gpt-5.6",

72 "reasoning": {"effort": "low"},72 "reasoning": {"effort": "low"},

73 "input": [73 "input": [

74 {74 {

88 88

89Defaults are also model-dependent rather than universal. `gpt-5.5` defaults to `medium` reasoning effort. This is the best starting point for `gpt-5.5`’s full balance of quality, reliability and performance.89Defaults are also model-dependent rather than universal. `gpt-5.5` defaults to `medium` reasoning effort. This is the best starting point for `gpt-5.5`’s full balance of quality, reliability and performance.

90 90

91| Effort | Best for... |91| Effort | Best for |

92| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |92| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

93| `none` | Latency-critical tasks that do not benefit from any reasoning or multi-chained tool calls. For latency-sensitive use cases with `gpt-5.5`, we recommend trying `low` to begin with and then moving to `none` if required. Common use cases include voice, fast information retrieval, and classification. |93| `none` | Latency-critical tasks that do not benefit from any reasoning or multi-chained tool calls. For latency-sensitive use cases with `gpt-5.5`, we recommend trying `low` to begin with and then moving to `none` if required. Common use cases include voice, fast information retrieval, and classification. |

94| `low` | Efficient reasoning with a modest latency increase. Ideal for use cases requiring tool-use, planning, search, or multi-step decision making, while optimizing for speed and cost. Common use cases include data analysis, drafting, execution-oriented coding, and customer support / chat assistant workflows. |94| `low` | Efficient reasoning with a modest latency increase. Ideal for use cases requiring tool-use, planning, search, or multi-step decision making, while optimizing for speed and cost. Common use cases include data analysis, drafting, execution-oriented coding, and customer support / chat assistant workflows. |

95| `medium` | When quality and reliability matter, and the task involves planning, complex reasoning, and judgement. Default configuration for most workloads, and a well-balanced point on the pareto curve of latency, performance and cost. Common use cases include agentic coding, research, working with spreadsheets & slides, and delegating long-horizon work. |95| `medium` | When quality and reliability matter, and the task involves planning, complex reasoning, and judgement. Default configuration for most workloads, and a well-balanced point on the pareto curve of latency, performance and cost. Common use cases include agentic coding, research, working with spreadsheets & slides, and delegating long-horizon work. |

96| `high` | Hard reasoning, complex debugging, deep planning, and high-value tasks where quality and intelligence matters more than latency. Recommended for complex workflows and agentic tasks. Common use cases include agentic coding, long-horizon research, and knowledge work. Depending on the complexity of the task, evaluate both `medium` and `high`. |96| `high` | Hard reasoning, complex debugging, deep planning, and high-value tasks where quality and intelligence matters more than latency. Recommended for complex workflows and agentic tasks. Common use cases include agentic coding, long-horizon research, and knowledge work. Depending on the complexity of the task, evaluate both `medium` and `high`. |

97| `xhigh` | Deep research, asynchronous workflows and agentic tasks that require very long rollouts. Only use when your evals show a clear benefit that justifies the extra latency and cost. Common use cases include security and code review, enterprise productivity, deeper research tasks, and challenging coding workflows. |97| `xhigh` | Deep research, asynchronous workflows and agentic tasks that require long runs. Only use when your evals show a clear benefit that justifies the extra latency and cost. Common use cases include security and code review, enterprise productivity, deeper research tasks, and challenging coding workflows. |

98 98

99For faster time to first visible token in latency-sensitive applications, ask the model to generate a short preamble before continuing with deeper reasoning.99For faster time to first visible token in latency-sensitive applications, ask the model to generate a short preamble before continuing with deeper reasoning.

100 100

101Some models support only a subset of these values, so check the relevant [model page](https://developers.openai.com/api/docs/models) before choosing a setting.101Some models support only a subset of these values, so check the relevant [model page](https://developers.openai.com/api/docs/models) before choosing a setting.

102 102

103## Reasoning mode

104

105GPT-5.6 models support `standard` and `pro` reasoning modes in the Responses API. `standard` is the default. Set `reasoning.mode` to `pro` for difficult tasks that need more model work and can tolerate higher latency and token usage.

106

107Reasoning mode and reasoning effort are independent. Mode selects standard or pro execution, while `reasoning.effort` controls how much reasoning the model applies within that mode. If you omit `reasoning.effort`, GPT-5.6 defaults to `medium` in both modes.

108

109Using pro reasoning mode

110

111```bash

112curl https://api.openai.com/v1/responses \

113 -H "Content-Type: application/json" \

114 -H "Authorization: Bearer $OPENAI_API_KEY" \

115 -d '{

116 "model": "gpt-5.6",

117 "reasoning": {

118 "mode": "pro",

119 "effort": "medium"

120 },

121 "input": "Review this database migration plan and identify potential failure modes."

122 }'

123```

124

125

126Pro mode aggregates the model work performed to produce the final answer and bills those tokens at the selected model's standard [token rates](https://developers.openai.com/api/docs/pricing). Pro mode performs more model work than standard mode, increasing token usage and cost. Existing Pro model IDs keep their current behavior and pricing.

127

103## How reasoning works128## How reasoning works

104 129

105Reasoning models introduce **reasoning tokens** in addition to input and output tokens. The models use these reasoning tokens to "think," breaking down the prompt and considering multiple approaches to generating a response. Our reasoning models like gpt-5.5 and gpt-5.4 support interleaved thinking, where the model is able to generate visible output tokens before and in between thinking, and is able to think in between tool calls.130Reasoning models introduce **reasoning tokens** in addition to input and output tokens. The models use these reasoning tokens to "think," breaking down the prompt and considering multiple approaches to generating a response. Our reasoning models like `gpt-5.5` and `gpt-5.4` support interleaved thinking, where the model is able to generate visible output tokens before and in between thinking, and is able to think in between tool calls.

106 131

107Here is an example of a multi-step conversation between a user and an assistant. Input and output tokens from each step are carried over, while reasoning tokens are discarded.132Here is the default behavior for a multi-step conversation between a user and an assistant. Input and output tokens from each step are carried over, while reasoning from earlier turns is not rendered into the next sample. Models that support persisted reasoning can change this behavior with `reasoning.context`.

108 133

109![Reasoning tokens aren't retained in context](https://cdn.openai.com/API/docs/images/context-window.png)134![Reasoning tokens with current-turn context](https://cdn.openai.com/API/docs/images/context-window.png)

110 135

111While reasoning tokens are not visible via the API, they still occupy space in136While reasoning tokens are not visible via the API, they still occupy space in

112 the model's context window and are billed as [output137 the model's context window and are billed as [output

161`;186`;

162 187

163const response = await openai.responses.create({188const response = await openai.responses.create({

164 model: "gpt-5.5",189 model: "gpt-5.6",

165 reasoning: { effort: "medium" },190 reasoning: { effort: "medium" },

166 input: [191 input: [

167 {192 {

196"""221"""

197 222

198response = client.responses.create(223response = client.responses.create(

199 model="gpt-5.5",224 model="gpt-5.6",

200 reasoning={"effort": "medium"},225 reasoning={"effort": "medium"},

201 input=[226 input=[

202 {227 {

226 251

227Check out [this guide](https://developers.openai.com/api/docs/guides/conversation-state) to learn more about manual context management.252Check out [this guide](https://developers.openai.com/api/docs/guides/conversation-state) to learn more about manual context management.

228 253

229### Encrypted reasoning items254## Preserve reasoning across calls

255

256Conversation state and reasoning state serve different purposes. Passing messages across calls gives the model the visible conversation history. On supported models, persisted reasoning also lets the model render compatible reasoning items from earlier turns into its next context.

257

258Persisted reasoning provides continuity; it does not expose the model's raw reasoning. The reasoning items remain opaque, and the API does not return their reasoning text. Set `reasoning.context` to control which available reasoning items the model can use:

259

260Support for <code>reasoning.context</code> modes is model-dependent. Replace

261 <code>YOUR_MODEL_ID</code> in the examples with a model that supports the mode

262 you select.

263

264| Value | Behavior |

265| -------------- | ------------------------------------------------------------------------------------------------------------------------------- |

266| `auto` | Uses the selected model's default. Omitting `reasoning.context` has the same effect as `auto`. |

267| `current_turn` | Makes reasoning from the active turn available, but does not render reasoning from earlier turns into the next sample. |

268| `all_turns` | Renders available, compatible reasoning items from earlier turns into the next sample. Only supported models accept this value. |

269

270The response's `reasoning.context` field contains the effective mode, either `current_turn` or `all_turns`. Check this field on each response to confirm which mode the model used. The setting does not create reasoning items that are not already available.

271

272`all_turns` has an effect only when the request has access to earlier response items. Use `previous_response_id`, attach the response to a conversation, or manually replay the complete response history. On the first request, `current_turn` and `all_turns` behave the same because no earlier reasoning exists.

273

274### Continue reasoning with stored responses

230 275

231When using the Responses API in a stateless mode (either with `store` set to `false`, or when an organization is enrolled in zero data retention), you must still retain reasoning items across conversation turns using the techniques described above. But in order to have reasoning items that can be sent with subsequent API requests, each of your API requests must have `reasoning.encrypted_content` in the `include` parameter of API requests, like so:276Use `previous_response_id` for the shortest stateful integration:

277

278Preserve reasoning with a previous response

279

280```javascript

281import OpenAI from "openai";

282

283const client = new OpenAI();

284

285const first = await client.responses.create({

286 model: "YOUR_MODEL_ID",

287 input: "Inspect this repository and identify the likely bug.",

288 reasoning: { context: "current_turn" },

289});

290

291const second = await client.responses.create({

292 model: "YOUR_MODEL_ID",

293 previous_response_id: first.id,

294 input: "Now patch the bug and explain the change.",

295 reasoning: { context: "all_turns" },

296});

297

298console.log(second.output_text);

299```

300

301```python

302from openai import OpenAI

303

304client = OpenAI()

305

306first = client.responses.create(

307 model="YOUR_MODEL_ID",

308 input="Inspect this repository and identify the likely bug.",

309 reasoning={"context": "current_turn"},

310)

311

312second = client.responses.create(

313 model="YOUR_MODEL_ID",

314 previous_response_id=first.id,

315 input="Now patch the bug and explain the change.",

316 reasoning={"context": "all_turns"},

317)

318

319print(second.output_text)

320```

321

322

323Use `current_turn` when replaying older response items that the model no longer needs. Those reasoning items can remain in the API payload for continuity, but the service does not render them into the new sample. This can reduce the rendered context for long-running workflows.

324

325### Preserve reasoning without stored responses

326

327When using the Responses API in a stateless mode, either with `store` set to `false` or for an organization enrolled in zero data retention, request `reasoning.encrypted_content` in the `include` parameter on every call:

232 328

233```bash329```bash

234curl https://api.openai.com/v1/responses \330curl https://api.openai.com/v1/responses \

235 -H "Content-Type: application/json" \331 -H "Content-Type: application/json" \

236 -H "Authorization: Bearer $OPENAI_API_KEY" \332 -H "Authorization: Bearer $OPENAI_API_KEY" \

237 -d '{333 -d '{

238 "model": "gpt-5.5",334 "model": "gpt-5.6",

239 "reasoning": {"effort": "medium"},335 "reasoning": {"effort": "medium"},

240 "input": "What is the weather like today?",336 "input": "What is the weather like today?",

241 "tools": [ ... function config here ... ],337 "tools": [ ... function config here ... ],

244```340```

245 341

246 342

247Any reasoning items in the `output` array will now have an `encrypted_content` property, which will contain encrypted reasoning tokens that can be passed along with future conversation turns.343Reasoning items in the `output` array will include an `encrypted_content` property containing encrypted reasoning tokens that you can pass to future calls.

344

345To use `all_turns` with `store: false`, request encrypted reasoning content on every call, preserve every output item, append the next user message, and replay the complete history:

346

347Preserve reasoning without storing responses

348

349```javascript

350import OpenAI from "openai";

351

352const client = new OpenAI();

353

354const history = [

355 {

356 role: "user",

357 content: "Inspect this repository and identify the likely bug.",

358 },

359];

360

361const first = await client.responses.create({

362 model: "YOUR_MODEL_ID",

363 store: false,

364 input: history,

365 include: ["reasoning.encrypted_content"],

366 reasoning: { context: "current_turn" },

367});

368

369// Keep every output item, including encrypted reasoning and assistant phase.

370history.push(...first.output);

371history.push({

372 role: "user",

373 content: "Now patch the bug and explain the change.",

374});

375

376const second = await client.responses.create({

377 model: "YOUR_MODEL_ID",

378 store: false,

379 input: history,

380 include: ["reasoning.encrypted_content"],

381 reasoning: { context: "all_turns" },

382});

383

384console.log(second.output_text);

385```

386

387```python

388from openai import OpenAI

389

390client = OpenAI()

391

392history = [

393 {

394 "role": "user",

395 "content": "Inspect this repository and identify the likely bug.",

396 }

397]

398

399first = client.responses.create(

400 model="YOUR_MODEL_ID",

401 store=False,

402 input=history,

403 include=["reasoning.encrypted_content"],

404 reasoning={"context": "current_turn"},

405)

406

407# Keep every output item, including encrypted reasoning and assistant phase.

408history.extend(item.model_dump() for item in first.output)

409history.append(

410 {

411 "role": "user",

412 "content": "Now patch the bug and explain the change.",

413 }

414)

415

416second = client.responses.create(

417 model="YOUR_MODEL_ID",

418 store=False,

419 input=history,

420 include=["reasoning.encrypted_content"],

421 reasoning={"context": "all_turns"},

422)

423

424print(second.output_text)

425```

426

248 427

249## Reasoning summaries428## Reasoning summaries

250 429

263const openai = new OpenAI();442const openai = new OpenAI();

264 443

265const response = await openai.responses.create({444const response = await openai.responses.create({

266 model: "gpt-5.5",445 model: "gpt-5.6",

267 input: "What is the capital of France?",446 input: "What is the capital of France?",

268 reasoning: {447 reasoning: {

269 effort: "low",448 effort: "low",

279client = OpenAI()458client = OpenAI()

280 459

281response = client.responses.create(460response = client.responses.create(

282 model="gpt-5.5",461 model="gpt-5.6",

283 input="What is the capital of France?",462 input="What is the capital of France?",

284 reasoning={463 reasoning={

285 "effort": "low",464 "effort": "low",

295 -H "Content-Type: application/json" \474 -H "Content-Type: application/json" \

296 -H "Authorization: Bearer $OPENAI_API_KEY" \475 -H "Authorization: Bearer $OPENAI_API_KEY" \

297 -d '{476 -d '{

298 "model": "gpt-5.5",477 "model": "gpt-5.6",

299 "input": "What is the capital of France?",478 "input": "What is the capital of France?",

300 "reasoning": {479 "reasoning": {

301 "effort": "low",480 "effort": "low",

347For long-running or tool-heavy flows with GPT-5.5 and GPT-5.4 in the Responses API, use the assistant message `phase` field to avoid early stopping and other misbehavior.526For long-running or tool-heavy flows with GPT-5.5 and GPT-5.4 in the Responses API, use the assistant message `phase` field to avoid early stopping and other misbehavior.

348`phase` is optional at the API level, but OpenAI recommends using it. Use `phase: "commentary"` for intermediate assistant updates, such as preambles before tool calls, and `phase: "final_answer"` for the completed answer. Don't add `phase` to user messages.527`phase` is optional at the API level, but OpenAI recommends using it. Use `phase: "commentary"` for intermediate assistant updates, such as preambles before tool calls, and `phase: "final_answer"` for the completed answer. Don't add `phase` to user messages.

349Using `previous_response_id` is usually the simplest path because prior assistant state is preserved. If you replay assistant history manually, preserve each original `phase` value.528Using `previous_response_id` is usually the simplest path because prior assistant state is preserved. If you replay assistant history manually, preserve each original `phase` value.

350Missing or dropped `phase` can cause preambles to be treated as final answers in those workflows. For model-specific prompt guidance, see [Prompting GPT-5.5](https://developers.openai.com/api/docs/guides/prompt-guidance?model=gpt-5.5#phase-parameter).529Missing or dropped `phase` can cause preambles to be treated as final answers in those workflows. For model-specific prompt guidance, see [Prompting GPT-5.5](https://developers.openai.com/api/docs/guides/latest-model?model=gpt-5.5#prompting-best-practices).

351 530

352### Round-trip assistant phase values531### Round-trip assistant phase values

353 532

358const client = new OpenAI();537const client = new OpenAI();

359 538

360const response = await client.responses.create({539const response = await client.responses.create({

361 model: "gpt-5.5",540 model: "gpt-5.6",

362 input: [541 input: [

363 {542 {

364 role: "assistant",543 role: "assistant",

387client = OpenAI()566client = OpenAI()

388 567

389response = client.responses.create(568response = client.responses.create(

390 model="gpt-5.5",569 model="gpt-5.6",

391 input=[570 input=[

392 {571 {

393 "role": "assistant",572 "role": "assistant",

412 591

413## Advice on prompting592## Advice on prompting

414 593

415There are some differences to consider when prompting a reasoning model. Reasoning-capable GPT-5 models usually work best when you give them a clear goal, strong constraints, and an explicit output contract without prescribing every intermediate step.594Consider these differences when prompting a reasoning model. Reasoning-capable GPT-5 models usually work best when you give them a clear goal, strong constraints, and an explicit output contract without prescribing every intermediate step.

416 595

417- Give the model the task, constraints, and desired output format.596- Give the model the task, constraints, and desired output format.

418- Treat `reasoning.effort` as a tuning knob, not the primary way to recover quality.597- Treat `reasoning.effort` as a tuning knob, not the primary way to recover quality.