OpenAI Responses API

The OpenAI Responses API is OpenAI's agent-oriented HTTP API, launched on March 11, 2025, that unifies the simplicity of the Chat Completions API with the stateful, tool-using capabilities of the older Assistants API. A single endpoint, POST /v1/responses, returns a stored response object that can carry text, images, function calls, and the results of OpenAI-hosted tools, including built-in web search, file search, and computer use. It gives developers access to the building blocks behind OpenAI's own agent products such as Operator and Deep Research, and it is now the company's recommended path for new agentic projects, with the Assistants API deprecated on August 26, 2025 and shut down on August 26, 2026.^{[1][3][4][15][17]}

OpenAI expanded the API on May 21, 2025 with remote MCP support, native image generation, code interpreter, background mode, and encrypted reasoning items. Together with the OpenAI Agents SDK released the same day in March, the Responses API and the related Conversations API form the long-term replacement for OpenAI's previously fragmented agent stack.^[1][2][4]

What is the Responses API?

The Responses API is OpenAI's attempt to fold the simplicity of the Chat Completions API together with the agentic capabilities that previously lived in the Assistants stack. A single request can call multiple built-in tools, preserve reasoning state across turns, and return polymorphic output items in the order they happened. Where Chat Completions returns one message, Responses returns a list of typed items, including message, reasoning, function_call, web_search_call, file_search_call, code_interpreter_call, and image_generation_call entries that document each step the model took.^[5][3]

Responses are stored by default. Every call returns a response.id that the caller can pass into the next request as previous_response_id, which lets OpenAI manage conversation history server-side rather than forcing the client to resend the full transcript on every turn. A separate Conversations API (added in August 2025) extends this with a long-running Conversation object that holds messages, tool calls, and tool outputs across sessions. The combination gives developers a stateful interface that does not depend on client-side history management.^[5][6]

When was the Responses API released?

OpenAI announced the Responses API on March 11, 2025, together with the open-source OpenAI Agents SDK and a set of hosted tools aimed at agent builders. At launch the API supported three built-in tools: web search, file search, and computer use. Coverage framed the release as giving developers access to the building blocks behind OpenAI's own Operator and Deep Research agents, without forcing them to wire those tools together by hand.^[1][7]

Olivier Godement, OpenAI's head of product for the API, framed the launch around the gap between agent demos and products: "It's pretty easy to demo your agent. To scale an agent is pretty hard, and to get people to use it often is very hard." The Responses API was meant to lower the engineering cost of getting from prototype to production by handling the orchestration loop on the server.^[8]

The built-in web search tool reused the model behind ChatGPT search and was available in Responses with gpt-4o and gpt-4o-mini; the fine-tuned gpt-4o-search-preview and gpt-4o-mini-search-preview models were offered separately in Chat Completions. OpenAI reported that these search-tuned variants reached 90% and 88% accuracy on the SimpleQA factuality benchmark, compared with 63% for GPT-4.5. The computer use tool was powered by a new computer-use-preview model, the same Computer-Using Agent that powered OpenAI's Operator product. OpenAI noted that computer use was still a research preview, gated to usage tiers 3 through 5, and acknowledged that it was "not yet highly reliable for automating tasks on operating systems." The model scored 38.1% on the OSWorld benchmark at release.^[1][7][8]

What did the May 2025 expansion add?

On May 21, 2025 OpenAI shipped a major update that added remote MCP server support, native image generation, code interpreter, file search upgrades, background mode, reasoning summaries, and encrypted reasoning items.^[2]

The May update also unlocked tool use inside the chain of thought for OpenAI o3 and OpenAI o4-mini. Earlier reasoning models could call tools only after finishing their reasoning step. With the Responses API, o3 and o4-mini can interleave tool calls with their internal thinking, which OpenAI claimed produced better results on tasks where the model needs intermediate evidence to reason well.^[2]

What does a Responses API request look like?

A Responses request is sent as POST /v1/responses. The minimum payload is a model and an input. The input field accepts either a plain string or a list of typed content items including input_text, input_image, input_file, and input_audio. The response object contains id, output (the list of items the model produced), output_text (a convenience accessor), usage, and metadata about any tools that were invoked.^[5]

A basic Python example using the official SDK looks like this:

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5",
    input="Summarize the latest news about the Mars Sample Return mission.",
    tools=[{"type": "web_search"}],
)

print(response.output_text)

The equivalent JavaScript call uses the same shape:

