Responses
List responses
GET
/openai/v1/responsesReturns a collection of all stored responses matching specified filter criteria.
Query ParametersHeader Parameters
limitintegeroptionaldefault: 20
A limit on the number of objects to be returned. Limit can range between 1 and 100, and the
default is 20.orderstringoptional
Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and`desc`
for descending order.ascdesc
afterstringoptional
A cursor for use in pagination. `after` is an object ID that defines your place in the list.
For instance, if you make a list request and receive 100 objects, ending with obj_foo, your
subsequent call can include after=obj_foo in order to fetch the next page of the list.beforestringoptional
A cursor for use in pagination. `before` is an object ID that defines your place in the list.
For instance, if you make a list request and receive 100 objects, ending with obj_foo, your
subsequent call can include before=obj_foo in order to fetch the previous page of the list.agent_namestringoptional
Filter by agent name. If provided, only items associated with the specified agent will be returned.agent_idstringoptional
Filter by agent ID in the format `name:version`. If provided, only items associated with the specified agent ID will be returned.conversation_idstringoptional
Filter by conversation ID. If provided, only responses associated with the specified conversation will be returned.x-ms-user-isolation-keystringoptional
Opaque per-user isolation key used to scope endpoint-scoped data (responses, conversations, sessions) to a specific end user.Responses
dataOpenAI.Response[]required
The requested list of items.metadataOpenAI.Metadata | null
top_logprobsinteger | null
temperaturenumber | null
top_pnumber | null
userstring
This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations.
A stable identifier for your end-users.
Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](/docs/guides/safety-best-practices#safety-identifiers).safety_identifierstring
A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies.
The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](/docs/guides/safety-best-practices#safety-identifiers).prompt_cache_keystring
Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](/docs/guides/prompt-caching).service_tierenum
Specifies the processing type used for serving the request.
- If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'.
- If set to 'default', then the request will be processed with the standard pricing and performance for the selected model.
- If set to '[flex](/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier.
- When not set, the default behavior is 'auto'.
When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter.autodefaultflexscalepriority
prompt_cache_retentionenum
in_memory24h
previous_response_idstring | null
modelstring
The model deployment to use for the creation of this response.reasoningOpenAI.Reasoning | null
backgroundboolean | null
max_tool_callsinteger | null
textOpenAI.ResponseTextParam
Configuration options for a text response from the model. Can be plain
text or structured JSON data. Learn more:
- [Text inputs and outputs](/docs/guides/text)
- [Structured Outputs](/docs/guides/structured-outputs)tools(bing_grounding | fabric_dataagent_preview | sharepoint_grounding_preview | azure_ai_search | openapi | bing_custom_search_preview | browser_automation_preview | azure_function | capture_structured_outputs | a2a_preview | work_iq_preview | fabric_iq_preview | memory_search_preview | toolbox_search_preview | code_interpreter | function | file_search | computer_use_preview | web_search | mcp | image_generation | local_shell | shell | custom | web_search_preview | apply_patch | computer | namespace | tool_search)[]
An array of tools the model may call while generating a response. You
can specify which tool to use by setting the `tool_choice` parameter.
We support the following categories of tools:
- **Built-in tools**: Tools that are provided by OpenAI that extend the
model's capabilities, like [web search](/docs/guides/tools-web-search)
or [file search](/docs/guides/tools-file-search). Learn more about
[built-in tools](/docs/guides/tools).
- **MCP Tools**: Integrations with third-party systems via custom MCP servers
or predefined connectors such as Google Drive and SharePoint. Learn more about
[MCP Tools](/docs/guides/tools-connectors-mcp).
- **Function calls (custom tools)**: Functions that are defined by you,
enabling the model to call your own code with strongly typed arguments
and outputs. Learn more about
[function calling](/docs/guides/function-calling). You can also use
custom tools to call your own code.tool_choiceOpenAI.ToolChoiceOptions | OpenAI.ToolChoiceParam
noneautorequired
promptOpenAI.Prompt
Reference to a prompt template and its variables.
[Learn more](/docs/guides/text?api-mode=responses#reusable-prompts).truncationenum
autodisabled
idstringrequired
Unique identifier for this Response.objectenumrequired
The object type of this resource - always set to `response`.response
statusenum
The status of the response generation. One of `completed`, `failed`,
`in_progress`, `cancelled`, `queued`, or `incomplete`.completedfailedin_progresscancelledqueuedincomplete
created_atintegerrequired
Unix timestamp (in seconds) of when this Response was created.completed_atstring | null
errorOpenAI.ResponseError | nullrequired
incomplete_detailsOpenAI.ResponseIncompleteDetails | nullrequired
output(structured_outputs | workflow_action | oauth_consent_request | bing_grounding_call | bing_grounding_call_output | sharepoint_grounding_preview_call | sharepoint_grounding_preview_call_output | azure_ai_search_call | azure_ai_search_call_output | bing_custom_search_preview_call | bing_custom_search_preview_call_output | openapi_call | openapi_call_output | browser_automation_preview_call | browser_automation_preview_call_output | fabric_dataagent_preview_call | fabric_dataagent_preview_call_output | azure_function_call | azure_function_call_output | a2a_preview_call | a2a_preview_call_output | memory_search_call | memory_command_preview_call | memory_command_preview_call_output | output_message | file_search_call | function_call | function_call_output | web_search_call | computer_call | computer_call_output | reasoning | tool_search_call | tool_search_output | compaction | image_generation_call | code_interpreter_call | local_shell_call | local_shell_call_output | shell_call | shell_call_output | apply_patch_call | apply_patch_call_output | mcp_call | mcp_list_tools | mcp_approval_request | mcp_approval_response | custom_tool_call | custom_tool_call_output)[]required
An array of content items generated by the model.
- The length and order of items in the `output` array is dependent
on the model's response.
- Rather than accessing the first item in the `output` array and
assuming it's an `assistant` message with the content generated by
the model, you might consider using the `output_text` property where
supported in SDKs.instructionsstring | (message | item_reference | output_message | file_search_call | computer_call | computer_call_output | web_search_call | function_call | function_call_output | tool_search_call | tool_search_output | reasoning | compaction | image_generation_call | code_interpreter_call | local_shell_call | local_shell_call_output | shell_call | shell_call_output | apply_patch_call | apply_patch_call_output | mcp_list_tools | mcp_approval_request | mcp_approval_response | mcp_call | custom_tool_call_output | custom_tool_call)[] | nullrequired
output_textstring | null
usageOpenAI.ResponseUsage
Represents token usage details including input tokens, output tokens,
a breakdown of output tokens, and the total tokens used.parallel_tool_callsbooleanrequired
Whether to allow the model to run tool calls in parallel.conversationOpenAI.ConversationReference | null
max_output_tokensinteger | null
agent_referenceAgentReference | nullrequired
The agent used for this responsecontent_filtersContentFilterResult[]
The content filter evaluation results.first_idstring
The first ID represented in this list.last_idstring
The last ID represented in this list.has_morebooleanrequired
A value indicating whether there are additional values available not captured in this list.