--- title: "Retrieve a response" method: GET path: "/v1/responses/{response_id}" tags: ["Responses"] --- # Retrieve a response `GET /v1/responses/{response_id}` Retrieve a response by its ID. Use this to poll the status of background tasks. ## Path parameters - `response_id` string, required ## Response `200` The response object - ResponsesResponse — Non-streaming response returned when stream is false - `created_at` integer, required - `error` ErrorInfo - `code` string - `message` string, required - `type` string - `id` string, required - `model` string, required - `object` 'response', required — Object type in API responses - `output` OutputItem[], required - union — One item in the response output: an assistant message, retrieved tool results, or a record of a tool call. - MessageOutputItem - `content` ContentPart[], required - `annotations` Annotation[] - `end_index` integer - `start_index` integer - `title` string - `type` string - `url` string - `text` string, required - `type` 'output_text', required — Type of a content part - `id` string, required - `role` 'assistant', required — Role in a message - `status` 'completed' | 'failed' | 'in_progress' | 'queued' | 'cancelled' | 'requires_action', required — Status of a response or output item - `type` 'message', required - SearchResultsOutputItem - `queries` string[] - `results` SearchResult[], required - `date` string - `id` integer, required - `last_updated` string - `snippet` string, required - `source` 'web' — Source of search results - `title` string, required - `url` string, required - `type` 'search_results', required - FetchUrlResultsOutputItem - `contents` UrlContent[], required - `snippet` string, required — The fetched content snippet - `title` string, required — The title of the page - `url` string, required — The URL from which content was fetched - `type` 'fetch_url_results', required - FunctionCallOutputItem - `arguments` string, required — JSON string of arguments - `call_id` string, required — Correlates with function_call_output input - `id` string, required - `name` string, required - `status` 'completed' | 'failed' | 'in_progress' | 'queued' | 'cancelled' | 'requires_action', required — Status of a response or output item - `thought_signature` string — Base64-encoded opaque signature for thinking models - `type` 'function_call', required - McpListToolsOutputItem — Tools discovered on one external MCP server at boot. Matches OpenAI's mcp_list_tools item. - `error` string - `id` string, required - `server_label` string, required - `tools` McpToolDef[], required - `description` string - `input_schema` object, required — The server's JSON Schema for the tool, passed through unmodified. - `name` string, required - `type` 'mcp_list_tools', required - McpCallOutputItem — One tool call executed against an external MCP server, modeled on OpenAI's mcp_call item. - `arguments` string, required — JSON-encoded arguments the model passed. - `error` string, nullable — The failure string when the call failed (also returned to the model in-band); null on success, matching OpenAI's mcp_call. - `id` string, required - `name` string, required - `output` string — Tool output text; empty when the call failed. - `server_label` string, required - `type` 'mcp_call', required - SkillLoadedOutputItem — Per-call result emitted by the `load_skill` tool. Only the resolved skill name is surfaced here; the skill body itself lives in the function_call_output input item the model consumes on its next turn. - `name` string, required — Name of the skill that was loaded. - `type` 'skill_loaded', required - AdvisorResultOutputItem — Preview API. Advisor tool invocation emitted in `response.output[]`. The advisor result is server-side guidance consumed by the agent loop; it is not a client-executable function call. - `type` 'advisor_result', required - `call_id` string, required - `status` 'completed' | 'failed' | 'in_progress' | 'queued' | 'cancelled' | 'requires_action', required — Status of a response or output item - `arguments` string — Raw JSON arguments the executor passed to the advisor tool. - `question` string — Parsed advisor question when present in arguments. - `advice` string — Guidance returned by the advisor model. - `error_code` string — Non-fatal advisor error code when the advisor call failed. - `error_message` string — Non-fatal advisor error message when the advisor call failed. - SandboxResultsOutputItem — Sandbox tool results emitted in `response.output[]`. Cost is aggregated into `Usage.tool_calls_details.sandbox.cost_usd`; this item does not carry per-execution cost. - `type` 'sandbox_results', required - `call_id` string, required - `language` 'python' | 'bash', required - `code` string, required - `container_id` string - `results` SandboxResult[], required - `stdout` string, required - `stderr` string, required - `exit_code` integer, required - `duration_ms` integer, required - `status` 'in_progress' | 'completed' | 'failed' | 'timed_out', required - `status` 'in_progress' | 'completed' | 'failed' | 'timed_out', required - SandboxWriteFileOutputItem — Per-invocation result of the `write` tool inside the sandbox. - `type` 'sandbox_write_file', required - `call_id` string, required - `file_path` string, required - `size_bytes` integer - `error` string - SandboxReadFileOutputItem — Per-invocation result of the `read` tool inside the sandbox. - `type` 'sandbox_read_file', required - `call_id` string, required - `file_path` string, required - `content` string - `start_line` integer - `total_lines` integer - `error` string - SandboxEditFileOutputItem — Per-invocation result of the `edit` tool inside the sandbox. - `type` 'sandbox_edit_file', required - `call_id` string, required - `file_path` string - `message` string - `error` string - SandboxGrepOutputItem — Per-invocation result of the `grep` tool inside the sandbox. - `type` 'sandbox_grep', required - `call_id` string, required - `files` string[] - `count` integer - `truncated` boolean - `error` string - SandboxGlobOutputItem — Per-invocation result of the `glob` tool inside the sandbox. - `type` 'sandbox_glob', required - `call_id` string, required - `files` string[] - `count` integer - `truncated` boolean - `error` string - SandboxApplyPatchOutputItem — Per-invocation result of the `apply_patch` tool inside the sandbox. - `type` 'sandbox_apply_patch', required - `call_id` string, required - `added` string[] - `modified` string[] - `deleted` string[] - `error` string - ShareFileOutputItem — Result of one `share_file` tool call. On success, file_id and filename identify a sandbox file downloadable at url. - `type` 'share_file', required - `call_id` string, required - `file_id` string - `filename` string - `size_bytes` integer - `url` string — Relative download path, /v1/responses/{id}/files/{file_id}/content. - `error` string - UnknownOutputItem — Forward-compat fallback for proto OutputItem variants the gateway does not yet have a typed schema for. - `type` 'unknown', required - `item_name` string, required - `payload` object, required - `status` 'completed' | 'failed' | 'in_progress' | 'queued' | 'cancelled' | 'requires_action', required — Status of a response or output item - `usage` ResponsesUsage - `cost` ResponsesCost - `cache_creation_cost` number, double - `cache_read_cost` number, double - `currency` 'USD', required — Currency code for cost values - `input_cost` number, double, required - `output_cost` number, double, required - `tool_calls_cost` number, double - `total_cost` number, double, required - `input_tokens` integer, required - `input_tokens_details` object - `cache_creation_input_tokens` integer - `cache_read_input_tokens` integer - `output_tokens` integer, required - `tool_calls_details` object - `total_tokens` integer, required - `background` boolean — Whether the response was created in background mode. - `previous_response_id` string, nullable — ID of the previous response in the chain, when the response was created with previous_response_id. - `store` boolean — Whether the response is stored and visible to later retrieve calls. A response created with store=false can still be used as a previous_response_id continuation source. ## Other responses - `404` — Response not found ## Changes - **2026-07-17** `bcca72d3b564` — 1 breaking, 1 info - added `#/components/schemas/SkillLoadedOutputItem, #/components/schemas/AdvisorResultOutputItem, #/components/schemas/SandboxResultsOutputItem, #/components/schemas/SandboxWriteFileOutputItem, #/components/schemas/SandboxReadFileOutputItem, #/components/schemas/SandboxEditFileOutputItem, #/components/schemas/SandboxGrepOutputItem, #/components/schemas/SandboxGlobOutputItem, #/components/schemas/SandboxApplyPatchOutputItem, #/components/schemas/ShareFileOutputItem, #/components/schemas/UnknownOutputItem` to the `output/items/` response property `oneOf` list for the response status `200` - added `skill_loaded, advisor_result, sandbox_results, sandbox_write_file, sandbox_read_file, sandbox_edit_file, sandbox_grep, sandbox_glob, sandbox_apply_patch, share_file, unknown` discriminator mapping keys to the `output/items/` response property for the response status `200` - **2026-07-15** `25e39510ae77` — 2 info - added the optional property `previous_response_id` to the response with the `200` status - added the optional property `store` to the response with the `200` status - …earlier changes not shown [Full history](https://skmtc.dev/perplexityai/apis/perplexity-ai-api/changes/v1/responses/:response_id/get.md) --- [API](https://skmtc.dev/perplexityai/apis/perplexity-ai-api.md) · [All operations](https://skmtc.dev/perplexityai/apis/perplexity-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/perplexityai/perplexity-ai-api/revisions/bcca72d3b564/schema)