import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-5",
  input: "Summarize the latest news about the Mars Sample Return mission.",
  tools: [{ type: "web_search" }],
});

console.log(response.output_text);

A conversation can be continued by passing the prior response id:

follow_up = client.responses.create(
    model="gpt-5",
    input="What are the funding risks for the mission?",
    previous_response_id=response.id,
)

The API also supports server-sent events streaming. When stream=true is set the server emits semantic events such as response.output_text.delta, response.function_call_arguments.delta, and response.completed, which are richer than the raw token deltas emitted by Chat Completions.^[5]

What built-in tools does the Responses API have?

One of the main reasons developers choose the Responses API over Chat Completions is the set of OpenAI-hosted tools that run server-side, so the model can invoke them inside a single request without round-tripping through the developer's backend.

The hosted tools can be combined freely. A model can run a web search, feed the result into code interpreter, then call a custom function the developer defined, and finally write a response. OpenAI's migration guide describes this as "an agentic loop by default."^[3]

Which models does the Responses API support?

The Responses API supports OpenAI's flagship text and reasoning models. The table below reflects the lineup as of mid-2026; by November 2026 OpenAI's current flagships were the GPT-6 family (GPT-6 Astra, GPT-6.1 Sol, GPT-6.1 Terra, GPT-6 Luna), and several older models listed here had been shut down or scheduled for shutdown.^[17] Reasoning models pick up extra benefits because the API preserves their chain of thought across turns.^[2][9]

OpenAI states that GPT-5 specifically benefits from Responses because the API preserves hidden reasoning tokens across calls. OpenAI has reported that GPT-5's Tau-Bench Retail score rose from 73.9% to 78.2% just by switching from Chat Completions to Responses and passing back previous reasoning items with previous_response_id.^[18]

How does the Responses API manage state and conversations?

With previous_response_id, OpenAI prepends the prior input and output items, including reasoning items from o-series models, before generating the next response. This is the recommended pattern for reasoning models because it preserves the chain of thought without the client having to handle it.^[6][10]

The Conversations API is the alternative for longer-running threads. A conversation is a named container of items, and a Responses request can take a conversation id instead of (or in addition to) previous_response_id. New input and output items are appended to the conversation automatically.^[5]

For sensitive deployments, OpenAI added encrypted reasoning items in May 2025. Reasoning content can be returned in encrypted form, stored on the client, and replayed on the next request without OpenAI ever retaining the plaintext. This is what lets organizations on Zero Data Retention contracts still benefit from reasoning continuity.^[2]

Background mode (also added in May 2025) is for long-running agent runs. The client sets background=true, gets a response id immediately, and can poll the response or cancel it. This is the recommended approach for deep research workflows or long computer-use sessions, because a single response can take minutes to produce and a regular HTTP request would time out.^[2]

How do structured outputs and function calling work?

The Responses API supports structured outputs through the text.format parameter (Chat Completions uses response_format instead). By passing a JSON Schema with strict: true, the developer guarantees that the response conforms to the schema; the model is constrained at decoding time so the JSON cannot be malformed. Structured outputs work with both regular chat models and reasoning models, and they also constrain the arguments emitted for function tools.^[5]

Function calling itself is unchanged in spirit from Chat Completions: declare functions as tools, get back arguments, run the function, post the result. The wire format uses typed items rather than a tool_calls list, which makes mixed sequences of model text, function calls, web searches, and code execution easier to reason about as a single output stream.^[5][10]

How much does the Responses API cost?

Responses API requests are billed at the standard per-token price for whichever model is invoked, plus separate per-call fees for hosted tools. OpenAI's launch posts and pricing page itemize the tool charges; the table shows the launch-era prices.^[1][2][11]

Reasoning tokens generated by o-series and GPT-5 thinking models count as output tokens, so a single Responses call against a reasoning model can consume far more output tokens than the visible reply suggests. Web search billing can also run higher than the call count suggests: most web search variants bill search content tokens at model rates on top of the per-call fee,^[11] and a single tool invocation can trigger several internal sub-searches, each billed as a separate call, which has caught some developers off guard.^[12]

How does Responses differ from Chat Completions and Assistants?

OpenAI now runs three primary text-generation APIs. Responses is the recommended path for new projects, Chat Completions remains supported, and Assistants was shut down on August 26, 2026.^[3][15]

