Response API Reference

Overview

The Responses API supports text, images, and files in a single API call.

Create a model response

Creates a model response. Provide text, image, or file inputs to generate text or JSON outputs. Have the model call your own custom code or use built-in tools like file search to use your own data as input for the model's response.

POST /v1/responses

Get a model response

Retrieves a model response with the given ID.

GET /v1/responses/{response_id}

Delete a model response

Deletes a model response with the given ID.

DELETE /v1/responses/{response_id}

Cancel a response

Cancels a model response with the given ID. Only responses created with the background parameter set to true can be cancelled.

POST /v1/responses/{response_id}/cancel

List input items

Returns a list of input items for a given response.

GET /v1/responses/{response_id}/input_items

Request Parameters

Parameter	Required	Type	Description
background	False	boolean or null	Choose whether or not to run the model response in the background for long-running tasks.
include	False	array or null	Specify additional output data to include in the response. `web_search_call.action.sources`: Include the sources of the web search tool call. `code_interpreter_call.outputs`: Includes the outputs of Python code execution in code interpreter tool call items. `computer_call_output.output.image_url`: Include image URLs from the computer call output. `file_search_call.results`: Include the search results of the file search tool call. `message.input_image.image_url`: Include image URLs from the input message. `message.output_text.logprobs`: Include logprobs with assistant messages. `reasoning.encrypted_content`: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the store parameter is set to `false`, or when an organization is enrolled in the zero data retention program).
input	Yes	string or array	The input to the model to generate a response, such as text, an image, or a file, for the model.
instructions	False	string or null	A system (or developer) message is inserted into the model's context.
max_output_tokens	False	integer or null	Upper bound for tokens that can be generated, including visible output and reasoning tokens.
max_tool_calls	False	integer or null	The maximum number of total calls to built-in tools that can be processed in a response.
metadata	False	map	Set of 16 key-value pairs for storing additional structured information.
model	Yes	string	Model ID used to generate the response. Available model IDs are GPT-4.1, GPT-4o, GPT-4o mini, o3, o3-mini, and o4-mini.
parallel_tool_calls	False	boolean or null	Whether to allow the model to run tool calls in parallel.
previous_response_id	False	string or null	Unique ID of the previous response to create multi-turn conversations.
prompt	False	object or null	Reference to a prompt template and its variables.
prompt[].id	Yes	string	The unique identifier of the prompt template to use.
prompt[].variables	False	map	Optional map of values to substitute in for variables in your prompt. The substitution values can either be strings or other Response input types, like images or files.
prompt[].version	False	map	Optional version of the prompt template.
prompt_cache_key	False	string	Used by OpenAI to cache responses for similar requests (replaces the user field).
reasoning	False	object or null	Configuration options for reasoning models (gpt-5 and O-series models only).
safety_identifier	False	string	Stable identifier to help detect users violating usage policies.
service_tier	False	string or null	Processing types are auto, default, flex, or priority.
store	False	boolean or null	Whether to store the generated model response for later retrieval via API.
stream	False	boolean or null	If true, response data is streamed using server-sent events.
stream_options	False	object or null	Options for streaming responses (only when stream: true).
include_obfuscation	False	boolean	When true, stream obfuscation will be enabled. Stream obfuscation adds random characters to an `obfuscation` field on streaming delta events to normalize payload sizes as a mitigation to certain side-channel attacks. These obfuscation fields are included by default, but they add a small amount of overhead to the data stream. You can set `include_obfuscation` to false to optimize for bandwidth if you trust the network links between your application and the OpenAI API.
temperature	False	number or null	Sampling temperature between 0 and 2. Higher = more random, lower = more focused.
text	False	object	Configuration options for text response (plain text or structured JSON).
tool_choice	False	string or object	How the model should select which tool(s) to use when generating a response.
tools	False	array	An array of tools that the model may call (built-in tools or custom functions).
top_logprobs	False	integer or null	Number of most likely tokens to return at each position (0-20).
top_p	False	number or null	Nucleus sampling alternative to temperature (0.1 = top 10% probability mass).
truncation	False	string or null	Truncation strategy: "auto" or "disabled". `auto`: If the context of this response and previous ones exceeds the model's context window size, the model will truncate the response to fit the context window by dropping input items in the middle of the conversation. `disabled` (default): If a model response will exceed the context window size for a model, the request will fail with a 400 error.
tools.type	Yes	string	The type of the web search tool. Note: This parameter is available with GPT-4.1, GPT-4o, and GPT-4o mini models.
tools.search_context_size	False	string	High-level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. Note: This parameter is available with GPT-4.1, GPT-4o, and GPT-4o mini models.
tools.user_location	False	object	Approximate location of the user. Note: This parameter is available with GPT-4.1, GPT-4o, and GPT-4o mini models.
tools.user_location.city	False	string	Free text input for the city of the user, e.g. San Francisco.
tools.user_location.country	False	string	The two-letter ISO country code of the user, e.g. US.
tools.user_location.region	False	string	Free text input for the region of the user, e.g. California.
tools.user_location.timezone	False	string	The IANA timezone of the user, e.g. America/Los_Angeles.
tools.user_location.type	False	string	The type of location approximation. Always approximate.
user	False	string	Deprecated: Replaced by `safety_identifier` and `prompt_cache_key`.

