---
title: "Compact a conversation. [alpha]"
method: POST
path: "/v1/responses/compact"
tags: ["Responses"]
---

# Compact a conversation. [alpha]

`POST /v1/responses/compact`

**[alpha]** Compresses conversation history into a smaller representation while preserving context. This endpoint is in alpha and may change without notice.

## Request body

- CompactResponseRequest — Request model for compacting a conversation.
  - `model` union, required — The model to use for generating the compacted summary.
    - string — Model identifier.
    - string
  - `input` union — Input message(s) to compact.
    - string
    - union[]
      - union
        - OpenAIResponseMessageInput — Corresponds to the various Message types in the Responses API. They are all under one type because the Responses API gives them all the same "type" value, and there is no way to tell them apart in certain scenarios.
          - `content` union, required
            - string
            - union[]
              - …
            - union[]
              - …
          - `role` union, required
            - 'system'
            - 'developer'
            - 'user'
            - 'assistant'
          - `type` 'message'
          - `id` string, nullable
          - `status` string, nullable
        - OpenAIResponseOutputMessageWebSearchToolCallInput — Web search tool call output message for OpenAI responses.
          - `id` string, required
          - `status` string, required
          - `type` 'web_search_call'
          - `action` union
            - WebSearchActionSearch — Web search action: performs a search query.
              - …
            - WebSearchActionOpenPage — Web search action: opens a specific URL from search results.
              - …
            - WebSearchActionFind — Web search action: searches for a pattern within a loaded page.
              - …
        - OpenAIResponseOutputMessageFileSearchToolCall — File search tool call output message for OpenAI responses.
          - `id` string, required
          - `queries` string[], required
          - `status` string, required
          - `type` 'file_search_call'
          - `results` OpenAIResponseOutputMessageFileSearchToolCallResults[], nullable
            - `attributes` object, required
            - `file_id` string, required
            - `filename` string, required
            - `score` number, required
            - `text` string, required
        - OpenAIResponseOutputMessageFunctionToolCall — Function tool call output message for OpenAI responses.
          - `call_id` string, required
          - `name` string, required
          - `arguments` string, required
          - `type` 'function_call'
          - `id` string, nullable
          - `status` string, nullable
        - OpenAIResponseOutputMessageMCPCall — Model Context Protocol (MCP) call output message for OpenAI responses.
          - `id` string, required
          - `type` 'mcp_call'
          - `arguments` string, required
          - `name` string, required
          - `server_label` string, required
          - `error` string, nullable
          - `output` string, nullable
        - OpenAIResponseOutputMessageMCPListTools — MCP list tools output message containing available tools from an MCP server.
          - `id` string, required
          - `type` 'mcp_list_tools'
          - `server_label` string, required
          - `tools` MCPListToolsTool[], required
            - `input_schema` object, required
            - `name` string, required
            - `description` string, nullable
        - OpenAIResponseMCPApprovalRequest — A request for human approval of a tool invocation.
          - `arguments` string, required
          - `id` string, required
          - `name` string, required
          - `server_label` string, required
          - `type` 'mcp_approval_request'
        - OpenAIResponseOutputMessageReasoningItem — Reasoning output from the model, representing the model's thinking process.
          - `id` string, required — Unique identifier for the reasoning output item.
          - `summary` OpenAIResponseOutputMessageReasoningSummary[], required — Summary of the reasoning output.
            - `text` string, required — The summary text of the reasoning output.
            - `type` 'summary_text' — The type identifier, always 'summary_text'.
          - `type` 'reasoning' — The type identifier, always 'reasoning'.
          - `content` OpenAIResponseOutputMessageReasoningContent[], nullable — The reasoning content from the model.
            - `text` string, required — The reasoning text content from the model.
            - `type` 'reasoning_text' — The type identifier, always 'reasoning_text'.
          - `status` 'in_progress' | 'completed' | 'incomplete', nullable — The status of the reasoning output.
        - OpenAIResponseInputFunctionToolCallOutput — This represents the output of a function call that gets passed back to the model.
          - `call_id` string, required
          - `output` union, required
            - string
            - union[]
              - …
          - `type` 'function_call_output'
          - `id` string, nullable
          - `status` string, nullable
        - OpenAIResponseMCPApprovalResponse — A response to an MCP approval request.
          - `approval_request_id` string, required
          - `approve` boolean, required
          - `type` 'mcp_approval_response'
          - `id` string, nullable
          - `reason` string, nullable
        - OpenAIResponseCompaction — A compaction item that summarizes prior conversation context.
          - `type` 'compaction'
          - `encrypted_content` string, required
          - `id` string, nullable
  - `instructions` string, nullable — Instructions to guide the compaction.
  - `previous_response_id` string, nullable — ID of a previous response whose history to compact.
  - `prompt_cache_key` string, nullable — A key to use when reading from or writing to the prompt cache.
  - `tools` union[], nullable — List of tools available to the model. Accepted for compatibility but not used during compaction.
    - union
      - OpenAIResponseInputToolWebSearch — Web search tool configuration for OpenAI response inputs.
        - `type` union
          - 'web_search'
          - 'web_search_preview'
          - 'web_search_preview_2025_03_11'
          - 'web_search_2025_08_26'
        - `search_context_size` 'low' | 'medium' | 'high', nullable
        - `filters` WebSearchFilters — Domain filters for web search results.
          - `allowed_domains` string[], nullable
        - `user_location` WebSearchUserLocation — Approximate user location to refine web search results.
          - `type` 'approximate'
          - `city` string, nullable
          - `country` string, nullable
          - `region` string, nullable
          - `timezone` string, nullable
      - OpenAIResponseInputToolFileSearch — File search tool configuration for OpenAI response inputs.
        - `type` 'file_search'
        - `vector_store_ids` string[], required
        - `filters` object, nullable
        - `max_num_results` integer, nullable
        - `ranking_options` SearchRankingOptions — Options for ranking and filtering search results. This class configures how search results are ranked and filtered. You can use algorithm-based rerankers (weighted, RRF) or neural rerankers. Defaults from VectorStoresConfig are used when parameters are not provided. Examples: # Weighted ranker with custom alpha SearchRankingOptions(ranker="weighted", alpha=0.7) # RRF ranker with custom impact factor SearchRankingOptions(ranker="rrf", impact_factor=50.0) # Use config defaults (just specify ranker type) SearchRankingOptions(ranker="weighted") # Uses alpha from VectorStoresConfig # Score threshold filtering SearchRankingOptions(ranker="weighted", score_threshold=0.5)
          - `ranker` string, nullable
          - `score_threshold` number, nullable
          - `alpha` number, nullable — Weight factor for weighted ranker
          - `impact_factor` number, nullable — Impact factor for RRF algorithm
          - `weights` object, nullable — Weights for combining vector, keyword, and neural scores. Keys: 'vector', 'keyword', 'neural'
          - `model` string, nullable — Model identifier for neural reranker
      - OpenAIResponseInputToolFunction — Function tool configuration for OpenAI response inputs.
        - `type` 'function'
        - `name` string, required
        - `description` string, nullable
        - `parameters` object, nullable, required
        - `strict` boolean, nullable
      - OpenAIResponseInputToolMCP — Model Context Protocol (MCP) tool configuration for OpenAI response inputs.
        - `type` 'mcp'
        - `server_label` string, required
        - `connector_id` string, nullable
        - `server_url` string, nullable
        - `headers` object, nullable
        - `authorization` string, nullable
        - `require_approval` union
          - 'always'
          - 'never'
          - ApprovalFilter — Filter configuration for MCP tool approval requirements.
            - `always` string[], nullable
            - `never` string[], nullable
        - `allowed_tools` union
          - string[]
          - AllowedToolsFilter — Filter configuration for restricting which MCP tools can be used.
            - `tool_names` string[], nullable
  - `parallel_tool_calls` boolean, nullable — Whether to enable parallel tool calls. Accepted for compatibility but not used during compaction.
  - `reasoning` OpenAIResponseReasoning — Configuration for reasoning effort in OpenAI responses. Controls how much reasoning the model performs before generating a response.
    - `effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh', nullable
    - `generate_summary` 'auto' | 'concise' | 'detailed', nullable — Deprecated: use 'summary' instead.
    - `summary` 'auto' | 'concise' | 'detailed', nullable — Summary mode for reasoning output. One of 'auto', 'concise', or 'detailed'.
  - `text` OpenAIResponseText — Text response configuration for OpenAI responses.
    - `format` OpenAIResponseTextFormat — Configuration for Responses API text format.
      - `type` union
        - 'text'
        - 'json_schema'
        - 'json_object'
      - `name` string, nullable
      - `schema` object, nullable
      - `description` string, nullable
      - `strict` boolean, nullable
    - `verbosity` 'low' | 'medium' | 'high', nullable

## Response `200`

Successful Response

- OpenAICompactedResponse — Response from compacting a conversation.
  - `id` string, required
  - `created_at` integer, required
  - `object` 'response.compaction'
  - `output` OpenAIResponseMessageOutputUnion[], required
    - union
      - object — Corresponds to the various Message types in the Responses API. They are all under one type because the Responses API gives them all the same "type" value, and there is no way to tell them apart in certain scenarios.
        - `content` union, required
          - string
          - union[]
            - union
              - …
          - union[]
            - union
              - …
        - `role` union, required
          - 'system'
          - 'developer'
          - 'user'
          - 'assistant'
        - `type` 'message'
        - `id` string, nullable
        - `status` string, nullable
      - object — Web search tool call output message for OpenAI responses.
        - `id` string, required
        - `status` string, required
        - `type` 'web_search_call'
        - `action` union
          - WebSearchActionSearch — Web search action: performs a search query.
            - `type` 'search'
            - `query` string, required
            - `queries` string[], nullable
            - `sources` WebSearchSource[], nullable
              - …
          - WebSearchActionOpenPage — Web search action: opens a specific URL from search results.
            - `type` 'open_page'
            - `url` string, nullable
          - WebSearchActionFind — Web search action: searches for a pattern within a loaded page.
            - `type` 'find_in_page'
            - `url` string, required
            - `pattern` string, required
      - object — File search tool call output message for OpenAI responses.
        - `id` string, required
        - `queries` string[], required
        - `status` string, required
        - `type` 'file_search_call'
        - `results` OpenAIResponseOutputMessageFileSearchToolCallResults[], nullable
          - `attributes` object, required
          - `file_id` string, required
          - `filename` string, required
          - `score` number, required
          - `text` string, required
      - object — Function tool call output message for OpenAI responses.
        - `call_id` string, required
        - `name` string, required
        - `arguments` string, required
        - `type` 'function_call'
        - `id` string, nullable
        - `status` string, nullable
      - object — Model Context Protocol (MCP) call output message for OpenAI responses.
        - `id` string, required
        - `type` 'mcp_call'
        - `arguments` string, required
        - `name` string, required
        - `server_label` string, required
        - `error` string, nullable
        - `output` string, nullable
      - object — MCP list tools output message containing available tools from an MCP server.
        - `id` string, required
        - `type` 'mcp_list_tools'
        - `server_label` string, required
        - `tools` MCPListToolsTool[], required
          - `input_schema` object, required
          - `name` string, required
          - `description` string, nullable
      - object — A request for human approval of a tool invocation.
        - `arguments` string, required
        - `id` string, required
        - `name` string, required
        - `server_label` string, required
        - `type` 'mcp_approval_request'
      - object — Reasoning output from the model, representing the model's thinking process.
        - `id` string, required — Unique identifier for the reasoning output item.
        - `summary` OpenAIResponseOutputMessageReasoningSummary[], required — Summary of the reasoning output.
          - `text` string, required — The summary text of the reasoning output.
          - `type` 'summary_text' — The type identifier, always 'summary_text'.
        - `type` 'reasoning' — The type identifier, always 'reasoning'.
        - `content` OpenAIResponseOutputMessageReasoningContent[], nullable — The reasoning content from the model.
          - `text` string, required — The reasoning text content from the model.
          - `type` 'reasoning_text' — The type identifier, always 'reasoning_text'.
        - `status` 'in_progress' | 'completed' | 'incomplete', nullable — The status of the reasoning output.
      - object — This represents the output of a function call that gets passed back to the model.
        - `call_id` string, required
        - `output` union, required
          - string
          - union[]
            - union
              - …
        - `type` 'function_call_output'
        - `id` string, nullable
        - `status` string, nullable
      - object — A response to an MCP approval request.
        - `approval_request_id` string, required
        - `approve` boolean, required
        - `type` 'mcp_approval_response'
        - `id` string, nullable
        - `reason` string, nullable
      - object — A compaction item that summarizes prior conversation context.
        - `type` 'compaction'
        - `encrypted_content` string, required
        - `id` string, nullable
  - `usage` OpenAIResponseUsage, required — Usage information for OpenAI response.
    - `input_tokens` integer, required
    - `output_tokens` integer, required
    - `total_tokens` integer, required
    - `input_tokens_details` OpenAIResponseUsageInputTokensDetails, required — Token details for input tokens in OpenAI response usage.
      - `cached_tokens` integer, required
    - `output_tokens_details` OpenAIResponseUsageOutputTokensDetails, required — Token details for output tokens in OpenAI response usage.
      - `reasoning_tokens` integer, required

## Other responses

- `400` — The request was invalid or malformed
- `429` — The client has sent too many requests in a given amount of time
- `500` — The server encountered an unexpected error
- `default` — An error occurred

---

[API](https://skmtc.net/ogx-ai/apis/ogx-specification-stable-experimental-apis.md) · [All operations](https://skmtc.net/ogx-ai/apis/ogx-specification-stable-experimental-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ogx-ai/ogx-specification-stable-experimental-apis/versions/f3f783962256/schema)