Skip to main content
Responses

Compact a conversation

POST
/openai/v1/responses/compact

Compacts a conversation into a response object suitable for long-running and zero-data-retention scenarios.

Request BodyContent-Type: application/json
modelstringrequired
The model deployment to use for the compaction of this response.
inputstring | (message | item_reference | output_message | file_search_call | computer_call | computer_call_output | web_search_call | function_call | function_call_output | tool_search_call | tool_search_output | additional_tools | configuration_update | reasoning | compaction | image_generation_call | code_interpreter_call | local_shell_call | local_shell_call_output | shell_call | shell_call_output | apply_patch_call | apply_patch_call_output | mcp_list_tools | mcp_approval_request | mcp_approval_response | mcp_call | custom_tool_call_output | custom_tool_call)[] | null
One of the following:
string
(message | item_reference | output_message | file_search_call | computer_call | computer_call_output | web_search_call | function_call | function_call_output | tool_search_call | tool_search_output | additional_tools | configuration_update | reasoning | compaction | image_generation_call | code_interpreter_call | local_shell_call | local_shell_call_output | shell_call | shell_call_output | apply_patch_call | apply_patch_call_output | mcp_list_tools | mcp_approval_request | mcp_approval_response | mcp_call | custom_tool_call_output | custom_tool_call)[]
null
previous_response_idstring | null
instructionsstring | null
prompt_cache_keystring | null
prompt_cache_retentionenum
in_memory24h
prompt_cache_optionsOpenAI.PromptCacheOptionsParam | null
One of the following:
OpenAI.PromptCacheOptionsParam
Options for prompt caching. Supported for gpt-5.6 and later models. By default, OpenAI automatically chooses one implicit cache breakpoint. You can add explicit breakpoints to content blocks with prompt_cache_breakpoint. Each request can write up to four breakpoints. For cache matching, OpenAI considers up to the latest 80 breakpoints in the conversation, without a content-block lookback limit. Set mode to explicit to disable the implicit breakpoint. The ttl defaults to 30m, which is currently the only supported value. See the prompt caching guide for current details.
null
service_tierenum
autodefaultfastflexpriority
Responses
idstringrequired
The unique identifier for the compacted response.
objectenumrequired
The object type. Always response.compaction.
response.compaction
output(message | program | program_output | function_call | tool_search_call | tool_search_output | additional_tools | function_call_output | file_search_call | web_search_call | image_generation_call | computer_call | computer_call_output | reasoning | compaction | code_interpreter_call | local_shell_call | local_shell_call_output | shell_call | shell_call_output | apply_patch_call | apply_patch_call_output | mcp_list_tools | mcp_approval_request | mcp_approval_response | mcp_call | custom_tool_call | custom_tool_call_output)[]required
The compacted list of output items.
One of the following:
messageOpenAI.ItemFieldMessage
A message to or from the model.
programOpenAI.ItemFieldProgram
An item representing a message, tool call, tool output, reasoning, or other response element.
program_outputOpenAI.ItemFieldProgramOutput
An item representing a message, tool call, tool output, reasoning, or other response element.
function_callOpenAI.ItemFieldFunctionToolCall
A tool call to run a function. See the function calling guide for more information.
tool_search_callOpenAI.ItemFieldToolSearchCall
An item representing a message, tool call, tool output, reasoning, or other response element.
tool_search_outputOpenAI.ItemFieldToolSearchOutput
An item representing a message, tool call, tool output, reasoning, or other response element.
additional_toolsOpenAI.ItemFieldAdditionalTools
An item representing a message, tool call, tool output, reasoning, or other response element.
function_call_outputOpenAI.ItemFieldFunctionToolCallOutput
The output of a function tool call.
file_search_callOpenAI.ItemFieldFileSearchToolCall
The results of a file search tool call. See the file search guide for more information.
web_search_callOpenAI.ItemFieldWebSearchToolCall
The results of a web search tool call. See the web search guide for more information.
image_generation_callOpenAI.ItemFieldImageGenToolCall
An image generation request made by the model.
computer_callOpenAI.ItemFieldComputerToolCall
A tool call to a computer use tool. See the computer use guide for more information.
computer_call_outputOpenAI.ItemFieldComputerToolCallOutput
The output of a computer tool call.
reasoningOpenAI.ItemFieldReasoningItem
A description of the chain of thought used by a reasoning model while generating a response. Be sure to include these items in your input to the Responses API for subsequent turns of a conversation if you are manually managing context.
compactionOpenAI.ItemFieldCompactionBody
A compaction item generated by the v1/responses/compact API.
code_interpreter_callOpenAI.ItemFieldCodeInterpreterToolCall
A tool call to run code.
local_shell_callOpenAI.ItemFieldLocalShellToolCall
A tool call to run a command on the local shell.
local_shell_call_outputOpenAI.ItemFieldLocalShellToolCallOutput
The output of a local shell tool call.
shell_callOpenAI.ItemFieldFunctionShellCall
A tool call that executes one or more shell commands in a managed environment.
shell_call_outputOpenAI.ItemFieldFunctionShellCallOutput
The output of a shell tool call that was emitted.
apply_patch_callOpenAI.ItemFieldApplyPatchToolCall
A tool call that applies file diffs by creating, deleting, or updating files.
apply_patch_call_outputOpenAI.ItemFieldApplyPatchToolCallOutput
The output emitted by an apply patch tool call.
mcp_list_toolsOpenAI.ItemFieldMcpListTools
A list of tools available on an MCP server.
mcp_approval_requestOpenAI.ItemFieldMcpApprovalRequest
A request for human approval of a tool invocation.
mcp_approval_responseOpenAI.ItemFieldMcpApprovalResponseResource
A response to an MCP approval request.
mcp_callOpenAI.ItemFieldMcpToolCall
An invocation of a tool on an MCP server.
custom_tool_callOpenAI.ItemFieldCustomToolCall
A call to a custom tool created by the model.
custom_tool_call_outputOpenAI.ItemFieldCustomToolCallOutput
The output of a custom tool call from your code, being sent back to the model.
created_atintegerrequired
Unix timestamp (in seconds) when the compacted conversation was created.
usageOpenAI.ResponseUsagerequired
Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used.
input_tokensintegerrequired
input_tokens_detailsOpenAI.ResponseUsageInputTokensDetailsrequired
output_tokensintegerrequired
output_tokens_detailsOpenAI.ResponseUsageOutputTokensDetailsrequired
total_tokensintegerrequired
Request
curl -X POST https://api.openai.com/v1/responses/compact \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $OPENAI_API_KEY" \
    -d '{
      "model": "gpt-5.1-codex-max",
      "input": [
        {
          "role": "user",
          "content": "Create a simple landing page for a dog petting café."
        },
        {
          "id": "msg_001",
          "type": "message",
          "status": "completed",
          "content": [
            {
              "type": "output_text",
              "annotations": [],
              "logprobs": [],
              "text": "Below is a single file, ready-to-use landing page for a dog petting café:..."
            }
          ],
          "role": "assistant"
        }
      ]
    }'
Response
{
  "id": "resp_001",
  "object": "response.compaction",
  "created_at": 1764967971,
  "output": [
    {
      "id": "msg_000",
      "type": "message",
      "status": "completed",
      "content": [
        {
          "type": "input_text",
          "text": "Create a simple landing page for a dog petting cafe."
        }
      ],
      "role": "user"
    },
    {
      "id": "cmp_001",
      "type": "compaction",
      "encrypted_content": "gAAAAABpM0Yj-...="
    }
  ],
  "usage": {
    "input_tokens": 139,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 438,
    "output_tokens_details": {
      "reasoning_tokens": 64
    },
    "total_tokens": 577
  }
}