Web Search Tool Example

Sample Request Format

{
    "model": "gpt-4o",
    "tools": [
        {
            "type": "web_search_preview",
            "search_context_size": "low",
            "user_location": {
                "type": "approximate",
                "city": "Austin",
                "country": "US",
                "region": null,
                "timezone": null
            }
        }
    ],
    "input": "what are top 2 tools for automation in 2025?"
}

Sample Response Format

{
    "id": "resp_04d5dbbc198d81810068e5518107a88190bb0713e4f34edfbb",
    "object": "response",
    "created_at": 1759859073,
    "status": "completed",
    "background": false,
    "content_filters": null,
    "error": null,
    "incomplete_details": null,
    "instructions": null,
    "max_output_tokens": null,
    "max_tool_calls": null,
    "model": "gpt-4o",
    "output": [
        {
            "id": "ws_04d5dbbc198d81810068e55181625c819093e79662ed315cd0",
            "type": "web_search_call",
            "status": "completed",
            "action": {
                "type": "search",
                "query": "top automation tools 2025"
            }
        },
        {
            "id": "msg_04d5dbbc198d81810068e551836e808190973e67709caa4093",
            "type": "message",
            "status": "completed",
            "content": [
                {
                    "type": "output_text",
                    "annotations": [],
                    "logprobs": [],
                    "text": "Two of the top automation tools in 2025 are:\n\n1. **UiPath**: A leading Robotic Process Automation (RPA) platform, heavily used for enterprise-grade task automation involving repetitive functions across industries. It integrates AI and machine learning to handle complex workflows efficiently.\n\n2. **Zapier**: A no-code automation platform connecting over 6,000+ apps. It is widely popular for automating repetitive tasks between applications, ideal for small businesses and individuals looking for user-friendly solutions. \n\nThese tools cater to both advanced enterprise needs and smaller-scale automation, making them a consistent choice across different industries."
                }
            ],
            "role": "assistant"
        }
    ],
    "parallel_tool_calls": true,
    "previous_response_id": null,
    "prompt_cache_key": null,
    "reasoning": {
        "effort": null,
        "summary": null
    },
    "safety_identifier": null,
    "service_tier": "default",
    "store": true,
    "temperature": 1.0,
    "text": {
        "format": {
            "type": "text"
        },
        "verbosity": "medium"
    },
    "tool_choice": "auto",
    "tools": [
        {
            "type": "web_search_preview",
            "search_context_size": "low",
            "user_location": {
                "type": "approximate",
                "city": "Austin",
                "country": "US",
                "region": null,
                "timezone": null
            }
        }
    ],
    "top_logprobs": 0,
    "top_p": 1.0,
    "truncation": "disabled",
    "usage": {
        "input_tokens": 6546,
        "input_tokens_details": {
            "cached_tokens": 0
        },
        "output_tokens": 148,
        "output_tokens_details": {
            "reasoning_tokens": 0
        },
        "total_tokens": 6694
    },
    "user": null,
    "metadata": {}
}