---
title: "Get Responses Endpoint"
method: GET
path: "/v1/responses/{response_id}"
tags: ["Responses"]
---

# Get Responses Endpoint

`GET /v1/responses/{response_id}`

## Request

- Base URL: `https://api.pharia.example.com`
- URL: `https://api.pharia.example.com/v1/responses/{response_id}`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/aleph-alpha/apis/stateful-responses/docs/v1/responses/:response_id/get.ts> (a function with typed inputs; its response is checked against the schema)

Handle GET /v1/responses/{response_id} - retrieve stored response.

Supports both streaming and non-streaming retrieval.
For req_* IDs (background requests), checks pending status first.

## Path parameters

- `response_id` string, required

## Query parameters

- `stream` boolean
- `include_deleted` boolean: Include soft-deleted responses. Admin-only; returns 403 for non-admin callers.

## Response `200`

When `stream=false` (default), returns a JSON response. When `stream=true`, returns Server-Sent Events.

- ResponseResponse: Response from Open Responses API. All fields marked as required in the OpenResponses spec are present here. Nullable fields default to None and are serialized as null (not omitted).
  - `id` string, required: The unique ID of the response.
  - `object` string: The object type.
  - `created_at` integer, required: The Unix timestamp (in seconds) for when the response was created.
  - `completed_at` integer, nullable: The Unix timestamp (in seconds) for when the response was completed.
  - `status` string: The status of the response.
  - `incomplete_details` object, nullable: Details about why the response was incomplete, if applicable.
  - `model` string, required: The model that generated this response.
  - `previous_response_id` string, nullable: The ID of the previous response in the conversation chain, if any.
  - `instructions` string, nullable: Additional instructions used to guide the model for this response.
  - `output` union[], required: The output items generated by the model.
    - union: Input item type, used to determine the input item schema
      - InputItemMessage: Input item for structured input. Per Open Responses spec, supports: - message type: role + content - function_call type: call_id + name + arguments (for history) - function_call_output type: call_id + output (tool results) Fields: - id: unique identifier (optional on input, populated on output) - status: in_progress, completed, incomplete (optional on input)
        - `type` 'message', required
        - `id` string, nullable: Unique identifier for messages
        - `status` 'in_progress' | 'completed' | 'incomplete', nullable
        - `role` string, nullable
        - `content` union
          - string
          - string[]
          - ContentItem[]
            - `type` string
            - `text` string, required
            - `annotations` object[]
              - …
          - union[]
            - union: A typed input content part (input_text/input_image).
              - …
      - InputItemReasoning: Input item for reasoning type messages.
        - `type` 'reasoning', required
        - `id` string, required: Unique identifier for reasoning messages
        - `status` 'in_progress' | 'completed' | 'incomplete', nullable
        - `role` string, nullable
        - `content` union
          - string
          - string[]
          - ContentItem[]
            - `type` string
            - `text` string, required
            - `annotations` object[]
              - …
          - union[]
            - union: A typed input content part (input_text/input_image).
              - …
        - `summary` ReasoningSummaryItem[]: Reasoning summary items returned by the downstream service.
          - `type` 'summary_text', required
          - `text` string, required
      - InputItemFunctionCall: Input item for function call (history reconstruction).
        - `type` 'function_call', required
        - `id` string, required: Unique identifier for the function call
        - `call_id` string, required
        - `status` 'in_progress' | 'completed' | 'incomplete', nullable
        - `name` string, nullable
        - `arguments` string, nullable
      - InputItemFunctionCallOutput: Input item for function call (history reconstruction).
        - `type` 'function_call_output', required
        - `call_id` string, required
        - `id` string, nullable: Unique identifier for the function call output
        - `status` 'in_progress' | 'completed' | 'incomplete', nullable
        - `output` string, nullable
      - InputItemShellCall: Input item for shell tool call (history reconstruction).
        - `type` 'shell_call', required
        - `id` string, required: Unique identifier for the shell call
        - `call_id` string, required
        - `status` 'in_progress' | 'completed' | 'incomplete', nullable
        - `name` string, nullable
        - `arguments` string, nullable
      - InputItemShellCallOutput: Input item for shell tool call output (history reconstruction).
        - `type` 'shell_call_output', required
        - `call_id` string, required
        - `id` string, nullable: Unique identifier for the shell call output
        - `status` 'in_progress' | 'completed' | 'incomplete', nullable
        - `output` string, nullable
      - InputItemMcpApprovalRequest
        - `type` 'mcp_approval_request', required
        - `id` string, required: Unique identifier for the approval request
        - `name` string, nullable
        - `server_label` string, nullable
        - `arguments` string, nullable
      - InputItemMcpApprovalResponses
        - `type` 'mcp_approval_response', required
        - `id` string, required: Unique identifier for the approval response
        - `approval_request_id` string, required
        - `approve` boolean, required
        - `reason` string, nullable: Why the call was not approved. Filled in by the service when the user sent a new message instead of answering.
        - `name` string, nullable
        - `arguments` string, nullable
      - InputItemMcpListTools
        - `type` 'mcp_list_tools', required
        - `id` string, required: Unique identifier for the MCP list tools
        - `server_label` string, nullable
        - `tools` union
          - object
          - unknown[]
            - unknown
        - `error` string, nullable
      - InputItemMcpCall
        - `type` 'mcp_call', required
        - `id` string, required: Unique identifier for the MCP call
        - `name` string, required
        - `arguments` string, nullable
        - `server_label` string, nullable
        - `output` string, nullable
        - `error` McpToolExecutionError: The tool's own error, in the shape the OpenAI SDK's mcp_call uses.
          - `type` 'mcp_tool_execution_error'
          - `content` string, required
      - InputItemFileSearchCall: Hosted file-search call/result output item. Mirrors OpenAI/OpenResponses ``file_search_call`` enough for upstream PydanticAI clients to map it as a native tool call while allowing Sherlock result extensions in ``results``.
        - `type` 'file_search_call', required
        - `id` string: Unique identifier for the file search call
        - `status` 'in_progress' | 'searching' | 'completed' | 'incomplete' | 'failed', required
        - `queries` string[]
        - `results` object[], nullable
      - InputItemWebSearchCall: Hosted web-search call/result output item. Mirrors OpenAI/OpenResponses ``web_search_call`` enough for upstream clients to map it as a native tool call while embedding the LinkUp results directly in ``results``.
        - `type` 'web_search_call', required
        - `id` string: Unique identifier for the web search call
        - `status` 'in_progress' | 'searching' | 'completed' | 'failed', required
        - `action` object, nullable: How the model invoked the tool, e.g. {"type": "search", "query": ...}
        - `results` object[], nullable
      - InputItemCompaction: Compaction item — opaque summary blob, mirrors OpenAI's `/v1/responses/compact` shape.
        - `type` 'compaction', required
        - `id` string, nullable: Identifier of the compaction item.
        - `encrypted_content` string, required: The (potentially encrypted) content of the compaction summary.
  - `error` object, nullable: The error that occurred, if the response failed.
  - `tools` union[]: The tools available to the model during response generation.
    - union: Tool type, used to determine the tool schema
      - Function: Function tool definition (client-executed).
        - `type` 'function', required: Tool type, must be 'function'
        - `name` string, required: Name of the function tool
        - `parameters` object, nullable
        - `strict` boolean
        - `description` string, nullable
      - MCPTool: MCP hosted tool definition (server-executed).
        - `type` 'mcp', required: Tool type, must be 'mcp'
        - `server_url` string, required: URL for the server to call when executing the tool
        - `require_approval` 'always' | 'never': Whether the server requires approval before calling the tool. 'always' means approval is required, 'never' means no approval needed.
        - `server_label` string, required: Label for the tool to be used by the server
        - `allowed_tools` union: Optional dict or array of allowed tools that the server can call, keyed by tool name. This can be used to specify which tools the server is allowed to call, and can include additional configuration for each tool.
          - object
          - string[]
        - `authorization` string, nullable: Optional authorization information for the server to use when calling the tool. This can include API keys, tokens, or other credentials needed to access the tool.
        - `headers` object, nullable: Optional headers to include when the server calls the tool. This can be used to provide additional context or information needed for the tool execution.
        - `server_description` string, nullable: Optional description for the server to understand the tool's purpose
        - `on_unavailable` 'fail' | 'skip': What to do when the server's tools cannot be listed. 'fail' fails the response. 'skip' records the error on the mcp_list_tools item and answers without this server's tools. Not part of the OpenAI API.
      - FileSearchTool: Aleph/OpenResponses hosted file-search tool definition. A single hosted tool can scope search/read to either uploaded documents (``attachments``) and/or whole knowledge-base stores (``search_store_ids``).
        - `type` 'file_search', required: Tool type, must be 'file_search'
        - `attachments` FileSearchAttachment[]
          - `searchStoreId` string, required
          - `fileId` string, required
          - `documentId` string, required
          - `fileName` string, required
        - `citations` boolean
        - `search_store_ids` string[]
      - ShellTool: Shell tool definition (server-executed in a containerized environment).
        - `type` 'shell', required: Tool type, must be 'shell'
        - `environment` ShellEnvironment, required: Environment configuration for a shell tool.
          - `type` string, required: Environment type (e.g. 'container_auto')
          - `skills` SkillReference[]: Skills available in the shell environment
            - `type` 'skill_reference', required: Type, must be 'skill_reference'
            - `skill_id` string, required: Identifier of the skill
            - `version` integer, nullable: Optional version of the skill to use
      - WebSearchTool: Hosted web-search tool definition (LinkUp-backed, server-executed). Exposes agentic ``web_search`` and ``fetch_url`` function tools to the model; both are executed server-side against the LinkUp API. ``depth`` maps directly onto LinkUp's search depth — no translation layer.
        - `type` 'web_search', required: Tool type, must be 'web_search'
        - `depth` 'fast' | 'standard' | 'deep': LinkUp search depth: 'fast', 'standard' or 'deep'
        - `filters` WebSearchFilters: Domain filters for hosted web search.
          - `allowed_domains` string[]: Restrict the search to these domains
          - `blocked_domains` string[]: Exclude these domains from the search
  - `tool_choice` union: Controls which tool the model should use, if any.
    - 'auto' | 'required' | 'none'
    - object
  - `truncation` string, nullable: How the input was truncated when it exceeded the model context window.
  - `parallel_tool_calls` boolean: Whether the model was allowed to call multiple tools in parallel.
  - `text` object, nullable: Configuration options for text output.
  - `top_p` number, nullable: The nucleus sampling parameter used for this response.
  - `temperature` number, nullable: The sampling temperature used for this response.
  - `presence_penalty` number, nullable: Penalizes new tokens based on whether they appear in the text so far.
  - `frequency_penalty` number, nullable: Penalizes new tokens based on their frequency in the text so far.
  - `top_logprobs` integer, nullable: Number of most likely tokens returned at each position.
  - `reasoning` object, nullable: Reasoning configuration and outputs produced for this response.
  - `usage` UsageInfo: Token usage information.
    - `input_tokens` integer, required
    - `output_tokens` integer, required
    - `total_tokens` integer, required
  - `max_output_tokens` integer, nullable: The maximum number of tokens the model was allowed to generate.
  - `max_tool_calls` integer, nullable: The maximum number of tool calls the model was allowed to make.
  - `store` boolean: Whether this response was stored for later retrieval.
  - `background` boolean: Whether this request was run in the background.
  - `service_tier` string, nullable: The service tier used for this response.
  - `metadata` object, nullable: Key-value pairs for storing additional information about the response.
  - `prompt_cache_key` string, nullable: A key used to read from or write to the prompt cache.
  - `conversation` ConversationRef: Minimal conversation reference embedded in response objects.
    - `id` string, required
  - `safety_identifier` string, nullable: A stable identifier used for safety monitoring and abuse detection.
  - `trace_id` string, nullable: 32-character lowercase hex OpenTelemetry trace ID for the generation request. Server-populated from the active span when the generated response is completed. Null on incomplete, failed, cancelled, in-progress, synthetic, historical, and tracing-disabled responses.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `413`: Content Too Large
- `422`: Validation errors are returned as 400, not 422. This entry exists because FastAPI generates it automatically.
- `425`: Too Early
- `500`: Internal Server Error
- `501`: Not Implemented
- `502`: Bad Gateway
- `504`: Gateway Timeout

---

[API](https://skmtc.dev/aleph-alpha/apis/stateful-responses.md) - [All operations](https://skmtc.dev/aleph-alpha/apis/stateful-responses/llms.txt) - [OpenAPI document](https://skmtc.dev/aleph-alpha/apis/stateful-responses/revisions/2747297acb54?raw)