---
title: "Compact a whole agent history to a token budget (compact-1)"
method: POST
path: "/v1/compact"
---

# Compact a whole agent history to a token budget (compact-1)

`POST /v1/compact`

## Request

- Base URL: `https://gateway.caveman.so`
- URL: `https://gateway.caveman.so/v1/compact`
- Auth: API key in header `x-cave-api-key`

Compaction of a whole history: compact-1 returns the history to continue from within budget_tokens. Not compression of one payload: use /v1/trim for that. The answer is the history and token counts only. A history that already fits comes back as sent. Metered per call and per token against the organization's monthly compact allowance.

## Headers

- `x-cave-retention` 'metadata' | 'zdr'

## Request body

- CompactRequest
  - `messages` object[], required: The agent's whole history: OpenAI chat messages (tool_calls, role tool) or Anthropic Messages (tool_use and tool_result blocks), not mixed. The body is at most 8 MB.
  - `budget_tokens` integer, required: The most tokens the history may take after its leading system messages, which are kept as sent and not counted.

## Response `200`

The compacted history

- CompactResponse
  - `messages` object[], required: The history to continue from, in the request's shape: the system prompt, the user's messages, one compact-1 block (a ledger of the work and the older lines most likely needed, with markers for what was left out), then the newest turns. Every message kept whole is returned as sent, byte for byte, and a history that already holds a compact-1 block keeps everything up to it byte-identical, so the provider's prompt cache survives.
  - `tokens_before` integer, required: The request's text tokens after its leading system messages (cl100k_base estimate of compact-1's serialization; images and thinking blocks are not counted).
  - `tokens_after` integer, required: The answer's text tokens, counted the same way; at most budget_tokens. Images and thinking blocks kept in whole messages come on top.
  - `recovery_handles` string[]: Present when text was left out and it was stored: GET /sdk/v1/ccr/{handle} returns the left-out spans, each under the reference its marker shows. Absent under metadata or zdr retention, and when the installation has no recovery store or it failed: the markers then point at nothing.
  - `model` 'compact-1', required

## Other responses

- `400`: Structured failure. `error.code` is stable; `error.request_id` is echoed in the x-cave-request-id header.
- `402`: Structured failure. `error.code` is stable; `error.request_id` is echoed in the x-cave-request-id header.
- `413`: Structured failure. `error.code` is stable; `error.request_id` is echoed in the x-cave-request-id header.
- `422`: Structured failure. `error.code` is stable; `error.request_id` is echoed in the x-cave-request-id header.
- `429`: Structured failure. `error.code` is stable; `error.request_id` is echoed in the x-cave-request-id header.
- `4XX`: Structured failure. `error.code` is stable; `error.request_id` is echoed in the x-cave-request-id header.
- `5XX`: Structured failure. `error.code` is stable; `error.request_id` is echoed in the x-cave-request-id header.

---

[API](https://skmtc.dev/caveman/apis/caveman-cloud-api.md) - [All operations](https://skmtc.dev/caveman/apis/caveman-cloud-api/llms.txt) - [OpenAPI document](https://skmtc.dev/caveman/apis/caveman-cloud-api/revisions/508312d01cfc?raw)