OpenAI's official guidance is that Chat Completions is still the right choice for simple text generation and for code that needs to remain portable across providers, since the Chat Completions schema is implemented by Anthropic-compatible endpoints, Azure, and most open-source inference servers. Responses is the right choice when an application needs hosted tools, reasoning preservation, server-managed conversation state, or the ability to combine multiple tools in a single agentic loop. The Realtime API is a separate surface for low-latency voice and live multimodal sessions over WebSocket and is not replaced by Responses.^[3][6]

How does it compare with peer agent APIs?

Responses is OpenAI's answer to a wave of agent-oriented APIs that other model providers have shipped over the same period.^[13][14]

The Responses API and the Anthropic Messages API are the closest competitors. Both expose computer use, web search, and MCP as first-class tools, and both ship official SDKs for Python and Node. The practical differences have narrowed: both APIs now return summarized rather than raw reasoning (Anthropic's thinking blocks contain a summary of Claude's reasoning),^[19] and while Anthropic has long exposed prompt caching as a developer-controlled feature, OpenAI's caching was implicit until GPT-5.6 added explicit cache control alongside automatic caching.^[6] Anthropic's API also keeps system prompts in a separate system field rather than embedding them in the message array.^[13][14]

How do you migrate from Chat Completions and Assistants?

Migrating from Chat Completions is mostly a matter of renaming messages to input and accepting a different output shape. A Chat Completions message list translates almost directly: each message becomes an input item with the same role and content. The biggest change for callers is reading response.output_text instead of the Chat Completions accessor response.choices[0].message.content, and looking through response.output to handle tool calls, since tool calls are a separate item type rather than a field on a message.^[3]

Migrating from Assistants is more involved because Assistants used persistent Assistant, Thread, Message, and Run objects, while Responses replaces them with Response and Conversation objects plus reusable Prompts (themselves deprecated in June 2026, with the prompts API scheduled to shut down on November 30, 2026).^[17] OpenAI published a side-by-side migration guide that maps each Assistants concept to its Responses equivalent: Threads become Conversations, Assistants become Prompts (versioned in the dashboard rather than created via the API), and Runs collapse into a single responses.create call that may invoke many tools. Vector stores carry over directly because both APIs use the same vector store backend for file search.^[3][15]

When is the Assistants API being deprecated?

OpenAI announced the Assistants API beta deprecation on August 26, 2025 with a sunset date of August 26, 2026, giving developers a full year to migrate. The sunset took effect on August 26, 2026: OpenAI's migration guide now states that the Assistants API "is no longer available," and calls such as retrieving thread messages no longer work. Remaining integrations have to be rebuilt on the Responses and Conversations APIs.^[15] OpenAI explicitly framed the move as the result of Responses reaching parity with everything Assistants offered, including code interpreter and persistent conversation state, plus new capabilities such as remote MCP, computer use, and reasoning preservation that Assistants never supported.^[15][4]

How does the Responses API relate to the Agents SDK?

The OpenAI Agents SDK is OpenAI's open-source orchestration framework for multi-agent workflows. It launched on March 11, 2025 alongside the Responses API as a Python library, with a JavaScript/TypeScript version following later. The SDK is built on top of Responses and uses the API's native tool-call loop as its execution primitive. An Agent in the SDK is a thin wrapper around a Responses call with a system instruction, a list of tools, and optional handoffs to other agents.^[1][7]

A minimal Agents SDK script in Python looks like this:

from agents import Agent, Runner, WebSearchTool

researcher = Agent(
    name="Researcher",
    instructions="Use web search to gather facts.",
    tools=[WebSearchTool()],
)

result = Runner.run_sync(researcher, "Latest funding rounds in robotics startups.")
print(result.final_output)

The SDK handles the tool-call loop, retries, tracing, and handoffs between agents. Because it sits on top of Responses, anything the SDK can do is also possible with raw Responses calls if a developer wants finer control.

What are the limitations of the Responses API?

The Responses API has matured quickly but still has gaps developers should plan around. Computer use is gated to higher usage tiers and remains a research preview, with OpenAI itself noting it is not yet reliable for general OS automation. Some hosted tools, including image generation and code interpreter, are not yet available in every Azure region; Microsoft's Azure OpenAI service rolled them out behind a separate availability matrix. The hosted tools are tightly coupled to OpenAI's ecosystem, so an application that relies heavily on the built-in web search or file search cannot easily swap to another model provider without rewriting that orchestration. The Responses schema is more expressive than Chat Completions, but that same expressiveness has slowed adoption by third-party libraries that originally targeted the Chat Completions shape.^[7][8][13]

