Claude Messages API compaction: two beta paths, the signed block and the billing line
compaction costs an extra sampling step and is not automatically cheaper
Anthropic put the compaction API in beta on 2026-02-05 (summarise once a threshold is hit) and added on-demand compaction on 2026-09-14: send the top-level compaction parameter and the API returns a signed compaction block. The two paths cannot share one request; the signed block has to go first in messages, and the docs call leaving the summarised messages in front of it a 400; usage.iterations decides what the call really cost; and the docs also show how compaction works with prompt caching.
Updated 2026-10-20
Claude, GPT and Chinese models on one key, billed per token; check /models for callable models.
- Billed per token — live rates on /models
- Pay by card (Visa / Mastercard), Apple Pay, Google Pay or crypto
- Self-service: top up and activate instantly
Four key points
Two different beta headers
Threshold compaction uses compact-2026-01-12, configured inside context_management.edits with entry type compact_20260112; on-demand uses compact-2026-09-04 with the top-level compaction parameter. Official wording: You can't send `compaction` and `context_management` on the same request.
Default trigger for the threshold path
The official parameter table: trigger defaults to {"type": "input_tokens", "value": 150000}, input_tokens is the only supported trigger type, and value must be at least 50,000 tokens. Once it fires, the API writes a summary, puts it in a compaction block and continues the response with the compacted context.
A misplaced signed block is a 400
The on-demand path returns one signed compaction block. Official wording: if any remain in front of the block, the request returns a 400 error (`compaction_block_misplaced`). Send the block first in messages, in place of the turns it summarises, and keep it exactly as returned including its signature. The threshold block sits after the content it summarised instead.
Why it bills separately
Official wording: Compaction requires an additional sampling step, which contributes to rate limits and billing. The response adds an entry of type compaction to usage.iterations; the top-level input_tokens and output_tokens do not include it, so the vendor asks you to sum across iterations for the real cost of the call.
What it is
Server-side compaction: when a request reaches your configured threshold, Claude writes the summary of the conversation itself and returns it inside a compaction block; on later requests the API drops every content block before that block and continues from the summary. The docs position it as the replacement for client-side summarisation code: the summary is written on the server, so you need no summarization code of your own. They name two use cases: a multi-turn chat that people keep running in one window for a long time, and task-oriented prompts that need a lot of follow-up work (often tool use) that might exceed the context window.
What happened
Both dates are verbatim in the official API release notes. 2026-02-05: the compaction API entered beta, providing server-side context summarization for effectively infinite conversations, and the entry says it was available on Opus 4.6. 2026-09-14: the Messages API can now compact a conversation on demand, in beta with the compact-2026-09-04 beta header; send the top-level compaction parameter and the API returns a signed compaction block, and on later requests you send that block back in place of those messages. The on-demand path produces one signed block and no reply (stop_reason is compaction); that request can run in the background while the conversation continues on full history, and recent turns can be kept word for word after the summary.
Timeline
2026-02-05: the official release notes say the compaction API entered beta with server-side context summarization for effectively infinite conversations, and the entry states it was available on Opus 4.6 - the first server-side compaction beta.
2026-09-14: the same page adds on-demand compaction (beta header compact-2026-09-04): the top-level compaction parameter, a signed block, background summarisation and word-for-word recent turns kept after the summary.
The official .md documents and the API release notes were captured, and every parameter, default and error code quoted above was checked verbatim; the official supported-platform list for the on-demand path names Google Cloud and not Amazon Bedrock, while the threshold path's list also names Amazon Bedrock.
Confirmed vs watch out
Confirmed by the docs
Verbatim in the official pages: trigger defaults to 150000 with value at least 50,000; input_tokens is the only supported trigger type; a non-blank instructions string replaces the default summarisation prompt entirely (up to 16,384 characters on the on-demand path); pause_after_compaction defaults to false; compaction requires an additional sampling step, which contributes to rate limits and billing; top-level usage excludes the compaction iteration and you must sum iterations; leaving the summarised messages in front of the signed block is a 400 with the code compaction_block_misplaced; compaction and context_management cannot be combined on one request; the token counting endpoint ignores the compaction parameter; images, documents, container_upload blocks and fetched URLs inside the summarised range are gone once the block replaces them.
⚠️ Watch out
The community line that compaction makes every later request dearer cannot be stated as fact. The vendor says compaction adds a billed sampling step, and in the same document says Compaction works well with prompt caching, showing a cache_control breakpoint on the block and recommending a breakpoint at the end of the system prompt so the system prompt cache stays valid; it also says re-applying a previous compaction block incurs no additional compaction cost. The accurate version: compaction has a cost, and whether it pays depends on where your cache breakpoints sit. Also: the whole surface is beta; a failed summary still returns HTTP 200 with empty content and that call is still billed; a transient server problem returns a retryable 529 overloaded_error with error.details.error_code compaction_unavailable; and sending a task budget's remaining value alongside compaction is a 400.
Same and different
What they share
Both summarise server-side, both return a compaction block, both use the model in your request to write the summary (Current limitations says there is no option to use a different, cheaper model), both add a sampling step that counts against rate limits and billing, and both are still beta.
What differs
Triggering differs: the threshold path fires mid-request and compacts in place, and it can fire several times in one call (with server tools the trigger is checked at the start of each sampling iteration); the on-demand path is one request you spend on writing the summary, and that request produces no reply. Block placement differs: a threshold block follows the content it summarised, a signed block replaces those messages. Platforms differ too: the official list for the on-demand path includes Google Cloud and not Amazon Bedrock, while the list for the threshold path also names Amazon Bedrock.
How to use it
Five steps. 1) Pick a path: threshold compaction if you want the API to manage context inside ordinary requests; the compaction parameter if your app must control when it happens, cannot pause while a summary is written, or must keep recent turns and their thinking. 2) Send the header right: on-demand needs compact-2026-09-04 on the request that asks for the summary and on every later request carrying the signed block; without it the summary request fails with a 400 that names the missing beta header, and a later request that carries the block fails with a validation error that says compaction is not one of the expected content block types, which never mentions the header. 3) Put the block back first in messages and delete the summarised turns. 4) Fix your cost tracking: sum usage.iterations instead of reading only the two top-level fields. 5) Handle the no-summary case: with tools defined the model sometimes calls a tool instead of writing a summary and the block comes back with content: null; the documented fix is instructions that explicitly forbid tool calls.
On QCode
Compaction is a Messages API parameter and beta header, not a switch we expose. Anthropic interprets the parameter, and we make no promise on its behalf. The models on the official beta support list - claude-opus-5, claude-sonnet-5, claude-fable-5, claude-fable-5-1, claude-opus-4-8 and claude-sonnet-4-6 - are all in the public /models list (checked 2026-10-20); the official support list also names claude-mythos-5 and claude-mythos-5-1. Whether a model supports compaction is listed in the official Compatibility lists, which the vendor keeps separately for each beta header. Billed per token; per-model rates are listed on the Models page.
FAQ
Can both betas be on at once?
No. The docs state that compaction and context_management cannot be sent on the same request, and add that threshold compaction (compact_20260112) cannot run on a request that carries a signed block. Pick one path.
Does enabling compaction save money?
Not by itself. The vendor says compaction requires an additional sampling step that contributes to rate limits and billing, and that the top-level input_tokens / output_tokens exclude it, so you have to sum usage.iterations. What shrinks is the context of later requests; whether the net is cheaper depends on cache breakpoints and on the fact that re-applying an old block costs no extra compaction.
Where does the signed block go?
First in messages, with the summarised turns removed, and the block kept exactly as returned including its signature. The docs say that if any remain in front of the block, the request returns a 400 error (compaction_block_misplaced). Every later request that carries the block must have the compact-2026-09-04 header.
Why did the block come back empty?
Most often the tool conflict: Current limitations says that when a request includes tools, the model occasionally calls a tool during the internal summarisation step instead of writing a summary, and the response then carries a compaction block with content: null. The documented fix is instructions that explicitly say not to call tools and to answer with text only. Note also that a failed summary is still HTTP 200 with empty content, still billed and still reported in usage.iterations.
Where do I find the models that support compaction? Which models can I try this on at QCode?
The vendor keeps official Compatibility lists separately for each beta header: one for the on-demand path, one for the threshold path, each with the model identifiers in the form you send them. The models on the official beta support list - claude-opus-5, claude-sonnet-5, claude-fable-5, claude-fable-5-1, claude-opus-4-8 and claude-sonnet-4-6 - are all in the public /models list (checked 2026-10-20); the official support list also names claude-mythos-5 and claude-mythos-5-1. Compaction is an API parameter, not a switch we flip for you; beta surfaces can change, and we promise no long-term support for either path.
Can a cheaper model write the summary, or skip it?
No swap. The docs state that the model specified in your request is used for summarization, and that there is no option to use a different (for example, cheaper) model for the summary. What you can change is instructions (a custom summarisation prompt that fully replaces the default) and the trigger threshold. Full control means turning server-side compaction off and summarising client-side, which is a different design.
Sources
Official Anthropic compaction pages: the overview at https://platform.claude.com/docs/en/build-with-claude/compaction (the Choose how to compact table and the page index), the threshold page at https://platform.claude.com/docs/en/build-with-claude/compaction-threshold (Parameters / Understanding usage / Prompt caching / Current limitations) and the on-demand page at https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand (Request a summary / Errors / Count compaction usage), plus the API release notes at https://platform.claude.com/docs/en/release-notes/api (the 2026-02-05 and September 14, 2026 entries are quoted verbatim; fetched the same day in the official .md form, HTTP 200).
Fix the usage accounting before deciding to compact
Headers, block placement and billing wording here follow the official documents checked on 2026-10-20; the parameter is interpreted by Anthropic and we promise no behaviour on its behalf. Out of quota? With an active personal plan buy a booster pack, without one buy Pay-as-you-go Packs, which start at $4 for a one-time quota you use within 7 days (top-ups start at $5). Prices on /pricing, current catalog on /models.
Related reading
Context Engineering Complete Guide 2026
Compaction is one technique inside context engineering; that page covers the method, not the API parameters.
Adding and Removing Tools Mid-Conversation
How mid-conversation instructions and tool changes survive summarisation is covered there.
effort is not supported when thinking is disabled
The thinking-block and history-change error family: the kept turns' thinking must stay consistent too.
Crypto payment guide
Nine coins, 56 networks, zero platform fee for AI coding API credits.
This page transcribes public Anthropic documentation and is not affiliated with Anthropic. Parameter names, defaults, error codes and quoted sentences are as of the check on 2026-10-20; beta surfaces change without notice. Whether compaction pays depends on the extra sampling step and on where the cache breakpoints sit, and the docs say nothing beyond that. QCode provides API access and does not change the beta status of Anthropic's interfaces.