Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/openai/openai-cookbook/llms.txt

Use this file to discover all available pages before exploring further.

The Responses API is OpenAI’s next-generation interface for building advanced AI applications. Unlike the Chat Completions API — which requires you to manually track and resend conversation history on every request — the Responses API is stateful by default, manages context on your behalf, and ships with powerful hosted tools that the model can invoke autonomously. Whether you’re building a multi-turn assistant, an agentic workflow, or a reasoning-heavy pipeline, the Responses API gives you a unified, flexible foundation.

​
Responses API vs Chat Completions

The Chat Completions API is text-in, text-out: you send the full message history on every call, and the model returns a completion. This works well for simple, single-turn use cases, but becomes cumbersome when you need persistent context, branching conversations, or access to external tools. The Responses API addresses these limitations directly:

Stateful by design

OpenAI stores conversation state server-side. Reference the previous response by ID instead of resending the full history.

Built-in hosted tools

Web search, file search, and code interpreter are available as first-class tools — no external integrations required.

Multi-turn made simple

Fork or continue conversations at any point using previous_response_id, enabling branching dialogue flows.

Reasoning visibility

Access chain-of-thought summaries from o3 and o4-mini to understand how the model arrived at its answer.

​
Making your first request

The surface of the Responses API is intentionally similar to Chat Completions. If you’ve used client.chat.completions.create() before, client.responses.create() will feel familiar. 
from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-4o",
    input="What is the latest news about AI?",
    tools=[{"type": "web_search_preview"}]
)

print(response.output_text)
The model receives your input, decides whether to invoke the web search tool, fetches live results, and synthesizes a grounded answer — all in a single API call.
response.output_text is a convenience accessor that concatenates all text output items. For more granular access, iterate over response.output directly.

​
Input types

The input field accepts more than plain strings. You can pass a list of typed content items to send images, audio, or structured data alongside text. 
response = client.responses.create(
    model="gpt-4o",
    input="Summarize the key points of the attached document.",
)

​
Built-in hosted tools

Instead of writing tool-calling logic and executing external functions yourself, the Responses API lets you declare hosted tools that OpenAI runs automatically. Gives the model real-time access to the internet. The model decides when to search and incorporates results into its response. 
response = client.responses.create(
    model="gpt-4o",
    input="What did OpenAI announce this week?",
    tools=[{"type": "web_search_preview"}],
)
print(response.output_text)
Queries a vector store you’ve pre-populated with your own documents. Ideal for building knowledge-base assistants or document Q&A systems. 
response = client.responses.create(
    model="gpt-4o",
    input="What does the employee handbook say about remote work?",
    tools=[{
        "type": "file_search",
        "vector_store_ids": ["vs_abc123"],
    }],
)
print(response.output_text)

​
Code interpreter

Executes Python in a sandboxed environment. Useful for data analysis, chart generation, and numerical computation. 
response = client.responses.create(
    model="gpt-4o",
    input="Calculate the compound interest on $10,000 at 5% annually for 10 years.",
    tools=[{"type": "code_interpreter", "container": {"type": "auto"}}],
)
print(response.output_text)
You can combine multiple tools in a single request. The model selects which tool(s) to call based on the query — no routing logic required on your end.

​
Multi-turn conversations with previous_response_id

The Responses API stores conversation context server-side. Pass previous_response_id to continue a conversation without resending the full message history.
1

Start a conversation

response = client.responses.create(
    model="gpt-4o",
    input="Tell me a joke.",
)
print(response.output_text)
# Why did the scarecrow win an award?
# Because he was outstanding in his field!
2

Continue from the previous response

response_two = client.responses.create(
    model="gpt-4o",
    input="Tell me another one.",
    previous_response_id=response.id,
)
print(response_two.output_text)
OpenAI maintains the conversation history automatically — no need to reconstruct the message array.
3

Fork from any point

# Branch the conversation from the *first* response instead of the second
forked = client.responses.create(
    model="gpt-4o",
    input="I didn't like that joke. Tell me a different one and explain why it's funny.",
    previous_response_id=response.id,  # fork from turn 1
)
print(forked.output_text)
Forking lets you explore alternative conversation branches without losing earlier context. This is particularly useful for A/B testing different follow-up prompts.
You can also retrieve any past response by its ID: 
fetched = client.responses.retrieve(response_id=response.id)
print(fetched.output_text)

​
Reasoning items and chain-of-thought visibility

When using reasoning models like o3 or o4-mini, the model generates an internal chain of thought before producing its final answer. In a multi-step conversation, those reasoning tokens are normally discarded between turns — which means the model must re-derive its reasoning from scratch on each call. The Responses API lets you pass reasoning items forward so the model can build on prior reasoning rather than starting over. This improves both response quality and token efficiency. 
# First turn: ask a complex question
response = client.responses.create(
    model="o3",
    input="Analyze the trade-offs between microservices and a monolithic architecture.",
    reasoning={"effort": "high", "summary": "auto"},
)

# The response includes a reasoning summary you can inspect
for item in response.output:
    if item.type == "reasoning":
        print("Reasoning summary:", item.summary)

# Second turn: continue with reasoning context preserved
follow_up = client.responses.create(
    model="o3",
    input="Based on your analysis, which would you recommend for a 5-person startup?",
    previous_response_id=response.id,
)
print(follow_up.output_text)
Reasoning summaries are available when summary is set to "auto" or "concise". Full reasoning tokens are never returned for safety reasons — only the summarized form.

​
How reasoning turns work

In a multi-step conversation, reasoning tokens from each turn are discarded after use, while input and output tokens are carried forward. By using previous_response_id, the Responses API ensures the model receives the complete prior context — including any reasoning summaries — enabling it to operate at maximum intelligence without redundant computation.

​
Next steps

Structured Outputs

Guarantee that model responses match a JSON schema you define, using Pydantic or raw JSON Schema.

File search

Upload documents to a vector store and query them using the built-in file search tool.

Build docs developers (and LLMs) love

Get started for freeTalk to us