---
title: "Responses Api"
method: POST
path: "/responses"
tags: ["responses"]
---

# Responses Api

`POST /responses`

## Request

- Base URL: `https://api.sea-lion.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.sea-lion.ai/responses`
- Auth: API key in header `x-litellm-api-key`

Follows the OpenAI Responses API spec: https://platform.openai.com/docs/api-reference/responses

Supports background mode with polling_via_cache for partial response retrieval.
When background=true and polling_via_cache is enabled, returns a polling_id immediately
and streams the response in the background, updating Redis cache.

```bash
# Normal request
curl -X POST http://localhost:4000/v1/responses     -H "Content-Type: application/json"     -H "Authorization: Bearer $LITELLM_MASTER_KEY"     -d '{
    "model": "gpt-4o",
    "input": "Tell me about AI"
}'

# Background request with polling
curl -X POST http://localhost:4000/v1/responses     -H "Content-Type: application/json"     -H "Authorization: Bearer $LITELLM_MASTER_KEY"     -d '{
    "model": "gpt-4o",
    "input": "Tell me about AI",
    "background": true
}'
```

## Request body

- object
  - `include` string[], nullable
  - `instructions` string, nullable
  - `max_output_tokens` integer, nullable
  - `metadata` object, nullable
  - `parallel_tool_calls` boolean, nullable
  - `previous_response_id` string, nullable
  - `reasoning` Reasoning: **gpt-5 and o-series models only** Configuration options for [reasoning models](https://platform.openai.com/docs/guides/reasoning).
    - `effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh', nullable
    - `generate_summary` 'auto' | 'concise' | 'detailed', nullable
    - `summary` 'auto' | 'concise' | 'detailed', nullable
  - `store` boolean, nullable
  - `background` boolean, nullable
  - `stream` boolean, nullable
  - `temperature` number, nullable
  - `text` ResponseTextConfigParam: Configuration options for a text response from the model. Can be plain text or structured JSON data. Learn more: - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs)
    - `format` union
      - ResponseFormatText: Default response format. Used to generate text responses.
        - `type` 'text', required
      - ResponseFormatTextJSONSchemaConfigParam: JSON Schema response format. Used to generate structured JSON responses. Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs).
        - `name` string, required
        - `schema` object, required
        - `type` 'json_schema', required
        - `description` string
        - `strict` boolean, nullable
      - ResponseFormatJSONObject: JSON object response format. An older method of generating JSON responses. Using `json_schema` is recommended for models that support it. Note that the model will not generate JSON without a system or user message instructing it to do so.
        - `type` 'json_object', required
    - `verbosity` 'low' | 'medium' | 'high', nullable
  - `tool_choice` union
    - 'none' | 'auto' | 'required'
    - ToolChoiceAllowedParam: Constrains the tools available to the model to a pre-defined set.
      - `mode` 'auto' | 'required', required
      - `tools` object[], required
      - `type` 'allowed_tools', required
    - ToolChoiceTypesParam: Indicates that the model should use a built-in tool to generate a response. [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools).
      - `type` 'file_search' | 'web_search_preview' | 'computer' | 'computer_use_preview' | 'computer_use' | 'web_search_preview_2025_03_11' | 'image_generation' | 'code_interpreter', required
    - ToolChoiceFunctionParam: Use this option to force the model to call a specific function.
      - `name` string, required
      - `type` 'function', required
    - ToolChoiceMcpParam: Use this option to force the model to call a specific tool on a remote MCP server.
      - `server_label` string, required
      - `type` 'mcp', required
      - `name` string, nullable
    - ToolChoiceCustomParam: Use this option to force the model to call a specific custom tool.
      - `name` string, required
      - `type` 'custom', required
    - ToolChoiceApplyPatchParam: Forces the model to call the apply_patch tool when executing a tool call.
      - `type` 'apply_patch', required
    - ToolChoiceShellParam: Forces the model to call the shell tool when a tool call is required.
      - `type` 'shell', required
  - `tools` union[], nullable
    - union
      - FunctionToolParam: Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling).
        - `name` string, required
        - `parameters` object, nullable, required
        - `strict` boolean, nullable, required
        - `type` 'function', required
        - `defer_loading` boolean
        - `description` string, nullable
      - FileSearchToolParam: A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search).
        - `type` 'file_search', required
        - `vector_store_ids` string[], required
        - `filters` union
          - ComparisonFilter: A filter used to compare a specified attribute key to a given value using a defined comparison operation.
            - `key` string, required
            - `type` 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin', required
            - `value` union, required
              - …
          - CompoundFilter: Combine multiple filters using `and` or `or`.
            - `filters` union[], required
              - …
            - `type` 'and' | 'or', required
        - `max_num_results` integer
        - `ranking_options` RankingOptions: Ranking options for search.
          - `hybrid_search` RankingOptionsHybridSearch: Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled.
            - `embedding_weight` number, required
            - `text_weight` number, required
          - `ranker` 'auto' | 'default-2024-11-15', nullable
          - `score_threshold` number, nullable
      - OpenaiTypesResponsesComputerToolParamComputerToolParam: A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use).
        - `type` 'computer', required
      - ComputerUsePreviewToolParam: A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use).
        - `display_height` integer, required
        - `display_width` integer, required
        - `environment` 'windows' | 'mac' | 'linux' | 'ubuntu' | 'browser', required
        - `type` 'computer_use_preview', required
      - WebSearchToolParam: Search the Internet for sources related to the prompt. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search).
        - `type` 'web_search' | 'web_search_2025_08_26', required
        - `filters` Filters: Filters for the search.
          - `allowed_domains` string[], nullable
        - `search_context_size` 'low' | 'medium' | 'high'
        - `user_location` OpenaiTypesResponsesWebSearchToolParamUserLocation: The approximate location of the user.
          - `city` string, nullable
          - `country` string, nullable
          - `region` string, nullable
          - `timezone` string, nullable
          - `type` 'approximate'
      - Mcp: Give the model access to additional tools via remote Model Context Protocol (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp).
        - `server_label` string, required
        - `type` 'mcp', required
        - `allowed_tools` union
          - string[]
          - McpAllowedToolsMcpToolFilter: A filter object to specify which tools are allowed.
            - `read_only` boolean, nullable
            - `tool_names` string[], nullable
        - `authorization` string, nullable
        - `connector_id` 'connector_dropbox' | 'connector_gmail' | 'connector_googlecalendar' | 'connector_googledrive' | 'connector_microsoftteams' | 'connector_outlookcalendar' | 'connector_outlookemail' | 'connector_sharepoint', nullable
        - `defer_loading` boolean, nullable
        - `headers` object, nullable
        - `require_approval` union
          - McpRequireApprovalMcpToolApprovalFilter: Specify which of the MCP server's tools require approval. Can be `always`, `never`, or a filter object associated with tools that require approval.
            - `always` McpRequireApprovalMcpToolApprovalFilterAlways: A filter object to specify which tools are allowed.
              - …
            - `never` McpRequireApprovalMcpToolApprovalFilterNever: A filter object to specify which tools are allowed.
              - …
          - 'always' | 'never'
        - `server_description` string, nullable
        - `server_url` string, nullable
      - CodeInterpreter: A tool that runs Python code to help generate a response to a prompt.
        - `container` union, required
          - string
          - CodeInterpreterContainerCodeInterpreterToolAuto: Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on.
            - `type` 'auto', required
            - `file_ids` string[], nullable
            - `memory_limit` '1g' | '4g' | '16g' | '64g', nullable
            - `network_policy` union
              - …
        - `type` 'code_interpreter', required
      - ImageGeneration: A tool that generates images using the GPT image models.
        - `type` 'image_generation', required
        - `action` 'generate' | 'edit' | 'auto', nullable
        - `background` 'transparent' | 'opaque' | 'auto', nullable
        - `input_fidelity` 'high' | 'low', nullable
        - `input_image_mask` ImageGenerationInputImageMask: Optional mask for inpainting. Contains `image_url` (string, optional) and `file_id` (string, optional).
          - `file_id` string, nullable
          - `image_url` string, nullable
        - `model` union
          - string
          - 'gpt-image-1' | 'gpt-image-1-mini' | 'gpt-image-1.5'
        - `moderation` 'auto' | 'low', nullable
        - `output_compression` integer, nullable
        - `output_format` 'png' | 'webp' | 'jpeg', nullable
        - `partial_images` integer, nullable
        - `quality` 'low' | 'medium' | 'high' | 'auto', nullable
        - `size` '1024x1024' | '1024x1536' | '1536x1024' | 'auto', nullable
      - LocalShell: A tool that allows the model to execute shell commands in a local environment.
        - `type` 'local_shell', required
      - FunctionShellToolParam: A tool that allows the model to execute shell commands.
        - `type` 'shell', required
        - `environment` union
          - ContainerAutoParam
            - `type` 'container_auto', required
            - `file_ids` string[]
            - `memory_limit` '1g' | '4g' | '16g' | '64g', nullable
            - `network_policy` union
              - …
            - `skills` union[]
              - …
          - LocalEnvironmentParam
            - `type` 'local', required
            - `skills` LocalSkillParam[]
              - …
          - ContainerReferenceParam
            - `container_id` string, required
            - `type` 'container_reference', required
      - CustomToolParam: A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools)
        - `name` string, required
        - `type` 'custom', required
        - `defer_loading` boolean
        - `description` string
        - `format` union
          - Text: Unconstrained free-form text.
            - `type` 'text', required
          - Grammar: A grammar defined by the user.
            - `definition` string, required
            - `syntax` 'lark' | 'regex', required
            - `type` 'grammar', required
      - NamespaceToolParam: Groups function/custom tools under a shared namespace.
        - `description` string, required
        - `name` string, required
        - `tools` union[], required
          - union
            - ToolFunction
              - …
            - CustomToolParam: A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools)
              - …
        - `type` 'namespace', required
      - ToolSearchToolParam: Hosted or BYOT tool search configuration for deferred tools.
        - `type` 'tool_search', required
        - `description` string, nullable
        - `execution` 'server' | 'client'
        - `parameters` unknown
      - WebSearchPreviewToolParam: This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search).
        - `type` 'web_search_preview' | 'web_search_preview_2025_03_11', required
        - `search_content_types` string[]
        - `search_context_size` 'low' | 'medium' | 'high'
        - `user_location` OpenaiTypesResponsesWebSearchPreviewToolParamUserLocation: The user's location.
          - `type` 'approximate', required
          - `city` string, nullable
          - `country` string, nullable
          - `region` string, nullable
          - `timezone` string, nullable
      - ApplyPatchToolParam: Allows the assistant to create, delete, or update files using unified diffs.
        - `type` 'apply_patch', required
      - LitellmTypesLlmsOpenaiComputerToolParam
        - `display_height` number, required
        - `display_width` number, required
        - `environment` union, required
          - 'mac' | 'windows' | 'ubuntu' | 'browser'
          - string
        - `type` union, required
          - 'computer_use_preview'
          - string
      - ShellToolParam: Shell tool for Responses API: run commands in hosted containers or local runtime. See https://developers.openai.com/api/docs/guides/tools-shell.
        - `type` union, required
          - 'shell'
          - string
        - `environment` object, required
  - `top_p` number, nullable
  - `truncation` 'auto' | 'disabled', nullable
  - `user` string, nullable
  - `service_tier` string, nullable
  - `safety_identifier` string, nullable
  - `prompt` PromptObject: Reference to a stored prompt template.
    - `id` string, required
    - `variables` object, nullable
    - `version` string, nullable
  - `max_tool_calls` integer, nullable
  - `prompt_cache_key` string, nullable
  - `prompt_cache_retention` string, nullable
  - `prompt_cache_options` PromptCacheOptions
    - `mode` 'implicit' | 'explicit'
    - `ttl` '30m'
  - `stream_options` ResponsesAPIStreamOptions
    - `include_obfuscation` boolean
  - `top_logprobs` integer, nullable
  - `partial_images` integer, nullable
  - `context_management` ContextManagementEntry[], nullable
    - `type` string
    - `compact_threshold` integer
  - `input` union, required
    - string
    - union[]
      - union
        - EasyInputMessageParam: A message input to the model with a role indicating instruction following hierarchy. Instructions given with the `developer` or `system` role take precedence over instructions given with the `user` role. Messages with the `assistant` role are presumed to have been generated by the model in previous interactions.
          - `content` union, required
            - string
            - union[]
              - …
          - `role` 'user' | 'assistant' | 'system' | 'developer', required
          - `phase` 'commentary' | 'final_answer', nullable
          - `type` 'message'
        - ResponsesAPIRequestParamsMessage: A message input to the model with a role indicating instruction following hierarchy. Instructions given with the `developer` or `system` role take precedence over instructions given with the `user` role.
          - `content` union[], required
            - union
              - …
          - `role` 'user' | 'system' | 'developer', required
          - `status` 'in_progress' | 'completed' | 'incomplete'
          - `type` 'message'
        - ResponseOutputMessageParam: An output message from the model.
          - `id` string, required
          - `content` union[], required
            - union
              - …
          - `role` 'assistant', required
          - `status` 'in_progress' | 'completed' | 'incomplete', required
          - `type` 'message', required
          - `phase` 'commentary' | 'final_answer', nullable
        - ResponseFileSearchToolCallParam: The results of a file search tool call. See the [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information.
          - `id` string, required
          - `queries` string[], required
          - `status` 'in_progress' | 'searching' | 'completed' | 'incomplete' | 'failed', required
          - `type` 'file_search_call', required
          - `results` Result[], nullable
            - `attributes` object, nullable
            - `file_id` string
            - `filename` string
            - `score` number
            - `text` string
        - ResponseComputerToolCallParam: A tool call to a computer use tool. See the [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information.
          - `id` string, required
          - `call_id` string, required
          - `pending_safety_checks` PendingSafetyCheck[], required
            - `id` string, required
            - `code` string, nullable
            - `message` string, nullable
          - `status` 'in_progress' | 'completed' | 'incomplete', required
          - `type` 'computer_call', required
          - `action` union
            - ActionClick: A click action.
              - …
            - ResponsesAPIRequestParamsActionDoubleClick: A double click action.
              - …
            - ActionDrag: A drag action.
              - …
            - ActionKeypress: A collection of keypresses the model would like to perform.
              - …
            - ActionMove: A mouse move action.
              - …
            - ActionScreenshot: A screenshot action.
              - …
            - ActionScroll: A scroll action.
              - …
            - ActionType: An action to type in text.
              - …
            - ActionWait: A wait action.
              - …
          - `actions` union[]
            - union
              - …
        - ComputerCallOutput: The output of a computer tool call.
          - `call_id` string, required
          - `output` ResponseComputerToolCallOutputScreenshotParam, required: A computer screenshot image used with the computer use tool.
            - `type` 'computer_screenshot', required
            - `file_id` string
            - `image_url` string
          - `type` 'computer_call_output', required
          - `id` string, nullable
          - `acknowledged_safety_checks` ComputerCallOutputAcknowledgedSafetyCheck[], nullable
            - `id` string, required
            - `code` string, nullable
            - `message` string, nullable
          - `status` 'in_progress' | 'completed' | 'incomplete', nullable
        - ResponseFunctionWebSearchParam: The results of a web search tool call. See the [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information.
          - `id` string, required
          - `action` union, required
            - ActionSearch: Action type "search" - Performs a web search query.
              - …
            - ActionOpenPage: Action type "open_page" - Opens a specific URL from search results.
              - …
            - ActionFind: Action type "find_in_page": Searches for a pattern within a loaded page.
              - …
          - `status` 'in_progress' | 'searching' | 'completed' | 'failed', required
          - `type` 'web_search_call', required
        - ResponseFunctionToolCallParam: A tool call to run a function. See the [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information.
          - `arguments` string, required
          - `call_id` string, required
          - `name` string, required
          - `type` 'function_call', required
          - `id` string
          - `namespace` string
          - `status` 'in_progress' | 'completed' | 'incomplete'
        - FunctionCallOutput: The output of a function tool call.
          - `call_id` string, required
          - `output` union, required
            - string
            - union[]
              - …
          - `type` 'function_call_output', required
          - `id` string, nullable
          - `status` 'in_progress' | 'completed' | 'incomplete', nullable
        - ToolSearchCall
          - `arguments` unknown, required
          - `type` 'tool_search_call', required
          - `id` string, nullable
          - `call_id` string, nullable
          - `execution` 'server' | 'client'
          - `status` 'in_progress' | 'completed' | 'incomplete', nullable
        - ResponseToolSearchOutputItemParamParam
          - `tools` union[], required
            - union
              - …
          - `type` 'tool_search_output', required
          - `id` string, nullable
          - `call_id` string, nullable
          - `execution` 'server' | 'client'
          - `status` 'in_progress' | 'completed' | 'incomplete', nullable
        - ResponseReasoningItemParam: A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your `input` to the Responses API for subsequent turns of a conversation if you are manually [managing context](https://platform.openai.com/docs/guides/conversation-state).
          - `id` string, required
          - `summary` Summary[], required
            - `text` string, required
            - `type` 'summary_text', required
          - `type` 'reasoning', required
          - `content` Content[]
            - `text` string, required
            - `type` 'reasoning_text', required
          - `encrypted_content` string, nullable
          - `status` 'in_progress' | 'completed' | 'incomplete'
        - ResponseCompactionItemParamParam: A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact).
          - `encrypted_content` string, required
          - `type` 'compaction', required
          - `id` string, nullable
        - ResponsesAPIRequestParamsImageGenerationCall: An image generation request made by the model.
          - `id` string, required
          - `result` string, nullable, required
          - `status` 'in_progress' | 'completed' | 'generating' | 'failed', required
          - `type` 'image_generation_call', required
        - ResponseCodeInterpreterToolCallParam: A tool call to run code.
          - `id` string, required
          - `code` string, nullable, required
          - `container_id` string, required
          - `outputs` union[], nullable, required
            - union
              - …
          - `status` 'in_progress' | 'completed' | 'incomplete' | 'interpreting' | 'failed', required
          - `type` 'code_interpreter_call', required
        - LocalShellCall: A tool call to run a command on the local shell.
          - `id` string, required
          - `action` LocalShellCallAction, required: Execute a shell command on the server.
            - `command` string[], required
            - `env` object, required
            - `type` 'exec', required
            - `timeout_ms` integer, nullable
            - `user` string, nullable
            - `working_directory` string, nullable
          - `call_id` string, required
          - `status` 'in_progress' | 'completed' | 'incomplete', required
          - `type` 'local_shell_call', required
        - LocalShellCallOutput: The output of a local shell tool call.
          - `id` string, required
          - `output` string, required
          - `type` 'local_shell_call_output', required
          - `status` 'in_progress' | 'completed' | 'incomplete', nullable
        - ShellCall: A tool representing a request to execute one or more shell commands.
          - `action` ShellCallAction, required: The shell commands and limits that describe how to run the tool call.
            - `commands` string[], required
            - `max_output_length` integer, nullable
            - `timeout_ms` integer, nullable
          - `call_id` string, required
          - `type` 'shell_call', required
          - `id` string, nullable
          - `environment` union
            - LocalEnvironmentParam
              - …
            - ContainerReferenceParam
              - …
          - `status` 'in_progress' | 'completed' | 'incomplete', nullable
        - ShellCallOutput: The streamed output items emitted by a shell tool call.
          - `call_id` string, required
          - `output` ResponseFunctionShellCallOutputContentParam[], required
            - `outcome` union, required
              - …
            - `stderr` string, required
            - `stdout` string, required
          - `type` 'shell_call_output', required
          - `id` string, nullable
          - `max_output_length` integer, nullable
          - `status` 'in_progress' | 'completed' | 'incomplete', nullable
        - ApplyPatchCall: A tool call representing a request to create, delete, or update files using diff patches.
          - `call_id` string, required
          - `operation` union, required
            - ApplyPatchCallOperationCreateFile: Instruction for creating a new file via the apply_patch tool.
              - …
            - ApplyPatchCallOperationDeleteFile: Instruction for deleting an existing file via the apply_patch tool.
              - …
            - ApplyPatchCallOperationUpdateFile: Instruction for updating an existing file via the apply_patch tool.
              - …
          - `status` 'in_progress' | 'completed', required
          - `type` 'apply_patch_call', required
          - `id` string, nullable
        - ApplyPatchCallOutput: The streamed output emitted by an apply patch tool call.
          - `call_id` string, required
          - `status` 'completed' | 'failed', required
          - `type` 'apply_patch_call_output', required
          - `id` string, nullable
          - `output` string, nullable
        - McpListTools: A list of tools available on an MCP server.
          - `id` string, required
          - `server_label` string, required
          - `tools` McpListToolsTool[], required
            - `input_schema` unknown, required
            - `name` string, required
            - `annotations` unknown
            - `description` string, nullable
          - `type` 'mcp_list_tools', required
          - `error` string, nullable
        - McpApprovalRequest: A request for human approval of a tool invocation.
          - `id` string, required
          - `arguments` string, required
          - `name` string, required
          - `server_label` string, required
          - `type` 'mcp_approval_request', required
        - ResponsesAPIRequestParamsMcpApprovalResponse: A response to an MCP approval request.
          - `approval_request_id` string, required
          - `approve` boolean, required
          - `type` 'mcp_approval_response', required
          - `id` string, nullable
          - `reason` string, nullable
        - McpCall: An invocation of a tool on an MCP server.
          - `id` string, required
          - `arguments` string, required
          - `name` string, required
          - `server_label` string, required
          - `type` 'mcp_call', required
          - `approval_request_id` string, nullable
          - `error` string, nullable
          - `output` string, nullable
          - `status` 'in_progress' | 'completed' | 'incomplete' | 'calling' | 'failed', nullable
        - ResponseCustomToolCallOutputParam: The output of a custom tool call from your code, being sent back to the model.
          - `call_id` string, required
          - `output` union, required
            - string
            - union[]
              - …
          - `type` 'custom_tool_call_output', required
          - `id` string
        - ResponseCustomToolCallParam: A call to a custom tool created by the model.
          - `call_id` string, required
          - `input` string, required
          - `name` string, required
          - `type` 'custom_tool_call', required
          - `id` string
          - `namespace` string
        - ItemReference: An internal identifier for an item to reference.
          - `id` string, required
          - `type` 'item_reference', nullable
  - `model` string, required

## Response `200`

Successful Response

- ResponsesAPIResponse
  - `id` string, required
  - `created_at` integer, required
  - `error` object, nullable
  - `incomplete_details` IncompleteDetails: Details about why the response is incomplete.
    - `reason` 'max_output_tokens' | 'content_filter', nullable
  - `instructions` string, nullable
  - `metadata` object, nullable
  - `model` string, nullable
  - `object` string, nullable
  - `output` union, required
    - union[]
      - union
        - ResponseOutputMessage: An output message from the model.
          - `id` string, required
          - `content` union[], required
            - union
              - …
          - `role` 'assistant', required
          - `status` 'in_progress' | 'completed' | 'incomplete', required
          - `type` 'message', required
          - `phase` 'commentary' | 'final_answer', nullable
        - ResponseFileSearchToolCall: The results of a file search tool call. See the [file search guide](https://platform.openai.com/docs/guides/tools-file-search) for more information.
          - `id` string, required
          - `queries` string[], required
          - `status` 'in_progress' | 'searching' | 'completed' | 'incomplete' | 'failed', required
          - `type` 'file_search_call', required
          - `results` ResultOutput[], nullable
            - `attributes` object, nullable
            - `file_id` string, nullable
            - `filename` string, nullable
            - `score` number, nullable
            - `text` string, nullable
        - ResponseFunctionToolCall: A tool call to run a function. See the [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information.
          - `arguments` string, required
          - `call_id` string, required
          - `name` string, required
          - `type` 'function_call', required
          - `id` string, nullable
          - `namespace` string, nullable
          - `status` 'in_progress' | 'completed' | 'incomplete', nullable
        - ResponseFunctionToolCallOutputItem
          - `id` string, required
          - `call_id` string, required
          - `output` union, required
            - string
            - union[]
              - …
          - `status` 'in_progress' | 'completed' | 'incomplete', required
          - `type` 'function_call_output', required
          - `created_by` string, nullable
        - ResponseFunctionWebSearch: The results of a web search tool call. See the [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information.
          - `id` string, required
          - `action` union, required
            - ActionSearch: Action type "search" - Performs a web search query.
              - …
            - ActionOpenPage: Action type "open_page" - Opens a specific URL from search results.
              - …
            - ActionFind: Action type "find_in_page": Searches for a pattern within a loaded page.
              - …
          - `status` 'in_progress' | 'searching' | 'completed' | 'failed', required
          - `type` 'web_search_call', required
        - ResponseComputerToolCall: A tool call to a computer use tool. See the [computer use guide](https://platform.openai.com/docs/guides/tools-computer-use) for more information.
          - `id` string, required
          - `call_id` string, required
          - `pending_safety_checks` PendingSafetyCheck[], required
            - `id` string, required
            - `code` string, nullable
            - `message` string, nullable
          - `status` 'in_progress' | 'completed' | 'incomplete', required
          - `type` 'computer_call', required
          - `action` union
            - ActionClick: A click action.
              - …
            - ActionDoubleClick: A double click action.
              - …
            - ActionDrag: A drag action.
              - …
            - ActionKeypress: A collection of keypresses the model would like to perform.
              - …
            - ActionMove: A mouse move action.
              - …
            - ActionScreenshot: A screenshot action.
              - …
            - ActionScroll: A scroll action.
              - …
            - ActionType: An action to type in text.
              - …
            - ActionWait: A wait action.
              - …
          - `actions` union[], nullable
            - union
              - …
        - ResponseComputerToolCallOutputItem
          - `id` string, required
          - `call_id` string, required
          - `output` ResponseComputerToolCallOutputScreenshot, required: A computer screenshot image used with the computer use tool.
            - `type` 'computer_screenshot', required
            - `file_id` string, nullable
            - `image_url` string, nullable
          - `status` 'completed' | 'incomplete' | 'failed' | 'in_progress', required
          - `type` 'computer_call_output', required
          - `acknowledged_safety_checks` AcknowledgedSafetyCheck[], nullable
            - `id` string, required
            - `code` string, nullable
            - `message` string, nullable
          - `created_by` string, nullable
        - ResponseReasoningItem: A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your `input` to the Responses API for subsequent turns of a conversation if you are manually [managing context](https://platform.openai.com/docs/guides/conversation-state).
          - `id` string, required
          - `summary` Summary[], required
            - `text` string, required
            - `type` 'summary_text', required
          - `type` 'reasoning', required
          - `content` Content[], nullable
            - `text` string, required
            - `type` 'reasoning_text', required
          - `encrypted_content` string, nullable
          - `status` 'in_progress' | 'completed' | 'incomplete', nullable
        - ResponseToolSearchCall
          - `id` string, required
          - `arguments` unknown, required
          - `call_id` string, nullable
          - `execution` 'server' | 'client', required
          - `status` 'in_progress' | 'completed' | 'incomplete', required
          - `type` 'tool_search_call', required
          - `created_by` string, nullable
        - ResponseToolSearchOutputItem
          - `id` string, required
          - `call_id` string, nullable
          - `execution` 'server' | 'client', required
          - `status` 'in_progress' | 'completed' | 'incomplete', required
          - `tools` union[], required
            - union
              - …
          - `type` 'tool_search_output', required
          - `created_by` string, nullable
        - ResponseCompactionItem: A compaction item generated by the [`v1/responses/compact` API](https://platform.openai.com/docs/api-reference/responses/compact).
          - `id` string, required
          - `encrypted_content` string, required
          - `type` 'compaction', required
          - `created_by` string, nullable
        - ImageGenerationCall: An image generation request made by the model.
          - `id` string, required
          - `result` string, nullable
          - `status` 'in_progress' | 'completed' | 'generating' | 'failed', required
          - `type` 'image_generation_call', required
        - ResponseCodeInterpreterToolCall: A tool call to run code.
          - `id` string, required
          - `code` string, nullable
          - `container_id` string, required
          - `outputs` union[], nullable
            - union
              - …
          - `status` 'in_progress' | 'completed' | 'incomplete' | 'interpreting' | 'failed', required
          - `type` 'code_interpreter_call', required
        - LocalShellCall: A tool call to run a command on the local shell.
          - `id` string, required
          - `action` LocalShellCallAction, required: Execute a shell command on the server.
            - `command` string[], required
            - `env` object, required
            - `type` 'exec', required
            - `timeout_ms` integer, nullable
            - `user` string, nullable
            - `working_directory` string, nullable
          - `call_id` string, required
          - `status` 'in_progress' | 'completed' | 'incomplete', required
          - `type` 'local_shell_call', required
        - LocalShellCallOutput: The output of a local shell tool call.
          - `id` string, required
          - `output` string, required
          - `type` 'local_shell_call_output', required
          - `status` 'in_progress' | 'completed' | 'incomplete', nullable
        - ResponseFunctionShellToolCall: A tool call that executes one or more shell commands in a managed environment.
          - `id` string, required
          - `action` Action, required: The shell commands and limits that describe how to run the tool call.
            - `commands` string[], required
            - `max_output_length` integer, nullable
            - `timeout_ms` integer, nullable
          - `call_id` string, required
          - `environment` union
            - ResponseLocalEnvironment: Represents the use of a local environment to perform shell actions.
              - …
            - ResponseContainerReference: Represents a container created with /v1/containers.
              - …
          - `status` 'in_progress' | 'completed' | 'incomplete', required
          - `type` 'shell_call', required
          - `created_by` string, nullable
        - ResponseFunctionShellToolCallOutput: The output of a shell tool call that was emitted.
          - `id` string, required
          - `call_id` string, required
          - `max_output_length` integer, nullable
          - `output` Output[], required
            - `outcome` union, required
              - …
            - `stderr` string, required
            - `stdout` string, required
            - `created_by` string, nullable
          - `status` 'in_progress' | 'completed' | 'incomplete', required
          - `type` 'shell_call_output', required
          - `created_by` string, nullable
        - ResponseApplyPatchToolCall: A tool call that applies file diffs by creating, deleting, or updating files.
          - `id` string, required
          - `call_id` string, required
          - `operation` union, required
            - OperationCreateFile: Instruction describing how to create a file via the apply_patch tool.
              - …
            - OperationDeleteFile: Instruction describing how to delete a file via the apply_patch tool.
              - …
            - OperationUpdateFile: Instruction describing how to update a file via the apply_patch tool.
              - …
          - `status` 'in_progress' | 'completed', required
          - `type` 'apply_patch_call', required
          - `created_by` string, nullable
        - ResponseApplyPatchToolCallOutput: The output emitted by an apply patch tool call.
          - `id` string, required
          - `call_id` string, required
          - `status` 'completed' | 'failed', required
          - `type` 'apply_patch_call_output', required
          - `created_by` string, nullable
          - `output` string, nullable
        - McpCall: An invocation of a tool on an MCP server.
          - `id` string, required
          - `arguments` string, required
          - `name` string, required
          - `server_label` string, required
          - `type` 'mcp_call', required
          - `approval_request_id` string, nullable
          - `error` string, nullable
          - `output` string, nullable
          - `status` 'in_progress' | 'completed' | 'incomplete' | 'calling' | 'failed', nullable
        - McpListTools: A list of tools available on an MCP server.
          - `id` string, required
          - `server_label` string, required
          - `tools` McpListToolsTool[], required
            - `input_schema` unknown, required
            - `name` string, required
            - `annotations` unknown
            - `description` string, nullable
          - `type` 'mcp_list_tools', required
          - `error` string, nullable
        - McpApprovalRequest: A request for human approval of a tool invocation.
          - `id` string, required
          - `arguments` string, required
          - `name` string, required
          - `server_label` string, required
          - `type` 'mcp_approval_request', required
        - McpApprovalResponse: A response to an MCP approval request.
          - `id` string, required
          - `approval_request_id` string, required
          - `approve` boolean, required
          - `type` 'mcp_approval_response', required
          - `reason` string, nullable
        - ResponseCustomToolCall: A call to a custom tool created by the model.
          - `call_id` string, required
          - `input` string, required
          - `name` string, required
          - `type` 'custom_tool_call', required
          - `id` string, nullable
          - `namespace` string, nullable
        - ResponseCustomToolCallOutputItem: The output of a custom tool call from your code, being sent back to the model.
          - `call_id` string, required
          - `output` union, required
            - string
            - union[]
              - …
          - `type` 'custom_tool_call_output', required
          - `id` string, required
          - `status` 'in_progress' | 'completed' | 'incomplete', required
          - `created_by` string, nullable
        - object
    - union[]
      - union
        - GenericResponseOutputItem: Generic response API output item
          - `type` string, required
          - `id` string, required
          - `status` string, required
          - `role` string, required
          - `content` OutputText[], required
            - `type` string, nullable, required
            - `text` string, nullable, required
            - `annotations` GenericResponseOutputItemContentAnnotation[], nullable, required
              - …
          - `phase` 'commentary' | 'final_answer', nullable
        - OutputCodeInterpreterCall: A code interpreter / code execution call output
          - `type` 'code_interpreter_call', required
          - `id` string, required
          - `code` string, nullable, required
          - `container_id` string, nullable, required
          - `status` 'in_progress' | 'completed' | 'incomplete' | 'failed', required
          - `outputs` OutputCodeInterpreterCallLog[], nullable, required
            - `type` 'logs', required
            - `logs` string, required
        - OutputFunctionToolCall: A tool call to run a function
          - `arguments` string, nullable, required
          - `call_id` string, nullable, required
          - `name` string, nullable, required
          - `type` string, nullable, required
          - `id` string, nullable, required
          - `status` 'in_progress' | 'completed' | 'incomplete', required
          - `phase` 'commentary' | 'final_answer', nullable
        - OutputImageGenerationCall: An image generation call output
          - `type` 'image_generation_call', required
          - `id` string, required
          - `status` 'in_progress' | 'completed' | 'incomplete' | 'failed', required
          - `result` string, nullable, required
        - ResponseFunctionToolCall: A tool call to run a function. See the [function calling guide](https://platform.openai.com/docs/guides/function-calling) for more information.
          - `arguments` string, required
          - `call_id` string, required
          - `name` string, required
          - `type` 'function_call', required
          - `id` string, nullable
          - `namespace` string, nullable
          - `status` 'in_progress' | 'completed' | 'incomplete', nullable
        - ResponseFunctionWebSearch: The results of a web search tool call. See the [web search guide](https://platform.openai.com/docs/guides/tools-web-search) for more information.
          - `id` string, required
          - `action` union, required
            - ActionSearch: Action type "search" - Performs a web search query.
              - …
            - ActionOpenPage: Action type "open_page" - Opens a specific URL from search results.
              - …
            - ActionFind: Action type "find_in_page": Searches for a pattern within a loaded page.
              - …
          - `status` 'in_progress' | 'searching' | 'completed' | 'failed', required
          - `type` 'web_search_call', required
        - CustomToolCallOutputItem: A custom/freeform tool call output item (e.g. apply_patch). Mirrors the ``custom_tool_call`` variant of OpenAI's Responses API output. Unlike ``OutputFunctionToolCall`` which uses ``arguments`` (JSON string), this uses ``input`` (raw string) for the tool payload.
          - `type` 'custom_tool_call', required
          - `call_id` string, required
          - `id` string, nullable
          - `name` string, required
          - `input` string, required
          - `status` 'in_progress' | 'completed' | 'incomplete', nullable
  - `parallel_tool_calls` boolean, nullable
  - `temperature` number, nullable
  - `tool_choice` union
    - 'none' | 'auto' | 'required'
    - ToolChoiceAllowedParam: Constrains the tools available to the model to a pre-defined set.
      - `mode` 'auto' | 'required', required
      - `tools` object[], required
      - `type` 'allowed_tools', required
    - ToolChoiceTypesParam: Indicates that the model should use a built-in tool to generate a response. [Learn more about built-in tools](https://platform.openai.com/docs/guides/tools).
      - `type` 'file_search' | 'web_search_preview' | 'computer' | 'computer_use_preview' | 'computer_use' | 'web_search_preview_2025_03_11' | 'image_generation' | 'code_interpreter', required
    - ToolChoiceFunctionParam: Use this option to force the model to call a specific function.
      - `name` string, required
      - `type` 'function', required
    - ToolChoiceMcpParam: Use this option to force the model to call a specific tool on a remote MCP server.
      - `server_label` string, required
      - `type` 'mcp', required
      - `name` string, nullable
    - ToolChoiceCustomParam: Use this option to force the model to call a specific custom tool.
      - `name` string, required
      - `type` 'custom', required
    - ToolChoiceApplyPatchParam: Forces the model to call the apply_patch tool when executing a tool call.
      - `type` 'apply_patch', required
    - ToolChoiceShellParam: Forces the model to call the shell tool when a tool call is required.
      - `type` 'shell', required
  - `tools` union
    - union[]
      - union
        - FunctionTool: Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling).
          - `name` string, required
          - `parameters` object, nullable
          - `strict` boolean, nullable
          - `type` 'function', required
          - `defer_loading` boolean, nullable
          - `description` string, nullable
        - FileSearchTool: A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search).
          - `type` 'file_search', required
          - `vector_store_ids` string[], required
          - `filters` union
            - ComparisonFilter: A filter used to compare a specified attribute key to a given value using a defined comparison operation.
              - …
            - CompoundFilter: Combine multiple filters using `and` or `or`.
              - …
          - `max_num_results` integer, nullable
          - `ranking_options` RankingOptions: Ranking options for search.
            - `hybrid_search` RankingOptionsHybridSearch: Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled.
              - …
            - `ranker` 'auto' | 'default-2024-11-15', nullable
            - `score_threshold` number, nullable
        - ComputerTool: A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use).
          - `type` 'computer', required
        - ComputerUsePreviewTool: A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use).
          - `display_height` integer, required
          - `display_width` integer, required
          - `environment` 'windows' | 'mac' | 'linux' | 'ubuntu' | 'browser', required
          - `type` 'computer_use_preview', required
        - WebSearchTool: Search the Internet for sources related to the prompt. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search).
          - `type` 'web_search' | 'web_search_2025_08_26', required
          - `filters` Filters: Filters for the search.
            - `allowed_domains` string[], nullable
          - `search_context_size` 'low' | 'medium' | 'high', nullable
          - `user_location` OpenaiTypesResponsesWebSearchToolUserLocation: The approximate location of the user.
            - `city` string, nullable
            - `country` string, nullable
            - `region` string, nullable
            - `timezone` string, nullable
            - `type` 'approximate', nullable
        - Mcp: Give the model access to additional tools via remote Model Context Protocol (MCP) servers. [Learn more about MCP](https://platform.openai.com/docs/guides/tools-remote-mcp).
          - `server_label` string, required
          - `type` 'mcp', required
          - `allowed_tools` union
            - string[]
            - McpAllowedToolsMcpToolFilter: A filter object to specify which tools are allowed.
              - …
          - `authorization` string, nullable
          - `connector_id` 'connector_dropbox' | 'connector_gmail' | 'connector_googlecalendar' | 'connector_googledrive' | 'connector_microsoftteams' | 'connector_outlookcalendar' | 'connector_outlookemail' | 'connector_sharepoint', nullable
          - `defer_loading` boolean, nullable
          - `headers` object, nullable
          - `require_approval` union
            - McpRequireApprovalMcpToolApprovalFilter: Specify which of the MCP server's tools require approval. Can be `always`, `never`, or a filter object associated with tools that require approval.
              - …
            - 'always' | 'never'
          - `server_description` string, nullable
          - `server_url` string, nullable
        - CodeInterpreter: A tool that runs Python code to help generate a response to a prompt.
          - `container` union, required
            - string
            - CodeInterpreterContainerCodeInterpreterToolAuto: Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on.
              - …
          - `type` 'code_interpreter', required
        - ImageGeneration: A tool that generates images using the GPT image models.
          - `type` 'image_generation', required
          - `action` 'generate' | 'edit' | 'auto', nullable
          - `background` 'transparent' | 'opaque' | 'auto', nullable
          - `input_fidelity` 'high' | 'low', nullable
          - `input_image_mask` ImageGenerationInputImageMask: Optional mask for inpainting. Contains `image_url` (string, optional) and `file_id` (string, optional).
            - `file_id` string, nullable
            - `image_url` string, nullable
          - `model` union
            - string
            - 'gpt-image-1' | 'gpt-image-1-mini' | 'gpt-image-1.5'
          - `moderation` 'auto' | 'low', nullable
          - `output_compression` integer, nullable
          - `output_format` 'png' | 'webp' | 'jpeg', nullable
          - `partial_images` integer, nullable
          - `quality` 'low' | 'medium' | 'high' | 'auto', nullable
          - `size` '1024x1024' | '1024x1536' | '1536x1024' | 'auto', nullable
        - LocalShell: A tool that allows the model to execute shell commands in a local environment.
          - `type` 'local_shell', required
        - FunctionShellTool: A tool that allows the model to execute shell commands.
          - `type` 'shell', required
          - `environment` union
            - ContainerAuto
              - …
            - LocalEnvironment
              - …
            - ContainerReference
              - …
        - CustomTool: A custom tool that processes input using a specified format. Learn more about [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools)
          - `name` string, required
          - `type` 'custom', required
          - `defer_loading` boolean, nullable
          - `description` string, nullable
          - `format` union
            - Text: Unconstrained free-form text.
              - …
            - Grammar: A grammar defined by the user.
              - …
        - NamespaceTool: Groups function/custom tools under a shared namespace.
          - `description` string, required
          - `name` string, required
          - `tools` union[], required
            - union
              - …
          - `type` 'namespace', required
        - ToolSearchTool: Hosted or BYOT tool search configuration for deferred tools.
          - `type` 'tool_search', required
          - `description` string, nullable
          - `execution` 'server' | 'client', nullable
          - `parameters` unknown
        - WebSearchPreviewTool: This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search).
          - `type` 'web_search_preview' | 'web_search_preview_2025_03_11', required
          - `search_content_types` string[], nullable
          - `search_context_size` 'low' | 'medium' | 'high', nullable
          - `user_location` OpenaiTypesResponsesWebSearchPreviewToolUserLocation: The user's location.
            - `type` 'approximate', required
            - `city` string, nullable
            - `country` string, nullable
            - `region` string, nullable
            - `timezone` string, nullable
        - ApplyPatchTool: Allows the assistant to create, delete, or update files using unified diffs.
          - `type` 'apply_patch', required
    - ResponseFunctionToolCall[]
      - `arguments` string, required
      - `call_id` string, required
      - `name` string, required
      - `type` 'function_call', required
      - `id` string, nullable
      - `namespace` string, nullable
      - `status` 'in_progress' | 'completed' | 'incomplete', nullable
    - object[]
  - `top_p` number, nullable
  - `max_output_tokens` integer, nullable
  - `previous_response_id` string, nullable
  - `reasoning` object, nullable
  - `status` string, nullable
  - `text` union
    - ResponseTextConfigParam: Configuration options for a text response from the model. Can be plain text or structured JSON data. Learn more: - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs)
      - `format` union
        - ResponseFormatText: Default response format. Used to generate text responses.
          - `type` 'text', required
        - ResponseFormatTextJSONSchemaConfigParam: JSON Schema response format. Used to generate structured JSON responses. Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs).
          - `name` string, required
          - `schema` object, required
          - `type` 'json_schema', required
          - `description` string
          - `strict` boolean, nullable
        - ResponseFormatJSONObject: JSON object response format. An older method of generating JSON responses. Using `json_schema` is recommended for models that support it. Note that the model will not generate JSON without a system or user message instructing it to do so.
          - `type` 'json_object', required
      - `verbosity` 'low' | 'medium' | 'high', nullable
    - object
  - `truncation` 'auto' | 'disabled', nullable
  - `usage` ResponseAPIUsage
    - `input_tokens` integer, required
    - `input_tokens_details` InputTokensDetails
      - `audio_tokens` integer, nullable
      - `cached_tokens` integer
      - `cached_tokens_details` CachedTokensDetails
        - `text_tokens` integer, nullable
        - `audio_tokens` integer, nullable
        - `image_tokens` integer, nullable
      - `image_tokens` integer, nullable
      - `text_tokens` integer, nullable
      - `video_tokens` integer, nullable
    - `output_tokens` integer, required
    - `output_tokens_details` OutputTokensDetails
      - `audio_tokens` integer, nullable
      - `reasoning_tokens` integer, nullable
      - `text_tokens` integer, nullable
    - `total_tokens` integer, required
    - `cost` number, nullable
  - `user` string, nullable
  - `store` boolean, nullable

## Changes

- **2026-10-21** `f2fb14eab3f5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/sea-lion/apis/litellm-api/changes/responses/post.md)

---

[API](https://skmtc.dev/sea-lion/apis/litellm-api.md) · [All operations](https://skmtc.dev/sea-lion/apis/litellm-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sea-lion/apis/litellm-api/revisions/f2fb14eab3f5?raw)