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 anddesc
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-identitystringoptional
Opaque per-user identity string used to scope endpoint-scoped data to a specific end user. The caller must have the agents/endpoints/UserIdentityImpersonation/action RBAC permission.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.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.prompt_cache_keystring
Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the user field. Learn more.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' or 'priority', 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.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
- Structured Outputstools(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 | 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
or file search. Learn more about
built-in 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.
- 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. 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.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 | additional_tools | 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.reasoningOpenAI.Reasoning | null
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 | additional_tools | 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.moderationOpenAI.Moderation | null
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.