> ## Documentation Index
> Fetch the complete documentation index at: https://docs.playapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Responses context compaction

> Compact complete history and continue with the returned context window.

Handle growing history before it exceeds the model's context window. The [standalone compaction endpoint](/en/api-reference/responses-compact) returns a new context window; it does not produce the final answer and is not a universal summarization API. Confirm that the same model and channel support both `/responses/compact` and `/responses`, including preservation and replay of compaction items.

## Compact and continue

Install the existing Python example dependencies. The script uses a fixed demonstration conversation, compacts it, then appends a question and generates text: two requests. In a real application, supply your complete saved inputs, outputs, tool results, and reasoning items.

```sh theme={null}
export API_BASE_URL="https://gateway.example.com/v1"
export API_KEY="YOUR_API_KEY"
export API_MODEL="YOUR_MODEL_ID"
.venv/bin/python examples/compaction.py
```

```python theme={null}
import os
from openai import OpenAI, APIConnectionError, APIStatusError

history = [
    {"role": "user", "content": "Plan a two-day visit to Kyoto without driving."},
    {"role": "assistant", "content": "Day one: eastern temples. Day two: Arashiyama by train."},
]
instructions = "Answer briefly in plain text. Preserve the user's travel constraints."
with OpenAI(base_url=os.environ["API_BASE_URL"].rstrip("/"),
            api_key=os.environ["API_KEY"], timeout=60.0, max_retries=0) as client:
    try:
        compacted = client.post("/responses/compact", cast_to=dict, body={
            "model": os.environ["API_MODEL"], "input": history,
            "instructions": instructions,
        })
        if (not isinstance(compacted, dict) or compacted.get("error")
                or compacted.get("object") != "response.compaction"):
            raise ValueError("Invalid compaction response.")
        window = compacted.get("output")
        if not isinstance(window, list) or not window:
            raise ValueError("Empty compacted window.")
        found_compaction = False
        for item in window:
            if not isinstance(item, dict) or not isinstance(item.get("type"), str) or not item["type"]:
                raise ValueError("Invalid context item.")
            if item["type"] == "compaction":
                encrypted = item.get("encrypted_content")
                if not isinstance(encrypted, str) or not encrypted.strip():
                    raise ValueError("Missing encrypted content.")
                found_compaction = True
        if not found_compaction:
            raise ValueError("Missing compaction item.")
        # Keep every returned item, in order, including unknown metadata.
        next_input = [*window, {"role": "user", "content": "Add a rainy-day alternative."}]
        result = client.responses.create(
            model=os.environ["API_MODEL"], input=next_input,
            instructions=instructions, store=False,
        )
        if result.status != "completed" or not result.output_text.strip():
            raise ValueError("No complete text reply.")
        for item in result.output:
            if item.type == "reasoning":
                continue
            if (item.type != "message" or item.status != "completed"
                    or any(part.type != "output_text" for part in item.content)):
                raise ValueError("Unexpected or incomplete output item.")
        print(result.output_text)
    except APIStatusError as error:
        raise SystemExit(f"Request failed (HTTP {error.status_code}). No automatic retry.")
    except APIConnectionError:
        raise SystemExit("Connection failed. Original history must be retained.")
    except (ValueError, TypeError, AttributeError):
        raise SystemExit("Invalid compaction or continuation. Original history must be retained.")
```

## Retention and replay

Standalone compaction returns `object: response.compaction` and `output`; do not read it using the usual Responses `status` / `output_text` contract. Preserve the entire ordered output, including additional fields. Use it as the next context window and append new input. Do not keep only the `compaction` item or append the old transcript again.

`encrypted_content` is opaque state, not a readable summary to decode or modify. The input to compaction must still fit the model's context window. See the [OpenAI compaction guide](https://developers.openai.com/api/docs/guides/compaction) for these protocol rules.

The example supplies `instructions` explicitly on each request and continues with `store: false`. That is not a retention guarantee for the gateway, logs, or upstream. Compaction does not synchronize your database, business state, or permission rules.

## Failure and compatibility

* Keep the original history if compaction fails or returns an empty window. Do not continue generation or automatically delete history.
* If compaction succeeds but continuation fails, retain the original history and valid compacted window so the application can choose a recovery point. Do not automatically rerun the entire flow.
* Load balancing may send the two requests to incompatible upstreams. Confirm routing, credentials, and state compatibility with the administrator; the same model ID alone does not guarantee replay.
* Automatic `context_management`, stored response IDs, and background execution are separate capabilities. Responses retrieval covers only [plugin task responses](/en/guides/background-responses), not general upstream retrieval or REST deletion / cancellation. See [API coverage](/en/guides/api-coverage).

This text example checks window structure and final text completion, not preservation of every fact. Evaluate important constraints, tool associations, and long-conversation quality against a real deployment. The local fixture does not validate encrypted state.

[Multi-turn conversations](/en/guides/conversations) · [Production integration](/en/guides/production)

[阅读中文](/zh/guides/compaction)

[Prompt caching](/en/guides/prompt-caching) · [Reasoning models](/en/guides/reasoning-models) · [Context management](/en/guides/context-management)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.