--- title: "Compacts a full Responses API input window into a shorter canonical window." method: POST path: "/v1/responses/compact" tags: ["v1"] --- # Compacts a full Responses API input window into a shorter canonical window. `POST /v1/responses/compact` The client sends its current input (the same items that would be passed to `POST /v1/responses`) and receives a compacted output window. The output should be used **verbatim** as the `input` of the next `/v1/responses` call (appending only the new user turn). This generalizes the compaction approach used by the coding-agent harness (`generate_session_compact` in xai-grok-shell): 1. Strip tool-result noise from the history. 2. Ask the model to produce a structured `` of the conversation. 3. Rebuild a compact window: system message → summary → last user query. 4. Return that window to the client. ## Request body - CompactRequest — The request body for `POST /v1/responses/compact`. Clients send the full current input window (the same items they would pass to `/v1/responses`) and receive back a compacted window suitable for use as the `input` of the next `/v1/responses` call. - `input` union, required — Content of the input passed to a `/v1/response` request. - string — Text input. - ModelInputPart[] — A list of input items to the model. Can be of different types. - union - object — Message input to the model. - `content` union, required - string — Text input. - ModelInputContentItem[] — A list of input items to the model. Can include text and images. - … - `name` string, nullable — A unique identifier representing your end-user, which can help xAI to monitor and detect abuse. Only supported for `user` messages. - `role` string, required — The role of the message. Possible values are `user`, `assistant`, `system` and `developer`. - `type` string, nullable — The type of the message, which is always `message`. - object — The model output from previous responses. - `content` OutputMessageContent[], required — Content of the output message. - union - … - `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`. - object — The model output from previous responses. - `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. - object — The model output from previous responses. - `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`. - object — The model output from previous responses. - `action` union, required - object — Action type "search" - Performs a web search query. - … - object — Action type "open_page" - Opens a specific URL from search results. - … - 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). - … - `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`. - object — The model output from previous responses. - `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`. - object — The model output from previous responses. - `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 - … - `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`. - object — The model output from previous responses. - `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`. - object — The model output from previous responses. - `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. - object — The model output from previous responses. - `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. - … - `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`. - object — The model output from previous responses. - `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. - object — The output of a function call. - `call_id` string, required — The unique ID of the function tool call generated by the model. - `output` union, required - string — Text input. - ModelInputContentItem[] — A list of input items to the model. Can include text and images. - … - `type` string, required — The type of the function tool call, which is always `function_call_output`. - object — The output of a shell call. - `call_id` string, required — The unique ID of the shell tool call generated by the model. - `max_output_length` integer, nullable — The maximum length of the shell command output. Generated by the model and should be passed back with the raw output. - `output` ShellCallOutputResult[], required — An array of shell call output contents. - `outcome` union, required — The outcome of a shell command execution. - … - `stderr` string — The standard error output that was captured. - `stdout` string — The standard output that was captured. - `type` string, required — The type of the output item, which is always `shell_call_output`. - object — A compaction item from a previous `/v1/responses/compact` call. - `encrypted_content` string, required — The encrypted content of the compacted conversation. - `id` string, nullable — The unique ID of the compaction item (e.g. `cmp_`). - `type` string, required — The type of the item. Always `"compaction"`. - `model` string, required — Model to use for compaction summarization (required). ## Response `200` Success – compacted window returned. - CompactResponse — The response body for `POST /v1/responses/compact`. The `output` list contains a single compaction item wrapping the entire compacted conversation in an encrypted blob. Clients should spread `output` into their next `/v1/responses` input: ```python next_input = [*compacted.output, new_user_msg] ``` - `created_at` integer, required — Unix timestamp (in seconds) when the compacted conversation was created. - `id` string, required — Unique ID for this compaction (e.g. `cmp_`). - `model` string, required — Model used for the compaction summary. - `object` string, required — Always `"response.compaction"`. - `output` ModelInputPart[], required — Compacted output containing a single compaction item. Pass this verbatim as input to the next `/v1/responses` call. - union - object — Message input to the model. - `content` union, required - string — Text input. - ModelInputContentItem[] — A list of input items to the model. Can include text and images. - union - … - `name` string, nullable — A unique identifier representing your end-user, which can help xAI to monitor and detect abuse. Only supported for `user` messages. - `role` string, required — The role of the message. Possible values are `user`, `assistant`, `system` and `developer`. - `type` string, nullable — The type of the message, which is always `message`. - object — The model output from previous responses. - `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`. - object — The model output from previous responses. - `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. - object — The model output from previous responses. - `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`. - object — The model output from previous responses. - `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`. - object — The model output from previous responses. - `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`. - object — The model output from previous responses. - `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`. - object — The model output from previous responses. - `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`. - object — The model output from previous responses. - `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. - object — The model output from previous responses. - `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`. - object — The model output from previous responses. - `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. - object — The output of a function call. - `call_id` string, required — The unique ID of the function tool call generated by the model. - `output` union, required - string — Text input. - ModelInputContentItem[] — A list of input items to the model. Can include text and images. - union - … - `type` string, required — The type of the function tool call, which is always `function_call_output`. - object — The output of a shell call. - `call_id` string, required — The unique ID of the shell tool call generated by the model. - `max_output_length` integer, nullable — The maximum length of the shell command output. Generated by the model and should be passed back with the raw output. - `output` ShellCallOutputResult[], required — An array of shell call output contents. - `outcome` union, required — The outcome of a shell command execution. - object — The command exited normally. - … - object — The command timed out. - … - `stderr` string — The standard error output that was captured. - `stdout` string — The standard output that was captured. - `type` string, required — The type of the output item, which is always `shell_call_output`. - object — A compaction item from a previous `/v1/responses/compact` call. - `encrypted_content` string, required — The encrypted content of the compacted conversation. - `id` string, nullable — The unique ID of the compaction item (e.g. `cmp_`). - `type` string, required — The type of the item. Always `"compaction"`. - `usage` CompactUsage — Token usage details for a compaction call. Mirrors OpenAI's `ResponseUsage` shape (`input_tokens`, `input_tokens_details.cached_tokens`, `output_tokens`, `output_tokens_details.reasoning_tokens`, `total_tokens`) and adds `dropped_message_count` as an xAI-specific extension. - `dropped_message_count` integer, required — Number of messages dropped/summarized during compaction. - `input_tokens` integer, required — Number of tokens in the original (pre-compaction) input. - `input_tokens_details` CompactUsageInputTokensDetails, required — Breakdown of input tokens for a compaction call. - `cached_tokens` integer, required — Number of input tokens that were served from the prompt cache. - `output_tokens` integer, required — Number of tokens in the compacted output. - `output_tokens_details` CompactUsageOutputTokensDetails, required — Breakdown of output tokens for a compaction call. - `reasoning_tokens` integer, required — Number of reasoning tokens generated during compaction. - `total_tokens` integer, required — Total number of tokens used (input + output, including reasoning). ## Other responses - `400` — Bad request. --- [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)