Search the API docs Conversation state Background mode Counting tokens Supported countries OpenAI Crawlers Terms and policies Agent Builder Overview Migration guide Node reference Safety in building agents Migration guide Safety in building agents Evals Getting started Working with evals Prompt optimizer External models Best practices Graders Getting started Working with evals Prompt optimizer External models Fine-tuning Optimization cycle Supervised fine-tuning Vision fine-tuning Direct preference optimization Reinforcement fine-tuning RFT use cases Best practices Optimization cycle Supervised fine-tuning Vision fine-tuning Direct preference optimization Reinforcement fine-tuning Assistants API Migration guide Migration guide Model selection Text generation Code generation Structured output Prompt engineering Citation formatting Migration guide Prompt generation Frontend prompting Reasoning models Reasoning best practices Images and video Images and vision Image input cost calculator Image input cost calculator Image generation Video generation Realtime and audio Audio and speech Specialized models Agent definitions Models and providers Results and state Integrations and observability Evaluate agent workflows Advanced integrations Function calling Search and retrieval Connect tools and data MCP and Connectors Secure MCP Tunnel Build tool workflows Programmatic tool calling Computer and code Code interpreter Image generation Live translation Realtime prompting guide Audio and speech File transcription Realtime transcription Speech generation Connection methods Sessions and operations Managing conversations Voice activity detection Realtime with tools Webhooks and server-side controls Production best practices Deployment checklist Performance and quality Latency optimization Predicted Outputs Accuracy optimization Cost and throughput Cost optimization Flex processing Safety and governance Safety best practices Safety checks Cybersecurity checks Under 18 API Guidance Cybersecurity checks Under 18 API Guidance Content provenance Infrastructure and access Terraform provider Overview Projects and access Service accounts Rate limits and spend Model, tool, and data controls Import and reconciliation Projects and access Service accounts Rate limits and spend Model, tool, and data controls Import and reconciliation Workload identity federation Codex setup Federation rules Admin API X.509 certificates Kubernetes AWS Microsoft Azure Google Cloud Oracle Cloud Infrastructure GitHub Actions SPIFFE Federation rules X.509 certificates Microsoft Azure Oracle Cloud Infrastructure IP egress ranges Plugin architecture Brainstorm use cases Build an MCP server Add UI to your MCP server (optional) Authenticate users Package your plugin Test and publish Connect and test your plugin Submit and publish Submission error reference Conversion specs Restaurant reservation spec Product checkout spec Optimize Metadata Submit a Claude Code plugin Security & Privacy Troubleshooting Plugin guidelines MCP server review requirements Plugin UI reference Checkout API reference Trigger workspace agent runs Authenticate with Workspace Agent access tokens Measurement Pixel Multiple Pixels (Advanced) Conversions API Supported Events API Partner Setup Delta Feeds API Campaign Targeting Conversion-Optimized Campaigns Custom Audiences Conversion Setup Get started with Work Import from another agent Personalize ChatGPT Skills & Plugins ChatGPT desktop app ChatGPT on the web Codex IDE extension Feature Maturity Projects and chats Scheduled tasks Long-running work Image generation Browser extension Work with files Troubleshooting Computer History Advanced Config Config Reference Environment Variables Agent configuration Extend ChatGPT and Codex Record & Replay Windows sandbox Development workflows

Integrated terminal Extend and automate Site tools (WebMCP) Local environments Cloud environment Build with Codex Non-interactive mode Third-party integrations CLI customization Developer commands Developer settings Agent approvals & security Internet access Codex Security plugin Quickstart Run a security scan Run a deep scan Review code changes Use the Security workbench Triage a backlog Fix findings Propose security hardening Write vulnerability reports Export and track findings Changelog Run a security scan Run a deep scan Review code changes Use the Security workbench Triage a backlog Propose security hardening Write vulnerability reports Export and track findings Codex Security CLI Quickstart Run bulk scans Run scans in CI GitLab CI/CD Reference FAQ Run scans in CI Codex Security cloud Setup Security Review Improving the threat model FAQ Security Review Improving the threat model Models & Trusted Access Recommended configuration Getting started Admin rollout guide ChatGPT Work Overview ChatGPT Work cloud security ChatGPT Work local security ChatGPT Work admin FAQ ChatGPT Work: usage and cost Identity and authentication Authentication overview Workload identity Personal Access Tokens Service accounts Workspace access, policy, and models Groups and provisioning User lifecycle management Roles and workspace permissions GPTs and Sharing Managed configuration HIPAA configuration Workspace model availability Plugin and connector controls Plugin controls Plugin management Usage, governance, and compliance Workspace analytics Compliance API and audit events Deployment and model providers Manage app updates Windows app deployment Remote connections Explore use cases Online trainings Codex Ambassadors Codex for Students Codex for Open Source Explore use cases Online trainings Codex Ambassadors Codex for Students Codex for Open Source Meet Rosalind Workbench: Empowering every scientist to be their own research team Automating repetitive work at OpenAI with Codex Meet the winners of OpenAI Build Week Scaling cyber defenders with Daybreak Codex as a platform: build on the open agent harness Cookbook on GitHub OpenAI Developers plugin Image generation Video generation Codex Ambassadors Codex for Students Codex for Open Source OpenAI for Startups Developer Forum 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.6-sol in the Responses API with reasoning.mode set to pro . For lower cost, consider gpt-5.6-terra , or gpt-5.6-luna for the lowest cost and latency. 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: 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 , xhigh , and max . 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. 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. 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. 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. For models released before GPT-5.6, the default behavior in a multi-step conversation is to carry over input and output tokens from each step without rendering reasoning from earlier turns into the next sample. GPT-5.6 models instead default to rendering available reasoning from earlier turns. Use reasoning.context to select either behavior on supported models. 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 : 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. 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: The GPT-5.6 model family supports all_turns and uses it by default. Earlier models default to current_turn . Omit reasoning.context or set it to auto to use the selected model’s default. 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. Persisted reasoning can be reused only within the same model family. For example, gpt-5.6-sol , gpt-5.6-terra , and gpt-5.6-luna can reuse each other’s reasoning, but reasoning does not carry between the GPT-5.6 and GPT-5.5 families. When you switch model families, the API omits incompatible reasoning from the model’s context, even when reasoning.context is all_turns . Continue reasoning with stored responses Use previous_response_id for the shortest stateful integration: 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 you create a response in stateless mode, reasoning items in the response’s output array include an encrypted_content property by default. Stateless mode applies when store is false or when your organization uses Zero Data Retention (ZDR). The API still accepts the legacy reasoning.encrypted_content value in include for compatibility, but doesn’t require it. The following request returns encrypted reasoning content without specifying include : 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 , preserve every output item, append the next user message, and replay the complete history: 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. 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. 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 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 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. OpenAI o-series models are also adept in creating multi-step plans. This example prompt asks o1 to create a filesystem structure for a full solution, along with Python code that implements the desired use case. OpenAI o-series models have shown excellent performance in STEM research. Prompts asking for support of basic research tasks should show strong results. Use case examples Some examples of using reasoning models for real-world use cases can be found in the cookbook . Evaluate a synthetic medical data set for discrepancies. Use help center articles to generate actions that an agent could perform. Loading docs agent...