OpenAI has also been criticized for the way Responses handles reasoning. The API does not return raw chain-of-thought text by default. Instead it returns a summary or, for Zero Data Retention customers, an encrypted blob that can be passed back in subsequent calls. Blogger Sean Goedecke has argued that the stateful design exists largely to let OpenAI keep its reasoning traces secret, presumably for safety reasons or to avoid leaking implementation details to other labs.^[16] Anthropic's API also returns only summarized reasoning for recent Claude models, though it can be used with a stateless, completions-style interface.^[19]

How was the Responses API received?

Reception of the Responses API has been broadly positive among developers building agents. TechCrunch and VentureBeat covered the launch as OpenAI opening up the building blocks behind its own agents, with the Agents SDK and computer use rounding out the picture. The May 2025 update was widely covered as the moment when Responses reached real feature parity with Assistants, and the August 2025 deprecation announcement confirmed Responses as the long-term direction.^{[7][8][4][14]}

Criticism has clustered around three themes. First, the cost of hosted tools, especially the $25 per 1,000 web search calls on preview models, prompted developers to compare Responses unfavorably with rolling their own retrieval pipelines. Second, the lack of cross-provider portability, since Responses is OpenAI-only while Chat Completions has near-universal third-party support. Third, the secrecy around reasoning tokens, which makes it harder for outside researchers to audit how the models behave during agentic loops.^[11][13][16]

References

1. ^1 ^2 ^3 ^4 ^5 ^6OpenAI. "New tools for building agents." March 11, 2025. openai.com/...new-tools-for-building-agents
2. ^1 ^2 ^3 ^4 ^5 ^6 ^7OpenAI. "New tools and features in the Responses API." May 21, 2025. openai.com/...ls-and-features-in-the-responses-api
3. ^1 ^2 ^3 ^4 ^5 ^6 ^7OpenAI. "Migrate to the Responses API." OpenAI Platform Docs. platform.openai.com/...migrate-to-responses
4. ^1 ^2 ^3 ^4OpenAI Developer Community. "Assistants API beta deprecation, August 26, 2026 sunset." August 26, 2025. community.openai.com/...1354666
5. ^1 ^2 ^3 ^4 ^5 ^6 ^7OpenAI. "Responses API Reference." OpenAI Platform Docs. platform.openai.com/...responses
6. ^1 ^2 ^3 ^4OpenAI Developers. "Using GPT-5.5." developers.openai.com/...latest-model
7. ^1 ^2 ^3 ^4 ^5VentureBeat. "OpenAI unveils Responses API, open source Agents SDK, letting developers build their own Deep Research and Operator." March 11, 2025. venturebeat.com/...-own-deep-research-and-operator
8. ^1 ^2 ^3 ^4TechCrunch. "OpenAI launches new tools to help businesses build AI agents." March 11, 2025. techcrunch.com/...-help-businesses-build-ai-agents
9. ^OpenAI. "Models." OpenAI Platform Docs. platform.openai.com/...models
10. ^1 ^2OpenAI Cookbook. "Better performance from reasoning models using the Responses API." developers.openai.com/...reasoning_items
11. ^1 ^2 ^3OpenAI. "API Pricing." OpenAI. openai.com/...pricing
12. ^OpenAI Developer Community. "Heads up: Web Search Tool Billing Can Be Higher Than You Expect." 2025. community.openai.com/...1236954
13. ^1 ^2 ^3 ^4Portkey. "OpenAI Responses API vs Chat Completions vs Anthropic Messages API." 2025. portkey.ai/...-vs-anthropic-anthropic-messages-api
14. ^1 ^2 ^3VentureBeat. "OpenAI updates its new Responses API rapidly with MCP support, GPT-4o native image gen, and more enterprise features." May 21, 2025. venturebeat.com/...en-and-more-enterprise-features
15. ^1 ^2 ^3 ^4 ^5OpenAI. "Assistants API migration guide." OpenAI Platform Docs. platform.openai.com/...migration
16. ^1 ^2Goedecke, Sean. "The whole point of OpenAI's Responses API is to help them hide reasoning traces." 2025. seangoedecke.com/responses-api
17. ^1 ^2 ^3OpenAI. "Deprecations." OpenAI API Docs. developers.openai.com/...deprecations
18. ^OpenAI Cookbook. "GPT-5 prompting guide." developers.openai.com/...gpt-5_prompting_guide
19. ^1 ^2Anthropic. "Thinking." Claude API Docs. docs.claude.com/...thinking