---
title: "Retrieve a previously generated response."
method: GET
path: "/v1/responses/{response_id}"
tags: ["v1"]
---

# Retrieve a previously generated response.

`GET /v1/responses/{response_id}`

## Path parameters

- `response_id` string, required

## Response `200`

Success

- ModelResponse — The response body for `/v1/responses` endpoint.
  - `background` boolean, required — OpenResponses compatibility fields. Not used at the moment. Just for OpenResponses compatibility. Whether to process the response asynchronously in the background.
  - `completed_at` integer, nullable — The Unix timestamp (in seconds) for the response completion time. Only set when the response is completed.
  - `created_at` integer, required — The Unix timestamp (in seconds) for the response creation time.
  - `error` unknown
  - `frequency_penalty` number, float, required — (NOT SUPPORTED in Responses API) Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim.
  - `id` string, required — Unique ID of the response.
  - `incomplete_details` union — Details about why a response is incomplete.
    - object
      - `reason` 'max_output_tokens', required
    - object
      - `reason` 'max_prompt_tokens', required
    - object
      - `reason` 'max_time_limit', required
  - `instructions` string, nullable — A system (or developer) message inserted into the model's context.
  - `max_output_tokens` integer, nullable — Max number of tokens that can be generated in a response. This includes both output and reasoning tokens.
  - `max_tool_calls` integer, nullable — The maximum number of tool calls allowed for this response.
  - `metadata` unknown, required
  - `model` string, required — Model name used to generate the response.
  - `object` string, required — The object type of this resource. Always set to `response`.
  - `output` ModelOutput[], required — The response generated by the model.
    - union
      - OutputMessage — An output message from the model.
        - `content` OutputMessageContent[], required — Content of the output message.
          - union
            - object — Text output.
              - …
            - object — Refusal.
              - …
        - `id` string — The unique ID of the output message.
        - `role` string, required — The role of the output message, which can be `assistant` or `tool`.
        - `status` string — Status of the item. One of `completed`, `in_progress` or `incomplete`.
        - `type` string, required — The type of the output message, which is always `message`.
      - FunctionToolCall — A tool call to run a function.
        - `arguments` string, required — The arguments to pass to the function, as a JSON string.
        - `call_id` string, required — The unique ID of the function tool call generated by the model.
        - `id` string — The unique ID of the function tool call.
        - `name` string, required — The name of the function.
        - `status` string — Status of the item. One of `completed`, `in_progress` or `incomplete`.
        - `type` string, required — The type of the function tool call, which can be `"function_call"` for client-side tool calls, and `"web_search_call"` or `"x_search_call"` or `"code_interpreter_call"` or `"mcp_call"` for server-side tool calls.
      - Reasoning — The reasoning done by the model.
        - `content` ReasoningText[] — The reasoning text contents.
          - `text` string, required — Reasoning done by the model.
          - `type` string, required — The type of the object, which is always `reasoning_text`.
        - `encrypted_content` string, nullable — The enrypted reasoning. Returned when `reasoning.encrypted_content` is passed in `include`.
        - `id` string — The unique ID of the reasoning content.
        - `status` string — Status of the item. One of `completed`, `in_progress` or `incomplete`.
        - `summary` SummaryText[], required — The summarized reasoning text contents.
          - `text` string, required — Summary of the reasoning done by the model.
          - `type` string, required — The type of the object, which is always `summary_text`.
        - `type` string, required — The type of the object, which is always `reasoning`.
      - WebSearchCall — The output of a web search tool call.
        - `action` union, required
          - object — Action type "search" - Performs a web search query.
            - `query` string, required — The search query.
            - `sources` WebSearchSource[] — The sources used in the search.
              - …
            - `type` 'search', required
          - object — Action type "open_page" - Opens a specific URL from search results.
            - `type` 'open_page', required
            - `url` string, required — The URL of the page to open.
          - object — Action type "find_in_page": Searches for a pattern within a loaded page. Wire shape mirrors OpenAI's `ActionFind` so the OpenAI Python SDK's typed `web_search_call.action` parses correctly — note the `find_in_page` tag (not `find`) and the flat `url` (not nested under a `source` field).
            - `pattern` string, required — The pattern or text to search for within the page.
            - `type` 'find_in_page', required
            - `url` string, required — The URL of the page being searched within.
        - `id` string — The unique ID of the web search tool call.
        - `status` string — The status of the web search tool call.
        - `type` string, required — The type of the web search tool call. Always `web_search_call`.
      - FileSearchCall — The output of a web search tool call.
        - `id` string — The unique ID of the file search tool call.
        - `queries` string[], required — The queries used to search for files.
        - `results` FileSearchResult[], required — The results of the file search tool call.
          - `file_id` string, required — The file ID of the file search result.
          - `filename` string, required — The filename of the file search result.
          - `score` number, double — The score of the file search result. Proto3 omits float fields with value 0.0; default to 0.0 when absent.
          - `text` string, required — The text of the file search result.
        - `status` string — The status of the file search tool call.
        - `type` string, required — The type of the file search tool call. Always `file_search_call`.
      - CodeInterpreterCall — The output of a code interpreter tool call.
        - `code` string — The code of the code interpreter tool call.
        - `id` string — The unique ID of the code interpreter tool call.
        - `outputs` CodeInterpreterOutput[], required — The outputs of the code interpreter tool call.
          - union
            - object — The output of the code interpreter tool call.
              - …
            - object — The error of the code interpreter tool call.
              - …
        - `status` string — The status of the code interpreter tool call.
        - `type` string, required — The type of the code interpreter tool call. Always `code_interpreter_call`.
      - McpCall — The output of a MCP tool call.
        - `arguments` string, required — A JSON string of the arguments passed to the tool.
        - `error` string — The error message of the MCP tool call.
        - `id` string — The unique ID of the MCP tool call.
        - `name` string, required — The name of the tool that was run.
        - `output` string, required — The output of the MCP tool call.
        - `server_label` string, required — The label of the MCP server running the tool.
        - `status` string — The status of the MCP tool call.
        - `type` string, required — The type of the MCP tool call. Always `mcp_call`.
      - CustomToolCall — The output of a custom tool call.
        - `call_id` string, required — The unique ID of the function tool call generated by the model.
        - `id` string, required — The status of the custom tool call.
        - `input` string — The unique ID of the custom tool call,
        - `name` string, required — An identifier used to map this custom tool call to a tool call output.
        - `status` string — Status of the item. One of `completed`, `in_progress` or `incomplete`.
        - `type` string, required — The input for the custom tool call generated by the model.
      - ShellCall — A shell command call emitted by the model for local execution.
        - `action` ShellCallAction, required — The shell commands and limits that describe how to run the tool call.
          - `commands` string[], required — The commands to run.
          - `max_output_length` integer, nullable — Optional maximum number of characters to return from each command.
          - `timeout_ms` integer, nullable — Optional timeout in milliseconds for the commands.
          - `type` string, nullable — The type of the action, which is always `exec`.
        - `call_id` string, required — The unique ID of the shell tool call generated by the model.
        - `environment` ShellEnvironment — The environment configuration for a shell tool.
          - `skills` LocalShellSkill[] — An optional list of skills available in the local environment.
            - `description` string, required — A description of what the skill does.
            - `name` string, required — The name of the skill.
            - `path` string, required — The path to the directory containing the skill (with a SKILL.md file).
          - `type` string, required — The type of the environment. Currently only `local` is supported.
        - `id` string — The unique ID of the shell call item.
        - `status` string — Status of the item. One of `completed`, `in_progress` or `incomplete`.
        - `type` string, required — The type of the output item, which is always `shell_call`.
      - ImageGenerationCall — The output of an image generation tool call.
        - `id` string — The unique ID of the image generation tool call.
        - `prompt` string, nullable — The prompt used to generate the image.
        - `result` string, nullable — The generated image encoded in base64 (OpenAI-compatible: bare base64, no data-URL prefix), or `null` while the call is still in progress or has failed. The image format can be determined from the decoded magic bytes (typically JPEG or PNG).
        - `status` string — The status of the image generation tool call. One of `in_progress`, `generating`, `completed` or `failed`.
        - `type` 'image_generation_call', required — Type tag for [`ImageGenerationCall`]. Serializes as `"image_generation_call"`. A single-variant enum rather than a `String`: `ImageGenerationCall` lives in the untagged `ModelOutput` / `ModelInputPart` enums and every other field is defaulted or optional, so with a plain `String` type field the struct would match *any* JSON object carrying a `type` key — swallowing `function_call_output` (and similar) input items before their own variants are tried.
  - `parallel_tool_calls` boolean, required — Whether to allow the model to run parallel tool calls.
  - `presence_penalty` number, float, required — (NOT SUPPORTED in Responses API) Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics.
  - `previous_response_id` string, nullable — The ID of the previous response from the model.
  - `prompt_cache_key` string, nullable — The cache key used for the prompt for routing to the correct engine.
  - `reasoning` ReasoningConfiguration
    - `effort` string, nullable — Constrains how hard a reasoning model thinks before responding. Only supported by `grok-4.3`. Possible values are `none` (disables reasoning completely), `low` (this is the default if not specified), `medium` and `high` (uses the most reasoning tokens).
    - `generate_summary` string, nullable — Only included for compatibility.
    - `summary` string, nullable — A summary of the model's reasoning process. Possible values are `auto`, `concise` and `detailed`. Only included for compatibility. The model shall always return `detailed`.
  - `safety_identifier` string, nullable — A stable identifier used to help detect users of your application that may be violating xAI's usage policies.
  - `service_tier` 'default' | 'priority', required — Processing tier for a request. Determines scheduling priority and billing.
  - `status` string, required — Status of the response. One of `completed`, `in_progress` or `incomplete`.
  - `store` boolean, required — Whether to store the input message(s) and model response for later retrieval.
  - `temperature` number, float, nullable — What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.
  - `text` ModelResponseConfiguration, required
    - `format` union — Response format parameter for structured outputs.
      - object — Specify text response format, always `"text"`.
        - `type` 'text', required
      - object — Specify json_object response format, always `json_object`. Used for backward compatibility. Prefer to use `"json_schema"` instead of this.
        - `type` 'json_object', required
      - object — Specify json_schema response format with a given schema. Type is always `"json_schema"`.
        - `description` string, nullable — Only included for compatibility.
        - `name` string, nullable — Only included for compatibility.
        - `schema` unknown, required
        - `strict` boolean, nullable — Only included for compatibility.
        - `type` 'json_schema', required
  - `tool_choice` union, required — Parameter to control how model chooses the tools.
    - string — Controls tool access by the model. `"none"` makes model ignore tools, `"auto"` let the model automatically decide whether to call a tool, `"required"` forces model to pick a tool to call.
    - object
      - `name` string, required — Name of the function to use.
      - `type` string, required — Type is always `"function"`.
  - `tools` ModelTool[], required — A list of tools the model may call in JSON-schema. Currently, only functions and web search are supported as tools. A max of 128 tools are supported.
    - union — Definition of one tool that the model can call.
      - object — A function that the model can call.
        - `description` string, nullable — A description of the function to indicate to the model when to call it.
        - `name` string, required — The name of the function. If the model calls the function, this name is used in the response.
        - `parameters` unknown, required
        - `strict` boolean, nullable — Not supported. Only maintained for compatibility reasons.
        - `type` 'function', required
      - object — Search X.
        - `allowed_x_handles` string[], nullable — List of X Handles of the users from whom to consider the posts. Note: This parameter cannot be set with `excluded_x_handles`.
        - `enable_image_understanding` boolean, nullable — Enable image understanding during X search.
        - `enable_video_understanding` boolean, nullable — Enable video understanding during X search.
        - `excluded_x_handles` string[], nullable — List of X Handles of the users from whom to exclude the posts. Note: This parameter cannot be set with `allowed_x_handles`.
        - `from_date` string, date, nullable — Date from which to consider the results in ISO-8601 YYYY-MM-DD. See <https://en.wikipedia.org/wiki/ISO_8601>.
        - `to_date` string, date, nullable — Date up to which to consider the results in ISO-8601 YYYY-MM-DD. See <https://en.wikipedia.org/wiki/ISO_8601>.
        - `type` 'x_search', required
      - object — Generate images from text prompts.
        - `action` string, nullable — Which image capabilities to expose to the model. One of `auto` (the default; both generation and editing), `generate` (text-to-image only), or `edit` (image editing only).
        - `type` 'image_generation', required
      - object — Search the knowledge bases.
        - `filters` unknown
        - `max_num_results` integer, nullable
        - `ranking_options` unknown
        - `type` 'file_search', required
        - `vector_store_ids` string[], required — List of vector store IDs to search within.
      - object — Execute code.
        - `container` unknown
        - `type` 'code_interpreter', required
      - object — A remote MCP server to use.
        - `allowed_tools` string[], nullable
        - `authorization` string, nullable
        - `connector_id` string, nullable
        - `headers` object, nullable
        - `require_approval` string, nullable
        - `server_description` string, nullable
        - `server_label` string, required
        - `server_url` string, required
        - `type` 'mcp', required
      - object — A local shell execution tool.
        - `environment` ShellEnvironment, required — The environment configuration for a shell tool.
          - `skills` LocalShellSkill[] — An optional list of skills available in the local environment.
            - `description` string, required — A description of what the skill does.
            - `name` string, required — The name of the skill.
            - `path` string, required — The path to the directory containing the skill (with a SKILL.md file).
          - `type` string, required — The type of the environment. Currently only `local` is supported.
        - `type` 'shell', required
  - `top_logprobs` integer, required — An integer between 0 and 8 specifying the number of most likely tokens to return at each token position.
  - `top_p` number, float, nullable — An alternative to sampling with `temperature`, called nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. It is generally recommended to alter this or `temperature` but not both.
  - `truncation` string, required — The truncation strategy to use for the model response.
  - `usage` ModelUsage
    - `context_details` ContextDetails — Token counts for the latest context window seen by the model. In the non-agentic path these mirror `input_tokens` / `output_tokens`. In the agentic path (multi-agents) these are reset on every step and reflect the most recent step's prompt and output sizes — useful for understanding how the live context window evolves across tool calls. Informational only; not used for billing.
      - `input_tokens` integer, required — Prompt tokens in the latest context (sourced from `SamplingUsage.context_prompt_tokens`).
      - `output_tokens` integer, required — Completion + reasoning tokens in the latest context (sourced from `SamplingUsage.context_output_tokens`).
    - `cost_in_nano_usd` integer, nullable — Cost in nano US dollars for this request.
    - `cost_in_usd_ticks` integer, nullable — Accurate cost of this request in USD ticks, where "tick" is defined as follows: TICKS_IN_USD_CENT: i64 = 100_000_000 which means there is 10'000'000'000 ticks in one *dollar*.
    - `input_tokens` integer, required — Number of input tokens used.
    - `input_tokens_details` InputTokensDetails, required
      - `cached_tokens` integer, required — Token cached by xAI from previous requests and reused for this request.
    - `num_server_side_tools_used` integer, required — Number of server side tools used.
    - `num_sources_used` integer, required — Number of sources used (for live search).
    - `output_tokens` integer, required — Number of output tokens used.
    - `output_tokens_details` OutputTokensDetails, required
      - `reasoning_tokens` integer, required — Tokens generated by the model for reasoning.
    - `server_side_tool_usage_details` ServerSideToolUsageDetails
      - `code_interpreter_calls` integer, required — Number of code interpreter calls.
      - `document_search_calls` integer, required — Number of document search calls.
      - `file_search_calls` integer, required — Number of file search calls.
      - `image_generation_calls` integer, required — Number of image generation calls.
      - `mcp_calls` integer, required — Number of MCP calls.
      - `web_search_calls` integer, required — Number of web search calls.
      - `x_search_calls` integer, required — Number of X search calls.
    - `total_tokens` integer, required — Total tokens used.
  - `user` string, nullable — A unique identifier representing your end-user, which can help xAI to monitor and detect abuse.

## Other responses

- `400` — Bad request. The request is invalid or an invalid API key is provided.
- `404` — Not found. No responses could be found with the given response_id.

---

[API](https://skmtc.net/x/apis/xai-s-rest-api.md) · [All operations](https://skmtc.net/x/apis/xai-s-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/x/xai-s-rest-api/versions/8f6014272113/schema)