compaction-on-demand changedbuild-with-claude/compaction-on-demand
Recorded here
Lines+37added
Lines−22removed
From line
24
where the diff opens
First seen
21 Sep 2026
this site's first read of the page
Recorded edits22to this page, all time
The whole hunk
from line 24, old and new numbered
/
from line 24
2424 - claude-sonnet-4-6
2525 supportedPlatforms:
2626 Claude API: beta
27 Claude Platform on AWS: beta
2827 Amazon Bedrock: beta
28 Claude Platform on AWS: beta
2929 Claude Models on Google Cloud (Google managed): beta
3030 Microsoft Foundry: beta
3131---
from line 339
339339}
340340```
341341
342This example continues the request sample, which ended on a `user` turn; the diagram shows the simpler case, where no turn is taken while the summary is written. Here the second `assistant` message is the reply to the last summarized `user` turn. It arrived while the summary was being written, so it was not among the messages summarized. Two `assistant` messages in a row are fine here, because the block still comes first.
342This example continues the request sample, which ended on a `user` turn. The diagram shows the simpler case, where nobody takes a turn while the API writes the summary. Here the second `assistant` message is the reply to the last summarized `user` turn. It arrived while the API was writing the summary, so the summary doesn’t cover it. Two `assistant` messages in a row are fine here, because the block still comes first.
343343
344344The API puts the summary where the block stands and passes every later message to Claude unchanged. Follow these rules:
345345
from line 348
348348* Send exactly one `compaction` block in each request, on every later request.
349349
350350<Warning>
351 Two mistakes in the swap raise no error. If summarized messages remain after the block, the API sends them to Claude again. If a later request leaves the block out, Claude gets no summary.
351 Two mistakes in the swap can pass without an error:
352
353 * **The block is left out of a later request:** Claude gets no summary.
354 * **Summarized messages stay after the block:** the API sends them to Claude again.
355
356 On models with [preserved thinking](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking), either mistake can also make thinking blocks in the request fail the [prefix check](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#prefix-check).
352357</Warning>
353358
354359Threshold compaction works the other way around: its block follows the messages it summarizes, and the API drops them for you. See [Passing compaction blocks back](https://platform.claude.com/docs/en/build-with-claude/compaction-threshold#passing-compaction-blocks-back).
355360
356In Python, use `client.beta.messages`, as the samples on this page do. If you call `client.messages` and serialize blocks yourself, use `to_dict()` or `model_dump(exclude_none=True)`: a plain `model_dump()` adds `citations: null` and `text: null` to the block, and the API rejects it.
357
358361If you keep turns after the block and send their thinking blocks back, the conditions that keep that thinking valid are on [Compaction and preserved thinking](https://platform.claude.com/docs/en/build-with-claude/compaction-thinking-blocks).
359362
360363### Compact again
from line 368
365368
366369After each turn, the loop adds the last response’s input and output tokens, because the next request sends the reply too. When that total passes a limit and another turn is still to come, it sends a compaction request with the same model and `system` prompt, checks `stop_reason`, replaces its history with the returned message, and prints the turn it compacted before. The sample’s limit of 2,500 tokens is deliberately low, so that a short conversation compacts. Set yours near your real input budget.
367370
368<CodeGroup exclude="shell">
371<CodeGroup exclude="shell:cURL, shell:CLI">
372 <CodeGroupItem language="cURL">
373 This workflow needs more logic than a single shell command. Use the Anthropic SDK to run it.
374 </CodeGroupItem>
375
376 <CodeGroupItem language="CLI">
377 This workflow needs more logic than a single shell command. Use the Anthropic SDK to run it.
378 </CodeGroupItem>
379
369380 ```python Python
370381 from anthropic.types.beta import BetaMessageParam
371382
from line 421
410421 compaction={"type": "summarize"},
411422 )
412423 if summary.stop_reason == "compaction":
424 # Use client.beta.messages. If you call client.messages and serialize blocks yourself,
425 # use to_dict() or model_dump(exclude_none=True): a plain model_dump() adds
426 # citations: null and text: null to the block, and the API rejects it.
413427 history = [{"role": "assistant", "content": summary.content}]
414428 print(f"Compacted before turn {turn + 1}")
415429 ```
from line 567
553567 }
554568
555569 var history []anthropic.BetaMessageParam
556 for i, question := range questions {
557 turn := i + 1
570 for index, question := range questions {
571 turn := index + 1
558572 history = append(history, anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock(question)))
559573 response, err := client.Beta.Messages.New(ctx, anthropic.BetaMessageNewParams{
560574 Model: anthropic.ModelClaudeOpus5_5,
from line 774
760774
761775The check on `stop_reason` comes before the code looks for the block; [Handle a missing summary or an error](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand#when-no-summary-comes-back) says why. The history is replaced, not appended to: the returned message replaces every message the request carried, under the rules in [Continue from the summary](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand#continue-from-the-summary). When no summary comes back, the loop keeps its history and asks again after the next turn.
762776
763The SDK [tool runner](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-runner) in Python, TypeScript, C#, Go, Java, PHP, and Ruby can send the compaction request for you. When you decide to compact, call `compact_before_next_turn()` (typescript, java, php: `compactBeforeNextTurn()`; csharp, go: `CompactBeforeNextTurn()`) on the runner. Once the current turn and its tool calls complete, the runner sends the compaction request and replaces its history with the returned message. Create the runner with the `compact-2026-09-04` beta, because the runner doesn’t add it.
777The SDK [tool runner](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-runner) can send the compaction request for you. When you decide to compact, call `compact_before_next_turn()` (ruby: `compact_before_next_turn`; typescript, java, php: `compactBeforeNextTurn()`; csharp, go: `CompactBeforeNextTurn()`) on the runner. Once the current turn and its tool calls complete, the runner sends the compaction request and replaces its history with the returned message. Create the runner with the `compact-2026-09-04` beta, because the runner doesn’t add it.
764778
765779The runner builds the compaction request from its own parameters and leaves `context_management` out. It also leaves out `stop_sequences`, a `tool_choice` of type `any` or `tool`, and a structured-output `output_config.format`, which the API rejects on a compaction request. [Request a summary](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand#request-a-summary) explains why. The runner sends them again on its later requests. SDK versions before Python 1.8.0, TypeScript 0.128.0, C# 12.50.0, Go 1.75.0, and Java 2.65.0 send them on the compaction request too. On those versions, a runner that sets any of these parameters gets a 400 error. The runner sends a [task budget](https://platform.claude.com/docs/en/build-with-claude/task-budgets) unchanged. If `output_config.task_budget` sets `remaining`, the compaction request returns a 400 error, so leave `remaining` unset, as [Limits and interactions with other features](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand#how-it-fits-with-the-rest-of-the-api) says. The runner refuses to compact while its `context_management` has a compaction edit, so use one kind of compaction on a runner.
766780
from line 819
805819
806820A compaction request, or a request that carries a block, can also fail outright. Most 400 errors have a message that says what to remove or resend. Some also carry an `error.details.error_code` that starts with `compaction_`. Parameter errors, such as a field that can’t be combined with `compaction`, carry the message only.
807821
808| Error | Cause | What to do |
809| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
810| 529 `overloaded_error`, `error.details.error_code` `compaction_unavailable` | A transient server problem while producing a block, or while reading one you sent back. | Retry the request. |
811| 400 `compaction_block_misplaced` | Summarized messages remain in front of the block. | Remove them, so the block comes first in `messages`. |
812| 400 `compaction_signature_invalid` or `compaction_content_mismatch` | The block’s `signature` or `content` was changed after the API returned it. | Send the block exactly as returned, including its `signature`. |
813| 400 | The request carries more than one `compaction` block. | Send exactly one, the newest. |
814| 400 | The last `assistant` turn ends in a tool call with no result yet. | Send that turn’s tool results, then compact. |
815| 400 `compaction_nothing_to_summarize` | `messages` has no `user` or `assistant` content, for example an empty list. | Send at least one `user` or `assistant` message. |
816| 400 on the compaction request, with a message that says the `compaction` parameter `requires anthropic-beta: compact-2026-09-04` | The compaction request left out the beta header. | Add the beta header; see [Request a summary](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand#request-a-summary). |
817| 400 on a later request that carries the block: a validation error that says `compaction` is not one of the expected content block types. The message doesn’t mention the header. | That request left out the beta header. | Add the beta header to every request that carries the block; see [Request a summary](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand#request-a-summary). |
818| 400 validation error, such as `messages.0.content.0.compaction.citations: Extra inputs are not permitted` | A block was sent back with fields the API didn’t return, such as `citations: null`. | Send the block exactly as returned; see [Continue from the summary](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand#continue-from-the-summary). |
822| Error | Cause | What to do |
823| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
824| 529 `overloaded_error`, `error.details.error_code` `compaction_unavailable` | A transient server problem while producing a block, or while reading one you sent back. | Retry the request. |
825| 400 `compaction_block_misplaced` | Summarized messages remain in front of the block. | Remove them, so the block comes first in `messages`. |
826| 400 `compaction_signature_invalid` or `compaction_content_mismatch` | The block’s `signature` or `content` was changed after the API returned it. | Send the block exactly as returned, including its `signature`. |
827| 400 | The request carries more than one `compaction` block. | Send exactly one, the newest. |
828| 400 | The last `assistant` turn ends in a tool call with no result yet. | Send that turn’s tool results, then compact. |
829| 400 `compaction_nothing_to_summarize` | `messages` has no `user` or `assistant` content, for example an empty list. | Send at least one `user` or `assistant` message. |
830| 400 with a message that a thinking block is `bound to a different conversation` | On a model with preserved thinking, a thinking block in the compaction request failed the [prefix check](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#prefix-check). | [Handle the error](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#handle-the-error-in-code), then compact. |
831| 400 on the compaction request, with a message that says the `compaction` parameter `requires anthropic-beta: compact-2026-09-04` | The compaction request left out the beta header. | Add the beta header; see [Request a summary](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand#request-a-summary). |
832| 400 on a later request that carries the block: a validation error that says `compaction` is not one of the expected content block types. The message doesn’t mention the header. | That request left out the beta header. | Add the beta header to every request that carries the block; see [Request a summary](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand#request-a-summary). |
833| 400 validation error, such as `messages.0.content.0.compaction.citations: Extra inputs are not permitted` | A block was sent back with fields the API didn’t return, such as `citations: null`. | Send the block exactly as returned; see [Continue from the summary](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand#continue-from-the-summary). |
819834
820835## Count compaction usage
821836
from line 842
827842
828843* **Threshold compaction and context editing.** You can’t send `compaction` and `context_management` on the same request. Threshold compaction (`compact_20260112`) can’t run on a request that carries a signed block.
829844* **Prompt caching.** `cache_control` on the block places a breakpoint after the summary.
830* **Mid-conversation system messages and tool changes.** `role: "system"` messages inside the summarized range are summarized too, so their text instructions stop applying once the block replaces them. A [per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta) level they set isn’t carried over either: until a later message sets a level, turns run at the request’s top-level `output_config.effort`, or the model’s default if you don’t set one. If an instruction or effort level still matters, state it again in a `role: "system"` message. Send that message right after your next new `user` turn, and leave it in your history from then on. For [tool changes](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#mid-conversation-tool-changes), and for where that message goes when you keep turns after the block, see [Change the system prompt or tools](https://platform.claude.com/docs/en/build-with-claude/compaction-thinking-blocks#change-the-system-prompt-or-tools).
845* **Mid-conversation system messages and tool changes.** `role: "system"` messages inside the summarized range are summarized too, so their text instructions stop applying once the block replaces them. A [per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort-per-message) level they set isn’t carried over either: until a later message sets a level, turns run at the request’s top-level `output_config.effort`, or the model’s default if you don’t set one. If an instruction or effort level still matters, state it again in a `role: "system"` message. Send that message right after your next new `user` turn, and leave it in your history from then on. For [tool changes](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#mid-conversation-tool-changes), and for where that message goes when you keep turns after the block, see [Change the system prompt or tools](https://platform.claude.com/docs/en/build-with-claude/compaction-thinking-blocks#change-the-system-prompt-or-tools).
831846* **Task budgets.** Don’t send the `remaining` value of a [task budget](https://platform.claude.com/docs/en/build-with-claude/task-budgets) (`output_config.task_budget.remaining`) with `compaction` or on requests that carry the block. Doing so returns a 400 error.
832847* **Token counting.** The [token counting](https://platform.claude.com/docs/en/build-with-claude/token-counting) endpoint ignores the `compaction` parameter.
833848* **Content the summary can’t carry.** Images, documents, `container_upload` blocks, and fetched URLs inside the summarized messages are gone once the block replaces them. Restate or re-upload anything a later turn still needs.
from line 860
845860| Status | Cloud platforms | Models |
846861| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
847862| Beta | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed), [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry) | [Claude Fable 5.2](https://platform.claude.com/docs/en/models/fable-5-2/overview), [Claude Mythos 5.2](https://platform.claude.com/docs/en/models/mythos-5-2/overview), [Claude Fable 5.1](https://platform.claude.com/docs/en/models/fable-5-1/overview), [Claude Mythos 5.1](https://platform.claude.com/docs/en/models/mythos-5-1/overview), [Claude Fable 5](https://platform.claude.com/docs/en/models/fable-5/overview), [Claude Mythos 5](https://platform.claude.com/docs/en/models/mythos-5/overview), Claude Mythos Preview, [Claude Opus 5.5](https://platform.claude.com/docs/en/models/opus-5-5/overview), [Claude Opus 5](https://platform.claude.com/docs/en/models/opus-5/overview), [Claude Sonnet 5.5](https://platform.claude.com/docs/en/models/sonnet-5-5/overview), [Claude Sonnet 5](https://platform.claude.com/docs/en/models/sonnet-5/overview), [Claude Haiku 5.5](https://platform.claude.com/docs/en/models/haiku-5-5/overview), [Claude Opus 4.8](https://platform.claude.com/docs/en/models/opus-4-8/overview), [Claude Opus 4.7](https://platform.claude.com/docs/en/models/opus-4-7/overview), [Claude Opus 4.6](https://platform.claude.com/docs/en/models/opus-4-6/overview), [Claude Sonnet 4.6](https://platform.claude.com/docs/en/models/sonnet-4-6/overview) |
848| Beta | [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock) | [Claude Fable 5.2](https://platform.claude.com/docs/en/models/fable-5-2/overview), [Claude Mythos 5.2](https://platform.claude.com/docs/en/models/mythos-5-2/overview), [Claude Fable 5.1](https://platform.claude.com/docs/en/models/fable-5-1/overview), [Claude Mythos 5.1](https://platform.claude.com/docs/en/models/mythos-5-1/overview), [Claude Fable 5](https://platform.claude.com/docs/en/models/fable-5/overview), [Claude Mythos 5](https://platform.claude.com/docs/en/models/mythos-5/overview), [Claude Opus 5.5](https://platform.claude.com/docs/en/models/opus-5-5/overview), [Claude Opus 5](https://platform.claude.com/docs/en/models/opus-5/overview), [Claude Sonnet 5.5](https://platform.claude.com/docs/en/models/sonnet-5-5/overview), [Claude Sonnet 5](https://platform.claude.com/docs/en/models/sonnet-5/overview), [Claude Haiku 5.5](https://platform.claude.com/docs/en/models/haiku-5-5/overview), [Claude Opus 4.8](https://platform.claude.com/docs/en/models/opus-4-8/overview), [Claude Opus 4.7](https://platform.claude.com/docs/en/models/opus-4-7/overview) |
863| Beta | [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock) | [Claude Fable 5.1](https://platform.claude.com/docs/en/models/fable-5-1/overview), [Claude Mythos 5.1](https://platform.claude.com/docs/en/models/mythos-5-1/overview), [Claude Fable 5](https://platform.claude.com/docs/en/models/fable-5/overview), [Claude Mythos 5](https://platform.claude.com/docs/en/models/mythos-5/overview), [Claude Opus 5.5](https://platform.claude.com/docs/en/models/opus-5-5/overview), [Claude Opus 5](https://platform.claude.com/docs/en/models/opus-5/overview), [Claude Sonnet 5.5](https://platform.claude.com/docs/en/models/sonnet-5-5/overview), [Claude Sonnet 5](https://platform.claude.com/docs/en/models/sonnet-5/overview), [Claude Haiku 5.5](https://platform.claude.com/docs/en/models/haiku-5-5/overview), [Claude Opus 4.8](https://platform.claude.com/docs/en/models/opus-4-8/overview), [Claude Opus 4.7](https://platform.claude.com/docs/en/models/opus-4-7/overview) |
849864
850865### Required beta headers
851866
No line in this hunk matches that.