OpenAI's API can now keep reasoning across turns instead of discarding it OpenAI updated its API to allow reasoning models like GPT-5.5 and GPT-5.6 to retain reasoning context across conversation turns, improving performance on complex multi-step tasks. The new feature, available via the Responses API, supports adjustable reasoning effort levels from none to xhigh, enabling developers to balance speed and quality. ··· 1 unchanged block 1 paragraph — click to show 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. Start with gpt-5.6 ~~Start with ~~ 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 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 . ··· 3 unchanged blocks Get started with reasoning — click to show 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 https://developers.openai.com/api/docs/api-reference/responses/create and specify your reasoning model and reasoning effort: python 1 2 3 4 5 6 7 8 9 10 - 11 12 13 14 15 16 17 18 19 20 21 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.5", model="gpt-5.6", reasoning={"effort": "low"}, input= { "role": "user", "content": prompt } print response.output text ··· 4 unchanged blocks Reasoning effort — click to show 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. Common use cases include security and code review, enterprise productivity, deeper research tasks, and challenging coding workflows. | ··· 2 unchanged blocks 2 paragraphs — click to show 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 https://developers.openai.com/api/docs/models 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. 1 2 3 4 5 6 7 8 9 10 11 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 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. ··· 2 unchanged blocks How reasoning works — click to show 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 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. 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 . ··· 11 unchanged blocks Managing the context window, Controlling costs, Allocating space for reasoning — click to show 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 https://openai.com/api/pricing . 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 https://developers.openai.com/api/docs/api-reference/responses/object , under output tokens details : 1 2 3 4 5 6 7 8 9 10 11 12 13 { "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 https://developers.openai.com/api/docs/models , 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 https://developers.openai.com/api/docs/api-reference/responses/create responses-create-max output tokens parameter. See output token counts https://developers.openai.com/api/docs/guides/token-counting understand-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. 1 2 3 4 5 6 7 8 9 10 - 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 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.5", 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" ··· 5 unchanged blocks Keeping reasoning items in context — click to show Keeping reasoning items in context When doing function calling https://developers.openai.com/api/docs/guides/function-calling with a reasoning model in the Responses API https://developers.openai.com/api/docs/api-reference/responses , 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 https://developers.openai.com/api/docs/api-reference/responses/object responses/object-output items from a past response into the input https://developers.openai.com/api/docs/api-reference/responses/create responses-create-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 https://developers.openai.com/api/docs/guides/conversation-state 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 ~~Encrypted reasoning items~~ When 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: Use previous response id for the shortest stateful integration: python 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 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: 1 2 3 4 - 5 6 7 8 9 10 curl https://api.openai.com/v1/responses \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $OPENAI API KEY" \ -d '{ "model": "gpt-5.5", "model": "gpt-5.6", "reasoning": {"effort": "medium"}, "input": "What is the weather like today?", "tools": ... function config here ... , "include": "reasoning.encrypted content" }' Reasoning ~~Any reasoning~~ items in the output array will include an encrypted content property containing ~~now have an ~~ encrypted reasoning tokens that you can pass to future calls. encrypted content property, which will contain~~can be passed along with future conversation turns.~~ 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: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 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 ··· 5 unchanged blocks Reasoning summaries — click to show 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 https://developers.openai.com/api/docs/models 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 https://developers.openai.com/api/docs/api-reference/responses/object responses/object-output . 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. python 1 2 3 4 - 5 6 7 8 9 10 11 12 13 from openai import OpenAI client = OpenAI response = client.responses.create model="gpt-5.5", model="gpt-5.6", input="What is the capital of France?", reasoning={ "effort": "low", "summary": "auto" } print response.output ··· 6 unchanged blocks phase parameter, Round-trip assistant phase values — click to show 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. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 { "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 https://help.openai.com/en/articles/10910291-api-organization-verification to ensure safe deployment. Get started with verification on the platform settings page https://platform.openai.com/settings/organization/general . 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 https://developers.openai.com/api/docs/guides/latest-model?model=gpt-5.5 prompting-best-practices . Round-trip assistant phase values 1 2 3 4 5 - 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 from openai import OpenAI client = OpenAI response = client.responses.create model="gpt-5.5", 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 ··· 1 unchanged block Advice on prompting — click to show Advice on prompting Consider these differences ~~There 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. ··· 8 unchanged blocks Prompt examples, Use case examples — click to show - 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 https://developers.openai.com/api/docs/guides/reasoning-best-practices . Prompt examples OpenAI o-series models are able to implement complex algorithms and produce code. This prompt asks o1 to refactor a React component based on some specific criteria. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 import OpenAI from "openai"; const openai = new OpenAI ; const prompt = Instructions: - Given the React component below, change it so that nonfiction books have red text. - Return only the code in your reply - Do not include any additional formatting, such as markdown code blocks - For formatting, use four space tabs, and do not allow any lines of code to exceed 80 columns const books = { title: 'Dune', category: 'fiction', id: 1 }, { title: 'Frankenstein', category: 'fiction', id: 2 }, { title: 'Moneyball', category: 'nonfiction', id: 3 }, ; export default function BookList { const listItems = books.map book =