title: Compaction url: https://platform.claude.com/docs/en/build-with-claude/compaction description: Server-side context compaction for managing long conversations that approach context window limits.
Compatibility
- Status: Beta
- Beta header:
compact-2026-01-12 - ZDR: eligible (excludes Covered Models)
- Supported models:
claude-fable-5-1,claude-mythos-5-1,claude-fable-5,claude-mythos-5,claude-mythos-preview,claude-opus-5,claude-opus-4-8,claude-opus-4-7,claude-opus-4-6,claude-sonnet-5,claude-sonnet-4-6 - Platforms: Claude API (beta), Claude Platform on AWS (beta), Amazon Bedrock (beta), Google Cloud (beta), Microsoft Foundry (beta)
Compaction extends the effective context length for long-running conversations and tasks by automatically summarizing older context when approaching the context window limit. It also keeps the active context small: as a conversation grows, response quality degrades, so compaction replaces older content with a concise summary.
For a deeper look at why long contexts degrade and how compaction helps, see [Effective context engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents).This is ideal for:
- Chat-based, multi-turn conversations where you want users to use one chat for a long period of time
- Task-oriented prompts that require a lot of follow-up work (often tool use) that might exceed the context window
How compaction works
When compaction is enabled, Claude automatically summarizes your conversation when it reaches the configured token threshold. The API:
- Detects when input tokens reach your specified trigger threshold.
- Generates a summary of the current conversation.
- Creates a
compactionblock containing the summary. - Continues the response with the compacted context.
On subsequent requests, append the response to your messages. The API automatically drops all content blocks prior to the compaction block, continuing the conversation from the summary.
The previous steps describe threshold compaction, which most of this page covers. With the compact-2026-09-04 beta header, you can instead request a summary on demand. That request is separate from your conversation turns and returns only the summary, so it can run in the background. When the block arrives, you swap it in for the messages it summarizes. See Compact on demand with the compaction parameter.
Basic usage
Enable compaction by adding the compact_20260112 strategy to context_management.edits in your Messages API request.
ant beta:messages create --beta compact-2026-01-12 <<'YAML'
model: claude-opus-5
max_tokens: 4096
messages:
- role: user
content: Help me build a website
context_management:
edits:
- type: compact_20260112
YAMLclient = anthropic.Anthropic()
messages = [{"role": "user", "content": "Help me build a website"}]
response = client.beta.messages.create(
betas=["compact-2026-01-12"],
model="claude-opus-5",
max_tokens=4096,
messages=messages,
context_management={"edits": [{"type": "compact_20260112"}]},
)
# Append the response (including any compaction block) to continue the conversation
messages.append({"role": "assistant", "content": response.content})const client = new Anthropic();
const messages: Anthropic.Beta.Messages.BetaMessageParam[] = [
{ role: "user", content: "Help me build a website" }
];
const response = await client.beta.messages.create({
betas: ["compact-2026-01-12"],
model: "claude-opus-5",
max_tokens: 4096,
messages,
context_management: {
edits: [
{
type: "compact_20260112"
}
]
}
});
// Append the response (including any compaction block) to continue the conversation
messages.push({
role: "assistant",
content: response.content
});AnthropicClient client = new();
var messages = new List<BetaMessageParam>
{
new() { Role = Role.User, Content = "Help me build a website" }
};
var parameters = new MessageCreateParams
{
Betas = ["compact-2026-01-12"],
Model = "claude-opus-5",
MaxTokens = 4096,
Messages = messages,
ContextManagement = new BetaContextManagementConfig
{
Edits = [new BetaCompact20260112Edit()]
}
};
var response = await client.Beta.Messages.Create(parameters);
// Append the response (including any compaction block) to continue the conversation
messages.Add(new BetaMessageParam
{
Role = Role.Assistant,
Content = response.Content.Select(block => new BetaContentBlockParam(block.Json)).ToList()
});
Console.WriteLine(response);client := anthropic.NewClient()
messages := []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Help me build a website")),
}
response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5,
MaxTokens: 4096,
Messages: messages,
ContextManagement: anthropic.BetaContextManagementConfigParam{
Edits: []anthropic.BetaContextManagementConfigEditUnionParam{
{OfCompact20260112: &anthropic.BetaCompact20260112EditParam{}},
},
},
Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"},
})
if err != nil {
log.Fatal(err)
}
// Append the response (including any compaction block) to continue the conversation
messages = append(messages, response.ToParam())
fmt.Println(response)import com.anthropic.models.beta.messages.BetaContextManagementConfig;
import com.anthropic.models.beta.messages.BetaCompact20260112Edit;
// ...
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.addBeta("compact-2026-01-12")
.model("claude-opus-5")
.maxTokens(4096L)
.addUserMessage("Help me build a website")
.contextManagement(BetaContextManagementConfig.builder()
.addEdit(BetaCompact20260112Edit.builder().build())
.build())
.build();
BetaMessage response = client.beta().messages().create(params);
// Append the response (including any compaction block) to continue the conversation
// by including it in the next request's messages
System.out.println(response);$client = new Client();
$messages = [
['role' => 'user', 'content' => 'Help me build a website']
];
$response = $client->beta->messages->create(
maxTokens: 4096,
messages: $messages,
model: 'claude-opus-5',
betas: ['compact-2026-01-12'],
contextManagement: [
'edits' => [
['type' => 'compact_20260112']
]
]
);
// Append the response (including any compaction block) to continue the conversation
$messages[] = ['role' => 'assistant', 'content' => $response->content];
echo json_encode($response, JSON_PRETTY_PRINT), PHP_EOL;client = Anthropic::Client.new
messages = [
{ role: "user", content: "Help me build a website" }
]
response = client.beta.messages.create(
betas: ["compact-2026-01-12"],
model: "claude-opus-5",
max_tokens: 4096,
messages: messages,
context_management: {
edits: [{ type: "compact_20260112" }]
}
)
# Append the response (including any compaction block) to continue the conversation
messages << { role: "assistant", content: response.content }
puts responseParameters
| Parameter | Type | Default | Description |
|---|---|---|---|
type |
string | Required | Must be "compact_20260112" |
trigger |
object | {"type": "input_tokens", "value": 150000} |
When to trigger compaction. input_tokens is the only supported trigger type. value must be at least 50,000 tokens. |
pause_after_compaction |
boolean | false |
Whether to pause after generating the compaction summary |
instructions |
string | null |
Custom summarization prompt. Completely replaces the default prompt when provided. |
Trigger configuration
Configure when compaction triggers using the trigger parameter:
ant beta:messages create --beta compact-2026-01-12 <<'YAML'
model: claude-opus-5
max_tokens: 4096
messages:
- role: user
content: Hello, Claude
context_management:
edits:
- type: compact_20260112
trigger:
type: input_tokens
value: 150000
YAMLclient = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
betas=["compact-2026-01-12"],
model="claude-opus-5",
max_tokens=4096,
messages=messages,
context_management={
"edits": [
{
"type": "compact_20260112",
"trigger": {"type": "input_tokens", "value": 150000},
}
]
},
)const client = new Anthropic();
const messages: Anthropic.Beta.Messages.BetaMessageParam[] = [
{ role: "user", content: "Hello, Claude" }
];
const response = await client.beta.messages.create({
betas: ["compact-2026-01-12"],
model: "claude-opus-5",
max_tokens: 4096,
messages,
context_management: {
edits: [
{
type: "compact_20260112",
trigger: {
type: "input_tokens",
value: 150000
}
}
]
}
});AnthropicClient client = new();
List<BetaMessageParam> messages = [new() { Role = Role.User, Content = "Hello" }];
var parameters = new MessageCreateParams
{
Model = "claude-opus-5",
MaxTokens = 4096,
Betas = ["compact-2026-01-12"],
Messages = messages,
ContextManagement = new BetaContextManagementConfig
{
Edits = [new BetaCompact20260112Edit
{
Trigger = new BetaInputTokensTrigger(150000)
}]
}
};
var message = await client.Beta.Messages.Create(parameters);
Console.WriteLine(message);client := anthropic.NewClient()
messages := []anthropic.BetaMessageParam{anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello, Claude"))}
response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5,
MaxTokens: 4096,
Messages: messages,
ContextManagement: anthropic.BetaContextManagementConfigParam{
Edits: []anthropic.BetaContextManagementConfigEditUnionParam{
{OfCompact20260112: &anthropic.BetaCompact20260112EditParam{
Trigger: anthropic.BetaInputTokensTriggerParam{Value: 150000},
}},
},
},
Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)import com.anthropic.models.beta.messages.BetaContextManagementConfig;
import com.anthropic.models.beta.messages.BetaCompact20260112Edit;
import com.anthropic.models.beta.messages.BetaInputTokensTrigger;
// ...
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model("claude-opus-5")
.maxTokens(4096L)
.addBeta("compact-2026-01-12")
.addUserMessage("Hello, Claude")
.contextManagement(BetaContextManagementConfig.builder()
.addEdit(BetaCompact20260112Edit.builder()
.trigger(BetaInputTokensTrigger.builder()
.value(150000L)
.build())
.build())
.build())
.build();
BetaMessage response = client.beta().messages().create(params);
System.out.println(response);$client = new Client();
$messages = [['role' => 'user', 'content' => 'Hello, Claude']];
$message = $client->beta->messages->create(
maxTokens: 4096,
messages: $messages,
model: 'claude-opus-5',
betas: ['compact-2026-01-12'],
contextManagement: [
'edits' => [
[
'type' => 'compact_20260112',
'trigger' => [
'type' => 'input_tokens',
'value' => 150000
]
]
]
]
);
echo $message;client = Anthropic::Client.new
messages = [{ role: "user", content: "Hello, Claude" }]
response = client.beta.messages.create(
betas: ["compact-2026-01-12"],
model: "claude-opus-5",
max_tokens: 4096,
messages: messages,
context_management: {
edits: [
{
type: "compact_20260112",
trigger: {
type: "input_tokens",
value: 150000
}
}
]
}
)
puts responseCustom summarization instructions
The default summarization prompt varies by model. Each default instructs Claude to write a summary inside <summary></summary> tags with the information needed to continue the task in a future context window. For example, some models use the following prompt:
You have written a partial transcript for the initial task above. Please write a summary of the transcript. The purpose of this summary is to provide continuity so you can continue to make progress towards solving the task in a future context, where the raw history above may not be accessible and will be replaced with this summary. Write down anything that would be helpful, including the state, next steps, learnings etc. You must wrap your summary in a <summary></summary> block.You can provide custom instructions through the instructions parameter. Custom instructions don't supplement the default prompt. They replace it completely:
ant beta:messages create --beta compact-2026-01-12 <<'YAML'
model: claude-opus-5
max_tokens: 4096
messages:
- role: user
content: Hello, Claude
context_management:
edits:
- type: compact_20260112
instructions: >-
Focus on preserving code snippets, variable names, and
technical decisions.
YAMLclient = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
betas=["compact-2026-01-12"],
model="claude-opus-5",
max_tokens=4096,
messages=messages,
context_management={
"edits": [
{
"type": "compact_20260112",
"instructions": "Focus on preserving code snippets, variable names, and technical decisions.",
}
]
},
)const client = new Anthropic();
const messages: Anthropic.Beta.Messages.BetaMessageParam[] = [
{ role: "user", content: "Hello, Claude" }
];
const response = await client.beta.messages.create({
betas: ["compact-2026-01-12"],
model: "claude-opus-5",
max_tokens: 4096,
messages,
context_management: {
edits: [
{
type: "compact_20260112",
instructions:
"Focus on preserving code snippets, variable names, and technical decisions."
}
]
}
});AnthropicClient client = new();
var parameters = new MessageCreateParams
{
Betas = ["compact-2026-01-12"],
Model = "claude-opus-5",
MaxTokens = 4096,
Messages =
[
new BetaMessageParam { Role = Role.User, Content = "Help me build a Python web scraper" },
new BetaMessageParam { Role = Role.Assistant, Content = "I'll help you build a web scraper..." },
new BetaMessageParam { Role = Role.User, Content = "Add support for JavaScript-rendered pages" }
],
ContextManagement = new BetaContextManagementConfig
{
Edits = [new BetaCompact20260112Edit
{
Instructions = "Focus on preserving code snippets, variable names, and technical decisions."
}]
}
};
var message = await client.Beta.Messages.Create(parameters);
Console.WriteLine(message);client := anthropic.NewClient()
response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5,
MaxTokens: 4096,
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Help me build a Python web scraper")),
{Role: anthropic.BetaMessageParamRoleAssistant, Content: []anthropic.BetaContentBlockParamUnion{anthropic.NewBetaTextBlock("I'll help you build a web scraper...")}},
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Add support for JavaScript-rendered pages")),
},
ContextManagement: anthropic.BetaContextManagementConfigParam{
Edits: []anthropic.BetaContextManagementConfigEditUnionParam{
{OfCompact20260112: &anthropic.BetaCompact20260112EditParam{
Instructions: anthropic.String("Focus on preserving code snippets, variable names, and technical decisions."),
}},
},
},
Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)import com.anthropic.models.beta.messages.BetaContextManagementConfig;
import com.anthropic.models.beta.messages.BetaCompact20260112Edit;
// ...
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.addBeta("compact-2026-01-12")
.model("claude-opus-5")
.maxTokens(4096L)
.addUserMessage("Help me build a Python web scraper")
.addAssistantMessage("I'll help you build a web scraper...")
.addUserMessage("Add support for JavaScript-rendered pages")
.contextManagement(BetaContextManagementConfig.builder()
.addEdit(BetaCompact20260112Edit.builder()
.instructions("Focus on preserving code snippets, variable names, and technical decisions.")
.build())
.build())
.build();
BetaMessage response = client.beta().messages().create(params);
System.out.println(response);$client = new Client();
$response = $client->beta->messages->create(
maxTokens: 4096,
messages: [
['role' => 'user', 'content' => 'Help me build a Python web scraper'],
['role' => 'assistant', 'content' => "I'll help you build a web scraper..."],
['role' => 'user', 'content' => 'Add support for JavaScript-rendered pages']
],
model: 'claude-opus-5',
betas: ['compact-2026-01-12'],
contextManagement: [
'edits' => [
[
'type' => 'compact_20260112',
'instructions' => 'Focus on preserving code snippets, variable names, and technical decisions.'
]
]
]
);
echo json_encode($response, JSON_PRETTY_PRINT), PHP_EOL;client = Anthropic::Client.new
response = client.beta.messages.create(
betas: ["compact-2026-01-12"],
model: "claude-opus-5",
max_tokens: 4096,
messages: [
{ role: "user", content: "Help me build a Python web scraper" },
{ role: "assistant", content: "I'll help you build a web scraper..." },
{ role: "user", content: "Add support for JavaScript-rendered pages" }
],
context_management: {
edits: [
{
type: "compact_20260112",
instructions:
"Focus on preserving code snippets, variable names, and technical decisions."
}
]
}
)
puts responseOn Claude Fable 5.1 and Claude Mythos 5.1, a request with custom instructions summarizes from the visible conversation only: earlier thinking blocks are not part of the summarizer's input.
Pausing after compaction
Use pause_after_compaction to pause the API after generating the compaction summary. This allows you to add additional content blocks (such as preserving recent messages or specific instruction-oriented messages) before the API continues with the response.
When enabled, the API returns a message with the compaction stop reason after generating the compaction block:
# pause_after_compaction stops the response right after the compaction
# summary so you can adjust the messages before continuing. The continue
# step doesn't translate well to a one-off CLI command; see the SDK tabs
# for the full pause-and-continue flow. Single paused request:
ant beta:messages create --beta compact-2026-01-12 --format jsonl <<'YAML'
model: claude-opus-5
max_tokens: 4096
messages:
- role: user
content: Hello, Claude
context_management:
edits:
- type: compact_20260112
pause_after_compaction: true
YAMLclient = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
betas=["compact-2026-01-12"],
model="claude-opus-5",
max_tokens=4096,
messages=messages,
context_management={
"edits": [{"type": "compact_20260112", "pause_after_compaction": True}]
},
)
# Check if compaction triggered a pause
if response.stop_reason == "compaction":
# Response contains only the compaction block
messages.append({"role": "assistant", "content": response.content})
# Continue the request
response = client.beta.messages.create(
betas=["compact-2026-01-12"],
model="claude-opus-5",
max_tokens=4096,
messages=messages,
context_management={"edits": [{"type": "compact_20260112"}]},
)const client = new Anthropic();
const messages: Anthropic.Beta.Messages.BetaMessageParam[] = [
{ role: "user", content: "Hello, Claude" }
];
let response = await client.beta.messages.create({
betas: ["compact-2026-01-12"],
model: "claude-opus-5",
max_tokens: 4096,
messages,
context_management: {
edits: [
{
type: "compact_20260112",
pause_after_compaction: true
}
]
}
});
// Check if compaction triggered a pause
if (response.stop_reason === "compaction") {
// Response contains only the compaction block
messages.push({
role: "assistant",
content: response.content
});
// Continue the request
response = await client.beta.messages.create({
betas: ["compact-2026-01-12"],
model: "claude-opus-5",
max_tokens: 4096,
messages,
context_management: {
edits: [{ type: "compact_20260112" }]
}
});
}var client = new AnthropicClient();
var messages = new List<BetaMessageParam>
{
new() { Role = Role.User, Content = "Hello, Claude" }
};
var parameters = new MessageCreateParams
{
Model = "claude-opus-5",
MaxTokens = 4096,
Betas = ["compact-2026-01-12"],
Messages = messages,
ContextManagement = new BetaContextManagementConfig
{
Edits = [new BetaCompact20260112Edit
{
PauseAfterCompaction = true
}]
}
};
var response = await client.Beta.Messages.Create(parameters);
if (response.StopReason == BetaStopReason.Compaction)
{
messages.Add(new BetaMessageParam
{
Role = Role.Assistant,
Content = response.Content.Select(block => new BetaContentBlockParam(block.Json)).ToList()
});
parameters = new()
{
Model = "claude-opus-5",
MaxTokens = 4096,
Betas = ["compact-2026-01-12"],
Messages = messages,
ContextManagement = new BetaContextManagementConfig
{
Edits = [new BetaCompact20260112Edit()]
}
};
response = await client.Beta.Messages.Create(parameters);
}
Console.WriteLine(response);client := anthropic.NewClient()
messages := []anthropic.BetaMessageParam{anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello, Claude"))}
compactEdit := anthropic.BetaContextManagementConfigParam{
Edits: []anthropic.BetaContextManagementConfigEditUnionParam{
{OfCompact20260112: &anthropic.BetaCompact20260112EditParam{
PauseAfterCompaction: anthropic.Bool(true),
}},
},
}
response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5,
MaxTokens: 4096,
Messages: messages,
ContextManagement: compactEdit,
Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"},
})
if err != nil {
log.Fatal(err)
}
if response.StopReason == "compaction" {
messages = append(messages, response.ToParam())
response, err = client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5,
MaxTokens: 4096,
Messages: messages,
ContextManagement: anthropic.BetaContextManagementConfigParam{
Edits: []anthropic.BetaContextManagementConfigEditUnionParam{
{OfCompact20260112: &anthropic.BetaCompact20260112EditParam{}},
},
},
Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"},
})
if err != nil {
log.Fatal(err)
}
}
fmt.Println(response)import com.anthropic.models.beta.messages.BetaContextManagementConfig;
import com.anthropic.models.beta.messages.BetaCompact20260112Edit;
import com.anthropic.models.beta.messages.BetaStopReason;
// ...
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model("claude-opus-5")
.maxTokens(4096L)
.addBeta("compact-2026-01-12")
.addUserMessage("Help me build a website")
.contextManagement(BetaContextManagementConfig.builder()
.addEdit(BetaCompact20260112Edit.builder()
.pauseAfterCompaction(true)
.build())
.build())
.build();
BetaMessage response = client.beta().messages().create(params);
// Check if compaction triggered a pause
if (response.stopReason().isPresent()
&& response.stopReason().get().equals(BetaStopReason.COMPACTION)) {
// Append the compaction block and continue the request
// by building a new request with the compacted context
MessageCreateParams continueParams = MessageCreateParams.builder()
.model("claude-opus-5")
.maxTokens(4096L)
.addBeta("compact-2026-01-12")
.addUserMessage("Help me build a website")
.addMessage(response)
.contextManagement(BetaContextManagementConfig.builder()
.addEdit(BetaCompact20260112Edit.builder().build())
.build())
.build();
response = client.beta().messages().create(continueParams);
}
System.out.println(response);$client = new Client();
$messages = [['role' => 'user', 'content' => 'Hello, Claude']];
$response = $client->beta->messages->create(
maxTokens: 4096,
messages: $messages,
model: 'claude-opus-5',
betas: ['compact-2026-01-12'],
contextManagement: [
'edits' => [
[
'type' => 'compact_20260112',
'pause_after_compaction' => true
]
]
]
);
if ($response->stopReason === 'compaction') {
$messages[] = [
'role' => 'assistant',
'content' => $response->content
];
$response = $client->beta->messages->create(
maxTokens: 4096,
messages: $messages,
model: 'claude-opus-5',
betas: ['compact-2026-01-12'],
contextManagement: [
'edits' => [
['type' => 'compact_20260112']
]
]
);
}
echo $response;client = Anthropic::Client.new
messages = [{ role: "user", content: "Hello, Claude" }]
response = client.beta.messages.create(
betas: ["compact-2026-01-12"],
model: "claude-opus-5",
max_tokens: 4096,
messages: messages,
context_management: {
edits: [
{
type: "compact_20260112",
pause_after_compaction: true
}
]
}
)
if response.stop_reason == :compaction
messages << { role: "assistant", content: response.content }
response = client.beta.messages.create(
betas: ["compact-2026-01-12"],
model: "claude-opus-5",
max_tokens: 4096,
messages: messages,
context_management: {
edits: [{ type: "compact_20260112" }]
}
)
end
puts responseEnforcing a total token budget
When a model works on long tasks with many tool-use iterations, total token consumption can grow significantly. You can combine pause_after_compaction with a compaction counter to estimate cumulative usage and gracefully wrap up the task once a budget is reached.
This example appears in the SDK languages only: its value is the budget-tracking logic around the request. The raw request combines the trigger from Trigger configuration with pause_after_compaction from Pausing after compaction.
response = client.beta.messages.create( betas=["compact-2026-01-12"], model="claude-opus-5", max_tokens=4096, messages=messages, context_management={ "edits": [ { "type": "compact_20260112", "trigger": {"type": "input_tokens", "value": TRIGGER_THRESHOLD}, "pause_after_compaction": True, } ] }, )
if response.stop_reason == "compaction": n_compactions += 1 messages.append({"role": "assistant", "content": response.content})
# Estimate total tokens consumed; prompt wrap-up if over budget
if n_compactions * TRIGGER_THRESHOLD >= TOTAL_TOKEN_BUDGET:
messages.append(
{
"role": "user",
"content": "Please wrap up your current work and summarize the final state.",
}
)
```typescript TypeScript
const client = new Anthropic();
const messages: Anthropic.Beta.Messages.BetaMessageParam[] = [
{ role: "user", content: "Hello, Claude" }
];
const TRIGGER_THRESHOLD = 100_000;
const TOTAL_TOKEN_BUDGET = 3_000_000;
let compactionCount = 0;
const response = await client.beta.messages.create({
betas: ["compact-2026-01-12"],
model: "claude-opus-5",
max_tokens: 4096,
messages,
context_management: {
edits: [
{
type: "compact_20260112",
trigger: { type: "input_tokens", value: TRIGGER_THRESHOLD },
pause_after_compaction: true
}
]
}
});
if (response.stop_reason === "compaction") {
compactionCount += 1;
messages.push({ role: "assistant", content: response.content });
// Estimate total tokens consumed; prompt wrap-up if over budget
if (compactionCount * TRIGGER_THRESHOLD >= TOTAL_TOKEN_BUDGET) {
messages.push({
role: "user",
content: "Please wrap up your current work and summarize the final state."
});
}
}AnthropicClient client = new();
List<BetaMessageParam> messages = [new() { Role = Role.User, Content = "Hello, Claude" }];
const int TriggerThreshold = 100_000;
const int TotalTokenBudget = 3_000_000;
int compactionCount = 0;
var response = await client.Beta.Messages.Create(new()
{
Betas = ["compact-2026-01-12"],
Model = "claude-opus-5",
MaxTokens = 4096,
Messages = messages,
ContextManagement = new BetaContextManagementConfig
{
Edits = [new BetaCompact20260112Edit
{
Trigger = new BetaInputTokensTrigger(TriggerThreshold),
PauseAfterCompaction = true
}]
}
});
if (response.StopReason == BetaStopReason.Compaction)
{
compactionCount += 1;
messages.Add(new()
{
Role = Role.Assistant,
Content = response.Content.Select(b => new BetaContentBlockParam(b.Json)).ToList()
});
// Estimate total tokens consumed; prompt wrap-up if over budget
if (compactionCount * TriggerThreshold >= TotalTokenBudget)
{
messages.Add(new()
{
Role = Role.User,
Content = "Please wrap up your current work and summarize the final state."
});
}
}
Console.WriteLine(response);client := anthropic.NewClient()
messages := []anthropic.BetaMessageParam{anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello, Claude"))}
const triggerThreshold = 100_000
const totalTokenBudget = 3_000_000
compactionCount := 0
response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5,
MaxTokens: 4096,
Messages: messages,
ContextManagement: anthropic.BetaContextManagementConfigParam{
Edits: []anthropic.BetaContextManagementConfigEditUnionParam{
{OfCompact20260112: &anthropic.BetaCompact20260112EditParam{
Trigger: anthropic.BetaInputTokensTriggerParam{Value: triggerThreshold},
PauseAfterCompaction: anthropic.Bool(true),
}},
},
},
Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"},
})
if err != nil {
log.Fatal(err)
}
if response.StopReason == "compaction" {
compactionCount++
messages = append(messages, response.ToParam())
// Estimate total tokens consumed; prompt wrap-up if over budget
if compactionCount*triggerThreshold >= totalTokenBudget {
messages = append(messages, anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Please wrap up your current work and summarize the final state.")))
}
}
fmt.Println(response)import com.anthropic.models.beta.messages.BetaContextManagementConfig;
import com.anthropic.models.beta.messages.BetaCompact20260112Edit;
import com.anthropic.models.beta.messages.BetaInputTokensTrigger;
import com.anthropic.models.beta.messages.BetaStopReason;
// ...
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
long triggerThreshold = 100_000;
long totalTokenBudget = 3_000_000;
int compactionCount = 0;
List<BetaMessageParam> messages = new ArrayList<>();
messages.add(BetaMessageParam.builder()
.role(BetaMessageParam.Role.USER)
.content("Hello, Claude")
.build());
MessageCreateParams params = MessageCreateParams.builder()
.addBeta("compact-2026-01-12")
.model("claude-opus-5")
.maxTokens(4096L)
.messages(messages)
.contextManagement(BetaContextManagementConfig.builder()
.addEdit(BetaCompact20260112Edit.builder()
.trigger(BetaInputTokensTrigger.builder()
.value(triggerThreshold)
.build())
.pauseAfterCompaction(true)
.build())
.build())
.build();
BetaMessage response = client.beta().messages().create(params);
if (response.stopReason().isPresent()
&& response.stopReason().get().equals(BetaStopReason.COMPACTION)) {
compactionCount += 1;
messages.add(response.toParam());
// Estimate total tokens consumed; prompt wrap-up if over budget
if (compactionCount * triggerThreshold >= totalTokenBudget) {
messages.add(BetaMessageParam.builder()
.role(BetaMessageParam.Role.USER)
.content("Please wrap up your current work and summarize the final state.")
.build());
}
}
System.out.println(response);$client = new Client();
$triggerThreshold = 100_000;
$totalTokenBudget = 3_000_000;
$compactionCount = 0;
$messages = [['role' => 'user', 'content' => 'Hello, Claude']];
$response = $client->beta->messages->create(
maxTokens: 4096,
messages: $messages,
model: 'claude-opus-5',
betas: ['compact-2026-01-12'],
contextManagement: [
'edits' => [
[
'type' => 'compact_20260112',
'trigger' => ['type' => 'input_tokens', 'value' => $triggerThreshold],
'pause_after_compaction' => true
]
]
]
);
if ($response->stopReason === 'compaction') {
$compactionCount += 1;
$messages[] = ['role' => 'assistant', 'content' => $response->content];
// Estimate total tokens consumed; prompt wrap-up if over budget
if ($compactionCount * $triggerThreshold >= $totalTokenBudget) {
$messages[] = [
'role' => 'user',
'content' => 'Please wrap up your current work and summarize the final state.'
];
}
}client = Anthropic::Client.new
messages = [{ role: "user", content: "Hello, Claude" }]
TRIGGER_THRESHOLD = 100_000
TOTAL_TOKEN_BUDGET = 3_000_000
compaction_count = 0
response = client.beta.messages.create(
betas: ["compact-2026-01-12"],
model: "claude-opus-5",
max_tokens: 4096,
messages: messages,
context_management: {
edits: [
{
type: "compact_20260112",
trigger: { type: "input_tokens", value: TRIGGER_THRESHOLD },
pause_after_compaction: true
}
]
}
)
if response.stop_reason == :compaction
compaction_count += 1
messages << { role: "assistant", content: response.content }
# Estimate total tokens consumed; prompt wrap-up if over budget
if compaction_count * TRIGGER_THRESHOLD >= TOTAL_TOKEN_BUDGET
messages << {
role: "user",
content: "Please wrap up your current work and summarize the final state."
}
end
endWorking with compaction blocks
When compaction is triggered, the API returns a compaction block at the start of the assistant response.
A long-running conversation might result in multiple compactions. The last compaction block reflects the final state of the prompt, replacing content prior to it with the generated summary.
{
"content": [
{
"type": "compaction",
"content": "Summary of the conversation: The user requested help building a web scraper..."
},
{
"type": "text",
"text": "Based on our conversation so far..."
}
]
}Passing compaction blocks back
You must pass the compaction block back to the API on subsequent requests to continue the conversation with the shortened prompt. The simplest approach is to append the entire response content to your messages:
ant beta:messages create \
--beta compact-2026-01-12 \
--transform content \
--format jsonl <<'YAML' > content.json
model: claude-opus-5
max_tokens: 4096
messages:
- role: user
content: Hello, Claude
context_management:
edits:
- type: compact_20260112
YAML
# After receiving a response with a compaction block, append it as the
# assistant turn and continue the conversation
ant beta:messages create --beta compact-2026-01-12 <<YAML
model: claude-opus-5
max_tokens: 4096
messages:
- role: user
content: Hello, Claude
- role: assistant
content: $(cat content.json)
- role: user
content: Now add error handling
context_management:
edits:
- type: compact_20260112
YAMLclient = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
betas=["compact-2026-01-12"],
model="claude-opus-5",
max_tokens=4096,
messages=messages,
context_management={"edits": [{"type": "compact_20260112"}]},
)
# After receiving a response with a compaction block
messages.append({"role": "assistant", "content": response.content})
# Continue the conversation
messages.append({"role": "user", "content": "Now add error handling"})
response = client.beta.messages.create(
betas=["compact-2026-01-12"],
model="claude-opus-5",
max_tokens=4096,
messages=messages,
context_management={"edits": [{"type": "compact_20260112"}]},
)const client = new Anthropic();
const messages: Anthropic.Beta.Messages.BetaMessageParam[] = [
{ role: "user", content: "Hello, Claude" }
];
const response = await client.beta.messages.create({
betas: ["compact-2026-01-12"],
model: "claude-opus-5",
max_tokens: 4096,
messages,
context_management: {
edits: [{ type: "compact_20260112" }]
}
});
// After receiving a response with a compaction block
messages.push({
role: "assistant",
content: response.content
});
// Continue the conversation
messages.push({ role: "user", content: "Now add error handling" });
const nextResponse = await client.beta.messages.create({
betas: ["compact-2026-01-12"],
model: "claude-opus-5",
max_tokens: 4096,
messages,
context_management: {
edits: [{ type: "compact_20260112" }]
}
});AnthropicClient client = new();
var messages = new List<BetaMessageParam>
{
new() { Role = Role.User, Content = "Help me build a web scraper" }
};
var response = await client.Beta.Messages.Create(new()
{
Betas = ["compact-2026-01-12"],
Model = "claude-opus-5",
MaxTokens = 4096,
Messages = messages,
ContextManagement = new BetaContextManagementConfig
{
Edits = [new BetaCompact20260112Edit()]
}
});
messages.Add(new BetaMessageParam
{
Role = Role.Assistant,
Content = response.Content.Select(block => new BetaContentBlockParam(block.Json)).ToList()
});
messages.Add(new BetaMessageParam { Role = Role.User, Content = "Now add error handling" });
var nextResponse = await client.Beta.Messages.Create(new()
{
Betas = ["compact-2026-01-12"],
Model = "claude-opus-5",
MaxTokens = 4096,
Messages = messages,
ContextManagement = new BetaContextManagementConfig
{
Edits = [new BetaCompact20260112Edit()]
}
});
Console.WriteLine(nextResponse);client := anthropic.NewClient()
messages := []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Help me build a web scraper")),
}
compactEdit := anthropic.BetaContextManagementConfigParam{
Edits: []anthropic.BetaContextManagementConfigEditUnionParam{
{OfCompact20260112: &anthropic.BetaCompact20260112EditParam{}},
},
}
response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5,
MaxTokens: 4096,
Messages: messages,
ContextManagement: compactEdit,
Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"},
})
if err != nil {
log.Fatal(err)
}
messages = append(messages, response.ToParam())
messages = append(messages, anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Now add error handling")))
nextResponse, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5,
MaxTokens: 4096,
Messages: messages,
ContextManagement: compactEdit,
Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(nextResponse)import com.anthropic.models.beta.messages.BetaContextManagementConfig;
import com.anthropic.models.beta.messages.BetaCompact20260112Edit;
// ...
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// First request
BetaMessage response = client.beta().messages().create(
MessageCreateParams.builder()
.addBeta("compact-2026-01-12")
.model("claude-opus-5")
.maxTokens(4096L)
.addUserMessage("Help me build a web scraper")
.contextManagement(BetaContextManagementConfig.builder()
.addEdit(BetaCompact20260112Edit.builder().build())
.build())
.build());
// After receiving a response with a compaction block, append the full
// content (including compaction blocks) and continue the conversation
BetaMessage nextResponse = client.beta().messages().create(
MessageCreateParams.builder()
.addBeta("compact-2026-01-12")
.model("claude-opus-5")
.maxTokens(4096L)
.addUserMessage("Help me build a web scraper")
.addMessage(response)
.addUserMessage("Now add error handling")
.contextManagement(BetaContextManagementConfig.builder()
.addEdit(BetaCompact20260112Edit.builder().build())
.build())
.build());
System.out.println(nextResponse);$client = new Client();
$messages = [
['role' => 'user', 'content' => 'Help me build a web scraper']
];
$response = $client->beta->messages->create(
maxTokens: 4096,
messages: $messages,
model: 'claude-opus-5',
betas: ['compact-2026-01-12'],
contextManagement: [
'edits' => [['type' => 'compact_20260112']]
]
);
$messages[] = ['role' => 'assistant', 'content' => $response->content];
$messages[] = ['role' => 'user', 'content' => 'Now add error handling'];
$nextResponse = $client->beta->messages->create(
maxTokens: 4096,
messages: $messages,
model: 'claude-opus-5',
betas: ['compact-2026-01-12'],
contextManagement: [
'edits' => [['type' => 'compact_20260112']]
]
);
echo json_encode($nextResponse, JSON_PRETTY_PRINT), PHP_EOL;client = Anthropic::Client.new
messages = [
{ role: "user", content: "Help me build a web scraper" }
]
response = client.beta.messages.create(
betas: ["compact-2026-01-12"],
model: "claude-opus-5",
max_tokens: 4096,
messages: messages,
context_management: {
edits: [{ type: "compact_20260112" }]
}
)
messages << { role: "assistant", content: response.content }
messages << { role: "user", content: "Now add error handling" }
next_response = client.beta.messages.create(
betas: ["compact-2026-01-12"],
model: "claude-opus-5",
max_tokens: 4096,
messages: messages,
context_management: {
edits: [{ type: "compact_20260112" }]
}
)
puts next_response.contentWhen the API receives a compaction block, all content blocks before it are ignored. You can either:
- Keep the original messages in your list and let the API handle removing the compacted content
- Manually drop the compacted messages and only include the compaction block onwards
On Claude Fable 5.1 and Claude Mythos 5.1, thinking blocks from before a compaction block aren't carried forward, so the summary is all the model has of that earlier work. If you write your own instructions, tell the model what the summary must retain; see Tell the model what to preserve in compaction summaries.
Streaming
The compaction block streams differently from text blocks. You receive a content_block_start event, followed by a single content_block_delta with the complete summary content (no intermediate streaming), and then a content_block_stop event.
ant beta:messages create \
--stream \
--beta compact-2026-01-12 \
--format jsonl <<'YAML'
model: claude-opus-5
max_tokens: 4096
messages:
- role: user
content: Hello, Claude
context_management:
edits:
- type: compact_20260112
YAMLclient = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
with client.beta.messages.stream(
betas=["compact-2026-01-12"],
model="claude-opus-5",
max_tokens=4096,
messages=messages,
context_management={"edits": [{"type": "compact_20260112"}]},
) as stream:
for event in stream:
match event.type:
case "content_block_start":
block = event.content_block
match block.type:
case "compaction":
print("Compaction started...")
case "text":
print("Text response started...")
case "content_block_delta":
delta = event.delta
match delta.type:
case "compaction_delta":
print(f"Compaction complete: {len(delta.content or '')} chars")
case "text_delta":
print(delta.text, end="", flush=True)
# Get the final accumulated message
message = stream.get_final_message()
messages.append({"role": "assistant", "content": message.content})const client = new Anthropic();
const messages: Anthropic.Beta.Messages.BetaMessageParam[] = [
{ role: "user", content: "Hello, Claude" }
];
const stream = await client.beta.messages.stream({
betas: ["compact-2026-01-12"],
model: "claude-opus-5",
max_tokens: 4096,
messages,
context_management: {
edits: [{ type: "compact_20260112" }]
}
});
for await (const event of stream) {
switch (event.type) {
case "content_block_start":
switch (event.content_block.type) {
case "compaction":
console.log("Compaction started...");
break;
case "text":
console.log("Text response started...");
break;
}
break;
case "content_block_delta":
switch (event.delta.type) {
case "compaction_delta":
console.log(`Compaction complete: ${event.delta.content?.length ?? 0} chars`);
break;
case "text_delta":
process.stdout.write(event.delta.text);
break;
}
break;
}
}
// Get the final accumulated message
const message = await stream.finalMessage();
messages.push({
role: "assistant",
content: message.content
});var client = new AnthropicClient();
List<BetaMessageParam> messages = [new() { Role = Role.User, Content = "Hello" }];
var parameters = new MessageCreateParams
{
Betas = ["compact-2026-01-12"],
Model = "claude-opus-5",
MaxTokens = 4096,
Messages = messages,
ContextManagement = new BetaContextManagementConfig
{
Edits = [new BetaCompact20260112Edit()]
}
};
await foreach (var streamEvent in client.Beta.Messages.CreateStreaming(parameters))
{
if (streamEvent.TryPickContentBlockStart(out var startEvent))
{
if (startEvent.ContentBlock.TryPickBetaCompaction(out _))
{
Console.WriteLine("Compaction started...");
}
else if (startEvent.ContentBlock.TryPickBetaText(out _))
{
Console.WriteLine("Text response started...");
}
}
else if (streamEvent.TryPickContentBlockDelta(out var deltaEvent))
{
if (deltaEvent.Delta.TryPickCompaction(out var compactionDelta))
{
Console.WriteLine($"Compaction complete: {compactionDelta.Content?.Length ?? 0} chars");
}
else if (deltaEvent.Delta.TryPickText(out var textDelta))
{
Console.Write(textDelta.Text);
}
}
}client := anthropic.NewClient()
messages := []anthropic.BetaMessageParam{anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello, Claude"))}
stream := client.Beta.Messages.NewStreaming(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5,
MaxTokens: 4096,
Messages: messages,
ContextManagement: anthropic.BetaContextManagementConfigParam{
Edits: []anthropic.BetaContextManagementConfigEditUnionParam{
{OfCompact20260112: &anthropic.BetaCompact20260112EditParam{}},
},
},
Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"},
})
for stream.Next() {
event := stream.Current()
switch eventVariant := event.AsAny().(type) {
case anthropic.BetaRawContentBlockStartEvent:
switch eventVariant.ContentBlock.AsAny().(type) {
case anthropic.BetaCompactionBlock:
fmt.Println("Compaction started...")
case anthropic.BetaTextBlock:
fmt.Println("Text response started...")
}
case anthropic.BetaRawContentBlockDeltaEvent:
switch deltaVariant := eventVariant.Delta.AsAny().(type) {
case anthropic.BetaCompactionContentBlockDelta:
fmt.Printf("Compaction complete: %d chars\n", len(deltaVariant.Content))
case anthropic.BetaTextDelta:
fmt.Print(deltaVariant.Text)
}
}
}
if err := stream.Err(); err != nil {
log.Fatal(err)
}import com.anthropic.models.beta.messages.BetaContextManagementConfig;
import com.anthropic.models.beta.messages.BetaCompact20260112Edit;
// ...
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model("claude-opus-5")
.maxTokens(4096L)
.addBeta("compact-2026-01-12")
.addUserMessage("Hello, Claude")
.contextManagement(BetaContextManagementConfig.builder()
.addEdit(BetaCompact20260112Edit.builder().build())
.build())
.build();
try (var streamResponse = client.beta().messages().createStreaming(params)) {
streamResponse.stream().forEach(event -> {
event.contentBlockStart().ifPresent(startEvent -> {
startEvent.contentBlock().compaction().ifPresent(c ->
System.out.println("Compaction started...")
);
startEvent.contentBlock().text().ifPresent(t ->
System.out.println("Text response started...")
);
});
event.contentBlockDelta().ifPresent(deltaEvent -> {
deltaEvent.delta().compaction().ifPresent(cd ->
System.out.println("Compaction complete: " + cd.content().map(String::length).orElse(0) + " chars")
);
deltaEvent.delta().text().ifPresent(td ->
System.out.print(td.text())
);
});
});
}use Anthropic\Beta\Messages\BetaCompactionBlock;
use Anthropic\Beta\Messages\BetaCompactionContentBlockDelta;
use Anthropic\Beta\Messages\BetaRawContentBlockDeltaEvent;
use Anthropic\Beta\Messages\BetaRawContentBlockStartEvent;
use Anthropic\Beta\Messages\BetaTextBlock;
use Anthropic\Beta\Messages\BetaTextDelta;
$client = new Client();
$messages = [['role' => 'user', 'content' => 'Hello, Claude']];
$stream = $client->beta->messages->createStream(
maxTokens: 4096,
messages: $messages,
model: 'claude-opus-5',
betas: ['compact-2026-01-12'],
contextManagement: [
'edits' => [
['type' => 'compact_20260112']
]
]
);
foreach ($stream as $event) {
switch (true) {
case $event instanceof BetaRawContentBlockStartEvent:
switch (true) {
case $event->contentBlock instanceof BetaCompactionBlock:
echo "Compaction started...\n";
break;
case $event->contentBlock instanceof BetaTextBlock:
echo "Text response started...\n";
break;
}
break;
case $event instanceof BetaRawContentBlockDeltaEvent:
switch (true) {
case $event->delta instanceof BetaCompactionContentBlockDelta:
echo "Compaction complete: " . strlen($event->delta->content ?? '') . " chars\n";
break;
case $event->delta instanceof BetaTextDelta:
echo $event->delta->text;
break;
}
break;
}
}client = Anthropic::Client.new
messages = [{ role: "user", content: "Hello, Claude" }]
stream = client.beta.messages.stream(
betas: ["compact-2026-01-12"],
model: "claude-opus-5",
max_tokens: 4096,
messages: messages,
context_management: {
edits: [{ type: "compact_20260112" }]
}
)
stream.each do |event|
case event
when Anthropic::Models::BetaRawContentBlockStartEvent
case event.content_block
when Anthropic::Models::BetaCompactionBlock
puts "Compaction started..."
when Anthropic::Models::BetaTextBlock
puts "Text response started..."
end
when Anthropic::Models::BetaRawContentBlockDeltaEvent
delta = event.delta
case delta
when Anthropic::Models::BetaCompactionContentBlockDelta
puts "Compaction complete: #{(delta.content || "").length} chars"
when Anthropic::Models::BetaTextDelta
print delta.text
end
end
endPrompt caching
Compaction works well with prompt caching. You can add a cache_control breakpoint on compaction blocks to cache the summarized content.
{
"role": "assistant",
"content": [
{
"type": "compaction",
"content": "[summary text]",
"cache_control": { "type": "ephemeral" }
},
{
"type": "text",
"text": "Based on our conversation..."
}
]
}Maximizing cache hits with system prompts
When compaction occurs, the summary becomes new content that needs to be written to the cache. Without additional cache breakpoints, this would also invalidate any cached system prompt, requiring it to be re-cached along with the compaction summary.
To maximize cache hit rates, add a cache_control breakpoint at the end of your system prompt. This keeps the system prompt cached separately from the conversation, so when compaction occurs:
- The system prompt cache remains valid and is read from cache
- Only the compaction summary needs to be written as a new cache entry
ant beta:messages create --beta compact-2026-01-12 <<'YAML'
model: claude-opus-5
max_tokens: 4096
system:
- type: text
text: You are a helpful coding assistant...
cache_control:
type: ephemeral
messages:
- role: user
content: Hello, Claude
context_management:
edits:
- type: compact_20260112
YAMLclient = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
response = client.beta.messages.create(
betas=["compact-2026-01-12"],
model="claude-opus-5",
max_tokens=4096,
system=[
{
"type": "text",
"text": "You are a helpful coding assistant...",
"cache_control": {
"type": "ephemeral"
}, # Cache the system prompt separately
}
],
messages=messages,
context_management={"edits": [{"type": "compact_20260112"}]},
)const client = new Anthropic();
const messages: Anthropic.Beta.Messages.BetaMessageParam[] = [
{ role: "user", content: "Hello, Claude" }
];
const response = await client.beta.messages.create({
betas: ["compact-2026-01-12"],
model: "claude-opus-5",
max_tokens: 4096,
system: [
{
type: "text",
text: "You are a helpful coding assistant...",
cache_control: { type: "ephemeral" } // Cache the system prompt separately
}
],
messages,
context_management: {
edits: [{ type: "compact_20260112" }]
}
});var client = new AnthropicClient();
var parameters = new MessageCreateParams
{
Betas = ["compact-2026-01-12"],
Model = "claude-opus-5",
MaxTokens = 4096,
System = new List<BetaTextBlockParam>
{
new()
{
Text = "You are a helpful coding assistant...",
CacheControl = new BetaCacheControlEphemeral()
}
},
Messages = [new() { Role = Role.User, Content = "Hello, Claude" }],
ContextManagement = new BetaContextManagementConfig
{
Edits = [new BetaCompact20260112Edit()]
}
};
var response = await client.Beta.Messages.Create(parameters);
Console.WriteLine(response);client := anthropic.NewClient()
response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5,
MaxTokens: 4096,
System: []anthropic.BetaTextBlockParam{
{
Text: "You are a helpful coding assistant...",
CacheControl: anthropic.NewBetaCacheControlEphemeralParam(),
},
},
Messages: []anthropic.BetaMessageParam{anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello, Claude"))},
ContextManagement: anthropic.BetaContextManagementConfigParam{
Edits: []anthropic.BetaContextManagementConfigEditUnionParam{
{OfCompact20260112: &anthropic.BetaCompact20260112EditParam{}},
},
},
Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)import com.anthropic.models.beta.messages.BetaContextManagementConfig;
import com.anthropic.models.beta.messages.BetaCompact20260112Edit;
import com.anthropic.models.beta.messages.BetaCacheControlEphemeral;
// ...
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model("claude-opus-5")
.maxTokens(4096L)
.addBeta("compact-2026-01-12")
.systemOfBetaTextBlockParams(List.of(
BetaTextBlockParam.builder()
.text("You are a helpful coding assistant...")
.cacheControl(BetaCacheControlEphemeral.builder().build())
.build()
))
.addUserMessage("Hello, Claude")
.contextManagement(BetaContextManagementConfig.builder()
.addEdit(BetaCompact20260112Edit.builder().build())
.build())
.build();
BetaMessage response = client.beta().messages().create(params);
System.out.println(response);$client = new Client();
$response = $client->beta->messages->create(
maxTokens: 4096,
messages: [['role' => 'user', 'content' => 'Hello, Claude']],
model: 'claude-opus-5',
betas: ['compact-2026-01-12'],
system: [
[
'type' => 'text',
'text' => 'You are a helpful coding assistant...',
'cache_control' => [
'type' => 'ephemeral'
]
]
],
contextManagement: [
'edits' => [
['type' => 'compact_20260112']
]
]
);
echo json_encode($response, JSON_PRETTY_PRINT), PHP_EOL;client = Anthropic::Client.new
response = client.beta.messages.create(
betas: ["compact-2026-01-12"],
model: "claude-opus-5",
max_tokens: 4096,
system: [
{
type: "text",
text: "You are a helpful coding assistant...",
cache_control: {
type: "ephemeral"
}
}
],
messages: [{ role: "user", content: "Hello, Claude" }],
context_management: {
edits: [{ type: "compact_20260112" }]
}
)
puts responseThis keeps long system prompts cached across multiple compaction events throughout a conversation.
Understanding usage
Compaction requires an additional sampling step, which contributes to rate limits and billing. The API returns detailed usage information in the response:
{
"usage": {
"input_tokens": 23000,
"output_tokens": 1000,
"iterations": [
{
"type": "compaction",
"input_tokens": 180000,
"output_tokens": 3500
},
{
"type": "message",
"input_tokens": 23000,
"output_tokens": 1000
}
]
}
}The iterations array shows usage for each sampling iteration. When compaction occurs, you'll see a compaction iteration followed by the main message iteration. The top-level input_tokens and output_tokens match the message iteration exactly in this example because there is only one non-compaction iteration. The final iteration's token counts reflect the effective context size after compaction.
If you previously relied on usage.input_tokens and usage.output_tokens for cost tracking or auditing, you'll need to update your tracking logic to aggregate across usage.iterations when compaction is enabled. With the compaction beta enabled, every response includes usage.iterations, even if no compaction occurred. A compaction entry appears only when a new compaction is triggered during the request. Re-applying a previous compaction block incurs no additional compaction cost, and the top-level usage fields remain accurate in that case.
Combining with other features
Server tools
When using server tools (such as web search), the compaction trigger is checked at the start of each sampling iteration. Compaction might occur multiple times within a single request depending on your trigger threshold and the amount of output generated.
Token counting
The token counting endpoint (/v1/messages/count_tokens) applies existing compaction blocks in your prompt but does not trigger new compactions. Use it to check your effective token count after previous compactions:
cat > request.yaml <<'YAML'
model: claude-opus-5
messages:
- role: user
content: Hello, Claude
context_management:
edits:
- type: compact_20260112
YAML
CURRENT=$(ant beta:messages count-tokens \
--beta compact-2026-01-12 \
--transform input_tokens \
--raw-output < request.yaml)
ORIGINAL=$(ant beta:messages count-tokens \
--beta compact-2026-01-12 \
--transform context_management.original_input_tokens \
--raw-output < request.yaml)
printf 'Current tokens: %s\n' "$CURRENT"
printf 'Original tokens: %s\n' "$ORIGINAL"client = anthropic.Anthropic()
messages = [{"role": "user", "content": "Hello, Claude"}]
count_response = client.beta.messages.count_tokens(
betas=["compact-2026-01-12"],
model="claude-opus-5",
messages=messages,
context_management={"edits": [{"type": "compact_20260112"}]},
)
print(f"Current tokens: {count_response.input_tokens}")
print(f"Original tokens: {count_response.context_management.original_input_tokens}")const client = new Anthropic();
const messages: Anthropic.Beta.Messages.BetaMessageParam[] = [
{ role: "user", content: "Summarize the key points of our conversation so far." }
];
const countResponse = await client.beta.messages.countTokens({
betas: ["compact-2026-01-12"],
model: "claude-opus-5",
messages,
context_management: {
edits: [{ type: "compact_20260112" }]
}
});
console.log(`Current tokens: ${countResponse.input_tokens}`);
console.log(`Original tokens: ${countResponse.context_management!.original_input_tokens}`);AnthropicClient client = new();
List<BetaMessageParam> messages = [new() { Role = Role.User, Content = "Hello" }];
var countParams = new MessageCountTokensParams
{
Model = "claude-opus-5",
Messages = messages,
ContextManagement = new BetaContextManagementConfig
{
Edits = [new BetaCompact20260112Edit()]
},
Betas = ["compact-2026-01-12"]
};
var countResponse = await client.Beta.Messages.CountTokens(countParams);
Console.WriteLine($"Current tokens: {countResponse.InputTokens}");
Console.WriteLine($"Original tokens: {countResponse.ContextManagement?.OriginalInputTokens}");client := anthropic.NewClient()
messages := []anthropic.BetaMessageParam{anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello, Claude"))}
countResponse, err := client.Beta.Messages.CountTokens(context.TODO(), anthropic.BetaMessageCountTokensParams{
Model: anthropic.ModelClaudeOpus5,
Messages: messages,
ContextManagement: anthropic.BetaContextManagementConfigParam{
Edits: []anthropic.BetaContextManagementConfigEditUnionParam{
{OfCompact20260112: &anthropic.BetaCompact20260112EditParam{}},
},
},
Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"},
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Current tokens: %d\n", countResponse.InputTokens)
fmt.Printf("Original tokens: %d\n", countResponse.ContextManagement.OriginalInputTokens)import com.anthropic.models.beta.messages.BetaMessageTokensCount;
import com.anthropic.models.beta.messages.MessageCountTokensParams;
import com.anthropic.models.beta.messages.BetaContextManagementConfig;
import com.anthropic.models.beta.messages.BetaCompact20260112Edit;
// ...
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCountTokensParams params = MessageCountTokensParams.builder()
.model("claude-opus-5")
.addUserMessage("Hello, Claude")
.contextManagement(BetaContextManagementConfig.builder()
.addEdit(BetaCompact20260112Edit.builder().build())
.build())
.addBeta("compact-2026-01-12")
.build();
BetaMessageTokensCount countResponse = client.beta().messages().countTokens(params);
System.out.println("Current tokens: " + countResponse.inputTokens());
System.out.println("Original tokens: " + countResponse.contextManagement().get().originalInputTokens());$client = new Client();
$messages = [['role' => 'user', 'content' => 'Hello, Claude']];
$countResponse = $client->beta->messages->countTokens(
messages: $messages,
model: 'claude-opus-5',
betas: ['compact-2026-01-12'],
contextManagement: [
'edits' => [
['type' => 'compact_20260112']
]
]
);
echo "Current tokens: " . $countResponse->inputTokens . "\n";
echo "Original tokens: " . $countResponse->contextManagement->originalInputTokens . "\n";client = Anthropic::Client.new
messages = [{ role: "user", content: "Hello, Claude" }]
count_response = client.beta.messages.count_tokens(
betas: ["compact-2026-01-12"],
model: "claude-opus-5",
messages: messages,
context_management: {
edits: [{ type: "compact_20260112" }]
}
)
puts "Current tokens: #{count_response.input_tokens}"
puts "Original tokens: #{count_response.context_management.original_input_tokens}"Examples
Here's a complete example of a long-running conversation with compaction:
```bash cURL # curl sends individual requests; maintain the messages array in the # calling script. See the SDK tabs for the full chat() loop. Single-turn # request shape: curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: compact-2026-01-12" \ -H "content-type: application/json" \ -d '{ "model": "claude-opus-5", "max_tokens": 4096, "messages": [ { "role": "user", "content": "Help me build a Python web scraper" } ], "context_management": { "edits": [ { "type": "compact_20260112", "trigger": { "type": "input_tokens", "value": 100000 } } ] } }' ```# The CLI handles individual turns; maintain the messages array in the
# calling script. See the SDK tabs for the full chat() loop. Single-turn
# request shape:
ant beta:messages create \
--beta compact-2026-01-12 \
--transform 'content.#(type=="text").text' \
--raw-output <<'YAML'
model: claude-opus-5
max_tokens: 4096
messages:
- role: user
content: Help me build a Python web scraper
context_management:
edits:
- type: compact_20260112
trigger:
type: input_tokens
value: 100000
YAMLclient = anthropic.Anthropic()
messages: list[dict] = []
def chat(user_message: str) -> str:
messages.append({"role": "user", "content": user_message})
response = client.beta.messages.create(
betas=["compact-2026-01-12"],
model="claude-opus-5",
max_tokens=4096,
messages=messages,
context_management={
"edits": [
{
"type": "compact_20260112",
"trigger": {"type": "input_tokens", "value": 100000},
}
]
},
)
# Append response (compaction blocks are automatically included)
messages.append({"role": "assistant", "content": response.content})
# Return the text content
return next(block.text for block in response.content if block.type == "text")
# Run a long conversation
print(chat("Help me build a Python web scraper"))
print(chat("Add support for JavaScript-rendered pages"))
print(chat("Now add rate limiting and error handling"))
# Continue calling chat() for as long as the conversation needsconst client = new Anthropic();
const messages: Anthropic.Beta.Messages.BetaMessageParam[] = [];
async function chat(userMessage: string): Promise<string> {
messages.push({ role: "user", content: userMessage });
const response = await client.beta.messages.create({
betas: ["compact-2026-01-12"],
model: "claude-opus-5",
max_tokens: 4096,
messages,
context_management: {
edits: [
{
type: "compact_20260112",
trigger: { type: "input_tokens", value: 100000 }
}
]
}
});
// Append response (compaction blocks are automatically included)
messages.push({ role: "assistant", content: response.content });
// Return the text content
const textBlock = response.content.find((block) => block.type === "text");
return textBlock?.text ?? "";
}
// Run a long conversation
console.log(await chat("Help me build a Python web scraper"));
console.log(await chat("Add support for JavaScript-rendered pages"));
console.log(await chat("Now add rate limiting and error handling"));
// Continue calling chat() for as long as the conversation needsAnthropicClient client = new();
List<BetaMessageParam> messages = new();
Console.WriteLine(await Chat(client, messages, "Help me build a Python web scraper"));
Console.WriteLine(await Chat(client, messages, "Add support for JavaScript-rendered pages"));
Console.WriteLine(await Chat(client, messages, "Now add rate limiting and error handling"));
static async Task<string> Chat(AnthropicClient client, List<BetaMessageParam> messages, string userMessage)
{
messages.Add(new() { Role = Role.User, Content = userMessage });
var parameters = new MessageCreateParams
{
Betas = ["compact-2026-01-12"],
Model = "claude-opus-5",
MaxTokens = 4096,
Messages = messages,
ContextManagement = new BetaContextManagementConfig
{
Edits = [new BetaCompact20260112Edit
{
Trigger = new BetaInputTokensTrigger(100000)
}]
}
};
var response = await client.Beta.Messages.Create(parameters);
messages.Add(new()
{
Role = Role.Assistant,
Content = response.Content.Select(block => new BetaContentBlockParam(block.Json)).ToList()
});
return response.Content
.Select(block => block.Value)
.OfType<BetaTextBlock>()
.Select(tb => tb.Text)
.FirstOrDefault() ?? "";
}package main
import (
"context"
"fmt"
"log"
"github.com/anthropics/anthropic-sdk-go"
)
var (
client = anthropic.NewClient()
messages []anthropic.BetaMessageParam
)
func chat(userMessage string) string {
messages = append(messages, anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock(userMessage)))
response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5,
MaxTokens: 4096,
Messages: messages,
ContextManagement: anthropic.BetaContextManagementConfigParam{
Edits: []anthropic.BetaContextManagementConfigEditUnionParam{
{OfCompact20260112: &anthropic.BetaCompact20260112EditParam{
Trigger: anthropic.BetaInputTokensTriggerParam{Value: 100000},
}},
},
},
Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"},
})
if err != nil {
log.Fatal(err)
}
messages = append(messages, response.ToParam())
for _, block := range response.Content {
if variant, ok := block.AsAny().(anthropic.BetaTextBlock); ok {
return variant.Text
}
}
return ""
}
func main() {
fmt.Println(chat("Help me build a Python web scraper"))
fmt.Println(chat("Add support for JavaScript-rendered pages"))
fmt.Println(chat("Now add rate limiting and error handling"))
}import com.anthropic.models.beta.messages.BetaContextManagementConfig;
import com.anthropic.models.beta.messages.BetaCompact20260112Edit;
import com.anthropic.models.beta.messages.BetaInputTokensTrigger;
// ...
private static final AnthropicClient client = AnthropicOkHttpClient.fromEnv();
private static final List<BetaMessageParam> messages = new ArrayList<>();
public static void main(String[] args) {
System.out.println(chat("Help me build a Python web scraper"));
System.out.println(chat("Add support for JavaScript-rendered pages"));
System.out.println(chat("Now add rate limiting and error handling"));
}
private static String chat(String userMessage) {
messages.add(BetaMessageParam.builder()
.role(BetaMessageParam.Role.USER)
.content(userMessage)
.build());
MessageCreateParams params = MessageCreateParams.builder()
.addBeta("compact-2026-01-12")
.model("claude-opus-5")
.maxTokens(4096L)
.messages(messages)
.contextManagement(BetaContextManagementConfig.builder()
.addEdit(BetaCompact20260112Edit.builder()
.trigger(BetaInputTokensTrigger.builder()
.value(100000L)
.build())
.build())
.build())
.build();
BetaMessage response = client.beta().messages().create(params);
// Append response (compaction blocks are automatically included)
messages.add(response.toParam());
return response.content().stream()
.filter(block -> block.text().isPresent())
.map(block -> block.text().get().text())
.findFirst()
.orElse("");
}$client = new Client();
$messages = [];
function chat($client, &$messages, $userMessage) {
$messages[] = ['role' => 'user', 'content' => $userMessage];
$response = $client->beta->messages->create(
maxTokens: 4096,
messages: $messages,
model: 'claude-opus-5',
betas: ['compact-2026-01-12'],
contextManagement: [
'edits' => [
[
'type' => 'compact_20260112',
'trigger' => ['type' => 'input_tokens', 'value' => 100000]
]
]
]
);
$messages[] = ['role' => 'assistant', 'content' => $response->content];
foreach ($response->content as $block) {
if ($block->type === 'text') {
return $block->text;
}
}
return '';
}
echo chat($client, $messages, "Help me build a Python web scraper") . "\n";
echo chat($client, $messages, "Add support for JavaScript-rendered pages") . "\n";
echo chat($client, $messages, "Now add rate limiting and error handling") . "\n";client = Anthropic::Client.new
messages = []
def chat(client, messages, user_message)
messages << { role: "user", content: user_message }
response = client.beta.messages.create(
betas: ["compact-2026-01-12"],
model: "claude-opus-5",
max_tokens: 4096,
messages: messages,
context_management: {
edits: [
{
type: "compact_20260112",
trigger: { type: "input_tokens", value: 100000 }
}
]
}
)
messages << { role: "assistant", content: response.content }
response.content.find { |block| block.type == :text }&.text || ""
end
puts chat(client, messages, "Help me build a Python web scraper")
puts chat(client, messages, "Add support for JavaScript-rendered pages")
puts chat(client, messages, "Now add rate limiting and error handling")On Claude Fable 5.1, remove the thinking and redacted_thinking blocks from any assistant turn you re-insert after the compaction block, or send thinking.block_binding.prefix_mismatch_behavior: "drop_block" with the thinking-binding-controls-2026-08-01 beta header. Those blocks were produced when the full history was present, so they no longer pass the conversation check. Where the check is enforced, the continuation request is rejected with a 400 error. The preserved text and tool blocks can stay as they are. Letting the API summarize everything, without re-inserting earlier turns, avoids this.
Here's an example that uses pause_after_compaction to preserve the prior exchange and the current user message (three messages total) verbatim instead of summarizing them:
# The CLI handles individual turns; maintain the messages array in the
# calling script. See the SDK tabs for the full chat() loop with
# pause-and-preserve handling. Single-turn request shape:
ant beta:messages create \
--beta compact-2026-01-12 \
--transform 'content.#(type=="text").text' \
--raw-output <<'YAML'
model: claude-opus-5
max_tokens: 4096
messages:
- role: user
content: Help me build a Python web scraper
context_management:
edits:
- type: compact_20260112
trigger:
type: input_tokens
value: 100000
pause_after_compaction: true
YAMLfrom typing import Any
client = anthropic.Anthropic()
messages: list[dict[str, Any]] = []
def chat(user_message: str) -> str:
messages.append({"role": "user", "content": user_message})
response = client.beta.messages.create(
betas=["compact-2026-01-12"],
model="claude-opus-5",
max_tokens=4096,
messages=messages,
context_management={
"edits": [
{
"type": "compact_20260112",
"trigger": {"type": "input_tokens", "value": 100000},
"pause_after_compaction": True,
}
]
},
)
# Check if compaction occurred and paused
if response.stop_reason == "compaction":
# Get the compaction block from the response
compaction_block = response.content[0]
# Preserve the prior exchange + current user message (3 messages)
# by including them after the compaction block
preserved_messages = messages[-3:] if len(messages) >= 3 else messages
# Build new message list: compaction + preserved messages
new_assistant_content = [compaction_block]
messages_after_compaction = [
{"role": "assistant", "content": new_assistant_content}
] + preserved_messages
# Continue the request with the compacted context + preserved messages
response = client.beta.messages.create(
betas=["compact-2026-01-12"],
model="claude-opus-5",
max_tokens=4096,
messages=messages_after_compaction,
context_management={"edits": [{"type": "compact_20260112"}]},
)
# Update the message list to reflect the compaction
messages.clear()
messages.extend(messages_after_compaction)
# Append the final response
messages.append({"role": "assistant", "content": response.content})
# Return the text content
return next(block.text for block in response.content if block.type == "text")
# Run a long conversation
print(chat("Help me build a Python web scraper"))
print(chat("Add support for JavaScript-rendered pages"))
print(chat("Now add rate limiting and error handling"))
# Continue calling chat() for as long as the conversation needsconst client = new Anthropic();
let messages: Anthropic.Beta.Messages.BetaMessageParam[] = [];
async function chat(userMessage: string): Promise<string> {
messages.push({ role: "user", content: userMessage });
let response = await client.beta.messages.create({
betas: ["compact-2026-01-12"],
model: "claude-opus-5",
max_tokens: 4096,
messages,
context_management: {
edits: [
{
type: "compact_20260112",
trigger: { type: "input_tokens", value: 100000 },
pause_after_compaction: true
}
]
}
});
// Check if compaction occurred and paused
if (response.stop_reason === "compaction") {
// Get the compaction block from the response
const compactionBlock = response.content[0];
// Preserve the prior exchange + current user message (3 messages)
// by including them after the compaction block
const preservedMessages = messages.length >= 3 ? messages.slice(-3) : [...messages];
// Build new message list: compaction + preserved messages
const messagesAfterCompaction: Anthropic.Beta.Messages.BetaMessageParam[] = [
{ role: "assistant", content: [compactionBlock] },
...preservedMessages
];
// Continue the request with the compacted context + preserved messages
response = await client.beta.messages.create({
betas: ["compact-2026-01-12"],
model: "claude-opus-5",
max_tokens: 4096,
messages: messagesAfterCompaction,
context_management: {
edits: [{ type: "compact_20260112" }]
}
});
// Update the message list to reflect the compaction
messages = messagesAfterCompaction;
}
// Append the final response
messages.push({ role: "assistant", content: response.content });
// Return the text content
const textBlock = response.content.find((block) => block.type === "text");
return textBlock?.text ?? "";
}
// Run a long conversation
console.log(await chat("Help me build a Python web scraper"));
console.log(await chat("Add support for JavaScript-rendered pages"));
console.log(await chat("Now add rate limiting and error handling"));
// Continue calling chat() for as long as the conversation needsAnthropicClient client = new();
List<BetaMessageParam> messages = new();
Console.WriteLine(await Chat("Help me build a Python web scraper"));
Console.WriteLine(await Chat("Add support for JavaScript-rendered pages"));
Console.WriteLine(await Chat("Now add rate limiting and error handling"));
async Task<string> Chat(string userMessage)
{
messages.Add(new() { Role = Role.User, Content = userMessage });
var response = await client.Beta.Messages.Create(new()
{
Betas = ["compact-2026-01-12"],
Model = "claude-opus-5",
MaxTokens = 4096,
Messages = messages,
ContextManagement = new BetaContextManagementConfig
{
Edits = [new BetaCompact20260112Edit
{
Trigger = new BetaInputTokensTrigger(100000),
PauseAfterCompaction = true
}]
}
});
if (response.StopReason == BetaStopReason.Compaction)
{
if (!response.Content[0].TryPickCompaction(out _))
throw new InvalidOperationException("Expected compaction block");
var preserved = messages.Count >= 3
? messages.Skip(messages.Count - 3).ToList()
: new List<BetaMessageParam>(messages);
var messagesAfterCompaction = new List<BetaMessageParam>
{
new()
{
Role = Role.Assistant,
Content = new List<BetaContentBlockParam> { new BetaContentBlockParam(response.Content[0].Json) }
}
};
messagesAfterCompaction.AddRange(preserved);
response = await client.Beta.Messages.Create(new()
{
Betas = ["compact-2026-01-12"],
Model = "claude-opus-5",
MaxTokens = 4096,
Messages = messagesAfterCompaction,
ContextManagement = new BetaContextManagementConfig
{
Edits = [new BetaCompact20260112Edit()]
}
});
messages = messagesAfterCompaction;
}
messages.Add(new()
{
Role = Role.Assistant,
Content = response.Content.Select(block => new BetaContentBlockParam(block.Json)).ToList()
});
return response.Content
.Select(block => block.Value)
.OfType<BetaTextBlock>()
.Select(tb => tb.Text)
.FirstOrDefault() ?? "";
}package main
import (
"context"
"fmt"
"log"
"github.com/anthropics/anthropic-sdk-go"
)
var (
client = anthropic.NewClient()
messages []anthropic.BetaMessageParam
)
func chat(userMessage string) string {
messages = append(messages, anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock(userMessage)))
compactEdit := anthropic.BetaContextManagementConfigParam{
Edits: []anthropic.BetaContextManagementConfigEditUnionParam{
{OfCompact20260112: &anthropic.BetaCompact20260112EditParam{
Trigger: anthropic.BetaInputTokensTriggerParam{Value: 100000},
PauseAfterCompaction: anthropic.Bool(true),
}},
},
}
response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5,
MaxTokens: 4096,
Messages: messages,
ContextManagement: compactEdit,
Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"},
})
if err != nil {
log.Fatal(err)
}
if response.StopReason == "compaction" {
compactionParam := response.Content[0].ToParam()
var preserved []anthropic.BetaMessageParam
if len(messages) >= 3 {
preserved = messages[len(messages)-3:]
} else {
preserved = messages
}
messagesAfterCompaction := []anthropic.BetaMessageParam{
{Role: anthropic.BetaMessageParamRoleAssistant, Content: []anthropic.BetaContentBlockParamUnion{compactionParam}},
}
messagesAfterCompaction = append(messagesAfterCompaction, preserved...)
response, err = client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5,
MaxTokens: 4096,
Messages: messagesAfterCompaction,
ContextManagement: anthropic.BetaContextManagementConfigParam{
Edits: []anthropic.BetaContextManagementConfigEditUnionParam{
{OfCompact20260112: &anthropic.BetaCompact20260112EditParam{}},
},
},
Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"},
})
if err != nil {
log.Fatal(err)
}
messages = messagesAfterCompaction
}
messages = append(messages, response.ToParam())
for _, block := range response.Content {
if textBlock, ok := block.AsAny().(anthropic.BetaTextBlock); ok {
return textBlock.Text
}
}
return ""
}
func main() {
fmt.Println(chat("Help me build a Python web scraper"))
fmt.Println(chat("Add support for JavaScript-rendered pages"))
fmt.Println(chat("Now add rate limiting and error handling"))
}import com.anthropic.models.beta.messages.BetaContextManagementConfig;
import com.anthropic.models.beta.messages.BetaCompact20260112Edit;
import com.anthropic.models.beta.messages.BetaInputTokensTrigger;
import com.anthropic.models.beta.messages.BetaStopReason;
// ...
private static final AnthropicClient client = AnthropicOkHttpClient.fromEnv();
private static final List<BetaMessageParam> messages = new ArrayList<>();
public static String chat(String userMessage) {
messages.add(BetaMessageParam.builder()
.role(BetaMessageParam.Role.USER)
.content(userMessage)
.build());
MessageCreateParams params = MessageCreateParams.builder()
.addBeta("compact-2026-01-12")
.model("claude-opus-5")
.maxTokens(4096L)
.messages(messages)
.contextManagement(BetaContextManagementConfig.builder()
.addEdit(BetaCompact20260112Edit.builder()
.trigger(BetaInputTokensTrigger.builder()
.value(100000L)
.build())
.pauseAfterCompaction(true)
.build())
.build())
.build();
BetaMessage response = client.beta().messages().create(params);
// Check if compaction occurred and paused
if (response.stopReason().isPresent()
&& response.stopReason().get().equals(BetaStopReason.COMPACTION)) {
// Preserve the prior exchange + current user message (3 messages)
List<BetaMessageParam> preservedMessages = messages.size() >= 3
? new ArrayList<>(messages.subList(messages.size() - 3, messages.size()))
: new ArrayList<>(messages);
// Build new message list: compaction + preserved messages
List<BetaMessageParam> messagesAfterCompaction = new ArrayList<>();
messagesAfterCompaction.add(response.toParam());
messagesAfterCompaction.addAll(preservedMessages);
// Continue the request with the compacted context + preserved messages
MessageCreateParams continueParams = MessageCreateParams.builder()
.addBeta("compact-2026-01-12")
.model("claude-opus-5")
.maxTokens(4096L)
.messages(messagesAfterCompaction)
.contextManagement(BetaContextManagementConfig.builder()
.addEdit(BetaCompact20260112Edit.builder().build())
.build())
.build();
response = client.beta().messages().create(continueParams);
// Update the message list to reflect the compaction
messages.clear();
messages.addAll(messagesAfterCompaction);
}
// Append the final response
messages.add(response.toParam());
return response.content().stream()
.filter(block -> block.text().isPresent())
.map(block -> block.text().get().text())
.findFirst()
.orElse("");
}
public static void main(String[] args) {
System.out.println(chat("Help me build a Python web scraper"));
System.out.println(chat("Add support for JavaScript-rendered pages"));
System.out.println(chat("Now add rate limiting and error handling"));
}$client = new Client();
$messages = [];
function chat($client, &$messages, $userMessage) {
$messages[] = ['role' => 'user', 'content' => $userMessage];
$response = $client->beta->messages->create(
maxTokens: 4096,
messages: $messages,
model: 'claude-opus-5',
betas: ['compact-2026-01-12'],
contextManagement: [
'edits' => [
[
'type' => 'compact_20260112',
'trigger' => ['type' => 'input_tokens', 'value' => 100000],
'pause_after_compaction' => true
]
]
]
);
if ($response->stopReason === 'compaction') {
$compactionBlock = $response->content[0];
$preserved = count($messages) >= 3
? array_slice($messages, -3)
: $messages;
$messagesAfterCompaction = array_merge(
[['role' => 'assistant', 'content' => [$compactionBlock]]],
$preserved
);
$response = $client->beta->messages->create(
maxTokens: 4096,
messages: $messagesAfterCompaction,
model: 'claude-opus-5',
betas: ['compact-2026-01-12'],
contextManagement: [
'edits' => [['type' => 'compact_20260112']]
]
);
$messages = $messagesAfterCompaction;
}
$messages[] = ['role' => 'assistant', 'content' => $response->content];
foreach ($response->content as $block) {
if ($block->type === 'text') {
return $block->text;
}
}
return '';
}
echo chat($client, $messages, "Help me build a Python web scraper") . "\n";
echo chat($client, $messages, "Add support for JavaScript-rendered pages") . "\n";
echo chat($client, $messages, "Now add rate limiting and error handling") . "\n";client = Anthropic::Client.new
messages = []
def chat(client, messages, user_message)
messages << { role: "user", content: user_message }
response = client.beta.messages.create(
betas: ["compact-2026-01-12"],
model: "claude-opus-5",
max_tokens: 4096,
messages: messages,
context_management: {
edits: [
{
type: "compact_20260112",
trigger: { type: "input_tokens", value: 100000 },
pause_after_compaction: true
}
]
}
)
if response.stop_reason == :compaction
compaction_block = response.content[0]
preserved = messages.length >= 3 ? messages[-3..-1] : messages.dup
messages_after_compaction = [
{ role: "assistant", content: [compaction_block] }
] + preserved
response = client.beta.messages.create(
betas: ["compact-2026-01-12"],
model: "claude-opus-5",
max_tokens: 4096,
messages: messages_after_compaction,
context_management: {
edits: [{ type: "compact_20260112" }]
}
)
messages.clear
messages.concat(messages_after_compaction)
end
messages << { role: "assistant", content: response.content }
response.content.find { |block| block.type == :text }&.text || ""
end
puts chat(client, messages, "Help me build a Python web scraper")
puts chat(client, messages, "Add support for JavaScript-rendered pages")
puts chat(client, messages, "Now add rate limiting and error handling")Current limitations
-
Same model for summarization: The model specified in your request is used for summarization. There is no option to use a different (for example, cheaper) model for the summary.
-
Compaction might fail when tools are defined: When your request includes
tools, the model occasionally calls a tool during the internal summarization step instead of writing a summary. When this occurs, the response contains acompactionblock withcontent: null. To prevent this, setinstructionsto a prompt that explicitly tells the model not to call tools, for example:textSummarize the transcript inside <summary></summary> tags. Include relevant information in the summary for continuing the task in the next context window. Do not call any tools while writing this summary; respond with text only.
Compact on demand with the compaction parameter
The compact-2026-09-04 beta adds a second way to compact. Threshold compaction summarizes partway through a request once the threshold you set is reached. With this beta, you instead send the top-level compaction parameter on a request of your choosing. The response contains a single signed compaction block and no reply. From then on, send that block first in messages, in place of the messages it summarizes, followed by any turns taken since. Claude sees the summary where those messages were. Everything after the summary reaches Claude unchanged. A threshold compaction block follows the messages it summarizes, but a signed block replaces them. Leaving the summarized messages in front of a signed block is a 400 error.
Compacting this way gives you three things. First, you decide when to compact. Second, the summarization request can run in the background while the conversation continues on its full history, and you swap the block in when it arrives. This is often called async or background compaction. Third, you can keep recent turns word for word after the summary, which is often called keep-tail compaction. Models with preserved thinking check earlier thinking blocks against the conversation. On those models, the thinking in turns that follow the summary, from either pattern, can stay valid after the swap, under the conditions in Continue from the summary. That lets a long-running agent keep its train of thought. Use threshold compaction when you want the API to manage context inside ordinary requests. Use the compaction parameter when your application needs to control when compaction happens, can't pause while a summary is written, or must keep recent turns and their thinking after the summary.
Send the compact-2026-09-04 beta header on the request that asks for the summary and on every later request that carries the signed block. On-demand compaction is available on the Claude API but not on Amazon Bedrock or Google Cloud. It works on Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5, and Claude Sonnet 4.6. You can also call the Models API with the beta header and read each model's capabilities.compaction. You can't combine compaction with context_management on one request.
Request a summary
Send the conversation as it stands with "compaction": {"type": "summarize"}. The API summarizes every message in the request once, generates no reply after it, and returns the block alone with stop_reason "compaction". Send the same system prompt and tools that you use for the rest of the conversation. The summarizer reads them, and on models with preserved thinking, the turns you keep stay valid only if they match. The conversation in this example has no system prompt or tools, so the request sends neither:
<File filename="request.yaml">
```yaml
model: claude-opus-5
# max_tokens caps the whole call, including any thinking, so allow several thousand tokens.
max_tokens: 4096
messages:
- role: user
content: I am building a recipe app. Help me name the main entities in the data model.
- role: assistant
content: Start with Recipe, Ingredient, and Step. Add a RecipeIngredient entry that holds the quantity and unit for each ingredient in a recipe.
- role: user
content: Good. Now suggest field names for Recipe.
compaction:
type: summarize
```
</File>
from anthropic.types.beta import BetaMessageParam
client = anthropic.Anthropic()
history: list[BetaMessageParam] = [
{
"role": "user",
"content": "I am building a recipe app. Help me name the main entities in the data model.",
},
{
"role": "assistant",
"content": "Start with Recipe, Ingredient, and Step. Add a RecipeIngredient entry that holds the quantity and unit for each ingredient in a recipe.",
},
{"role": "user", "content": "Good. Now suggest field names for Recipe."},
]
response = client.beta.messages.create(
model="claude-opus-5",
# max_tokens caps the whole call, including any thinking, so allow several thousand tokens.
max_tokens=4096,
betas=["compact-2026-09-04"],
messages=history,
compaction={"type": "summarize"},
)
print(f"Stop reason: {response.stop_reason}")const client = new Anthropic();
const history: Anthropic.Beta.Messages.BetaMessageParam[] = [
{
role: "user",
content: "I am building a recipe app. Help me name the main entities in the data model."
},
{
role: "assistant",
content:
"Start with Recipe, Ingredient, and Step. Add a RecipeIngredient entry that holds the quantity and unit for each ingredient in a recipe."
},
{ role: "user", content: "Good. Now suggest field names for Recipe." }
];
const response = await client.beta.messages.create({
model: "claude-opus-5",
// max_tokens caps the whole call, including any thinking, so allow several thousand tokens.
max_tokens: 4096,
betas: ["compact-2026-09-04"],
messages: history,
compaction: { type: "summarize" }
});
console.log(`Stop reason: ${response.stop_reason}`);using Anthropic.Models.Beta;
using Anthropic.Models.Beta.Messages;
using Model = Anthropic.Models.Messages.Model;
AnthropicClient client = new();
List<BetaMessageParam> history =
[
new()
{
Role = Role.User,
Content = "I am building a recipe app. Help me name the main entities in the data model.",
},
new()
{
Role = Role.Assistant,
Content = "Start with Recipe, Ingredient, and Step. Add a RecipeIngredient entry that holds the quantity and unit for each ingredient in a recipe.",
},
new() { Role = Role.User, Content = "Good. Now suggest field names for Recipe." },
];
var response = await client.Beta.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus5,
// max_tokens caps the whole call, including any thinking, so allow several thousand tokens.
MaxTokens = 4096,
Betas = [AnthropicBeta.Compact2026_09_04],
Messages = history,
Compaction = new BetaCompactionConfig(), // type defaults to "summarize"
});
Console.WriteLine($"Stop reason: {response.StopReason?.Raw()}");client := anthropic.NewClient()
history := []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("I am building a recipe app. Help me name the main entities in the data model.")),
{
Role: anthropic.BetaMessageParamRoleAssistant,
Content: []anthropic.BetaContentBlockParamUnion{anthropic.NewBetaTextBlock("Start with Recipe, Ingredient, and Step. Add a RecipeIngredient entry that holds the quantity and unit for each ingredient in a recipe.")},
},
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Good. Now suggest field names for Recipe.")),
}
response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeOpus5,
// max_tokens caps the whole call, including any thinking, so allow several thousand tokens.
MaxTokens: 4096,
Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaCompact2026_09_04},
Messages: history,
Compaction: anthropic.BetaCompactionConfigUnionParam{
OfSummarize: &anthropic.BetaSummarizeCompactionParam{},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println("Stop reason:", response.StopReason)import com.anthropic.models.beta.AnthropicBeta;
import com.anthropic.models.beta.messages.BetaCompactionConfig;
import com.anthropic.models.beta.messages.MessageCreateParams;
void main() {
var client = AnthropicOkHttpClient.fromEnv();
var params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5)
// max_tokens caps the whole call, including any thinking, so allow several thousand tokens.
.maxTokens(4096)
.addBeta(AnthropicBeta.COMPACT_2026_09_04)
.addUserMessage("I am building a recipe app. Help me name the main entities in the data model.")
.addAssistantMessage("Start with Recipe, Ingredient, and Step. Add a RecipeIngredient entry that holds the quantity and unit for each ingredient in a recipe.")
.addUserMessage("Good. Now suggest field names for Recipe.")
.compaction(BetaCompactionConfig.builder().build()) // type defaults to "summarize"
.build();
var response = client.beta().messages().create(params);
response.stopReason().ifPresent(reason -> IO.println("Stop reason: " + reason));
}use Anthropic\Beta\AnthropicBeta;
use Anthropic\Beta\Messages\BetaCompactionConfig;
use Anthropic\Beta\Messages\BetaMessageParam;
use Anthropic\Beta\Messages\BetaMessageParam\Role;
$client = new Client();
$history = [
BetaMessageParam::with(
role: Role::USER,
content: 'I am building a recipe app. Help me name the main entities in the data model.',
),
BetaMessageParam::with(
role: Role::ASSISTANT,
content: 'Start with Recipe, Ingredient, and Step. Add a RecipeIngredient entry that holds the quantity and unit for each ingredient in a recipe.',
),
BetaMessageParam::with(role: Role::USER, content: 'Good. Now suggest field names for Recipe.'),
];
$response = $client->beta->messages->create(
model: Model::CLAUDE_OPUS_5,
// max_tokens caps the whole call, including any thinking, so allow several thousand tokens.
maxTokens: 4096,
betas: [AnthropicBeta::COMPACT_2026_09_04],
messages: $history,
compaction: BetaCompactionConfig::with(), // type defaults to 'summarize'
);
echo "Stop reason: {$response->stopReason}", PHP_EOL;client = Anthropic::Client.new
history = [
{
role: "user",
content: "I am building a recipe app. Help me name the main entities in the data model."
},
{
role: "assistant",
content: "Start with Recipe, Ingredient, and Step. Add a RecipeIngredient entry that holds the quantity and unit for each ingredient in a recipe."
},
{ role: "user", content: "Good. Now suggest field names for Recipe." }
]
response = client.beta.messages.create(
model: Anthropic::Model::CLAUDE_OPUS_5,
# max_tokens caps the whole call, including any thinking, so allow several thousand tokens.
max_tokens: 4096,
betas: [Anthropic::AnthropicBeta::COMPACT_2026_09_04],
messages: history,
compaction: { type: "summarize" }
)
puts "Stop reason: #{response.stop_reason}"{
"id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
"type": "message",
"role": "assistant",
"model": "claude-opus-5",
"content": [
{
"type": "compaction",
"content": "Summary of the conversation: the user is designing the data model for a recipe app. The entities agreed so far are Recipe, Ingredient, Step, and RecipeIngredient, which holds the quantity and unit. The user then asked for field names for Recipe.",
"signature": "EuYBCkQY..."
}
],
"stop_reason": "compaction",
"usage": {
"input_tokens": 0,
"output_tokens": 0,
"iterations": [{ "type": "compaction", "input_tokens": 144, "output_tokens": 276 }]
}
}The summarization call uses the request's model, system, tools, thinking settings, and max_tokens. The summarizer reads the tool definitions but never runs a tool, and the response carries no thinking. max_tokens caps the whole call, including any thinking the model does before it writes the summary, so allow several thousand tokens. It is billed and rate-limited like any other request, and usage.iterations reports it as the compaction entry. The top-level input_tokens and output_tokens are zero because no reply was generated.
If the last assistant turn ends in a tool call with no result yet, the API rejects the request. Send that turn's tool results first. Also leave out stop_sequences, structured-output output_config.format, and a tool_choice of type any or tool. They would do nothing on a summarization call, and the API rejects them. The conversation must still fit the model's context window, so compact before you outgrow it, not after.
When you stream the response, the block arrives whole. You get one content_block_start event carrying the complete block, then content_block_stop, with no content_block_delta events. ping events can arrive before or between them.
Continue from the summary
In your history, replace the messages you sent with the returned assistant message. Keep the compaction block exactly as the API returned it, including its signature. Send it first on every later request, with the beta header:
{
"model": "claude-opus-5",
"max_tokens": 2048,
"messages": [
{
"role": "assistant",
"content": [
{
"type": "compaction",
"content": "Summary of the conversation: the user is designing the data model for a recipe app. The entities agreed so far are Recipe, Ingredient, Step, and RecipeIngredient, which holds the quantity and unit. The user then asked for field names for Recipe.",
"signature": "EuYBCkQY..."
}
]
},
{
"role": "assistant",
"content": "For Recipe, use title, description, servings, prep_minutes, and cook_minutes. Add created_at and updated_at timestamps."
},
{ "role": "user", "content": "Now do the same for Ingredient." }
]
}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.
The API puts the summary where the block stands and passes every later message to Claude unchanged. Follow these rules:
- Put the block first in
messages, either as anassistantmessage of its own or as the first content block of the first message, whether that is auserorassistantmessage. - Remove the summarized messages. If any remain in front of the block, the request returns a 400 error (
compaction_block_misplaced). If any remain after it, the API doesn't reject the request for that reason and sends them to the model again. - Send exactly one
compactionblock per request, on every later request. A request without the block reaches Claude without the summary.
To keep a tail of recent turns word for word, leave those turns out of the compaction request. The API summarizes every message it is sent, so send only the older turns, then put the block in front of the turns you kept.
If the conversation took more turns while a background summary request ran, drop exactly the messages you sent in the compaction request from the front of your history. Put the returned message in their place, and keep everything appended since:
# sent_count = len(messages sent in the compaction request)
# response = that request's result, arriving while the agent kept working
if response.stop_reason == "compaction":
compaction_message = {"role": "assistant", "content": response.content}
history = [compaction_message] + history[sent_count:]
# Otherwise keep the full history and try again later (see "When no summary comes back").Don't edit your history between sending the compaction request and making the swap, and make the swap on the first request after the block arrives. That way, thinking produced while the summary was being written stays valid.
On models with preserved thinking, the thinking blocks in the kept turns stay valid as long as both of these conditions hold:
- The kept turns directly followed the summarized messages.
- The
systemparameter and thetoolsnot markeddefer_loading: trueare unchanged from the compaction request.
The first condition also rules out a first kept message that the API would merge into the last summarized message: one with the same role as the last summarized message, or a role: "system" message. The simplest way to meet it is to compact exactly the messages of a request you already made. To change system or tools without invalidating any kept thinking, compact the whole conversation first, so no turns are kept. Then change them on the next request.
A later request can use a different model, system, or tools than the compaction request, and the API still accepts the block. Such a change can invalidate the thinking in the kept turns, but it has no other effect.
To compact a conversation that already starts with a block, send compaction again. The new block summarizes the old summary and everything after it. From then on, send only the newest block.
Write your own summarization prompt
Without instructions, the API uses its own summarization prompt. A non-blank instructions string (up to 16,384 characters) replaces that prompt entirely, as it does for threshold compaction (see Custom summarization instructions). For example:
{
"compaction": {
"type": "summarize",
"instructions": "Summarize this recipe app design conversation. Preserve every entity and field name agreed so far, and the user's latest open request. Do not call tools; respond with the summary text only."
}
}The summarizer reads the whole conversation, earlier thinking included, with or without instructions. That differs from threshold compaction on Claude Fable 5.1 and Claude Mythos 5.1, where custom instructions leave earlier thinking out. In your instructions, say what the summary must retain and tell the model not to call tools. The summarization call runs under the same safeguards as any other request.
When no summary comes back
A summary is produced only when the summarization call ends normally with text and no tool call. Otherwise, the response is still a 200 with empty content. The call is still billed and reported in usage.iterations, with zero usage when no call could be made. The stop_reason is the one the summarization call ended with:
"max_tokens": the summary was cut off."model_context_window_exceeded": there was no room for the summarization prompt."refusal": the request was declined. It is subject to the same safeguards as your other requests, andstop_detailsidentifies the policy category behind it."tool_use": the model called a tool instead of writing the summary."end_turn": the call returned no text.
Resend with a larger max_tokens after "max_tokens", with shorter instructions or fewer messages after "model_context_window_exceeded", or with instructions that tell the model not to call tools after "tool_use". You can also continue without a summary.
A transient server problem while producing a block, or while reading one you sent back, returns a retryable 529 overloaded_error with error.details.error_code set to compaction_unavailable. Retry the request. Other rejections specific to this beta are 400 errors, and most have a message that says what to remove or resend. The exception is a request that leaves out the beta header: it fails with a generic validation error, such as compaction: Extra inputs are not permitted, that doesn't mention the header. Some also carry an error.details.error_code that starts with compaction_, mostly the errors about the block itself: an altered, misplaced, or duplicated block, or a request with nothing left to summarize. Parameter errors, such as a field that can't be combined with compaction, carry the message only.
How it fits with the rest of the API
- Threshold compaction and context editing. You can't send
compactionandcontext_managementon the same request. Threshold compaction (compact_20260112) can't run on a request that carries a signed block. - Prompt caching.
cache_controlon the block places a breakpoint after the summary. - Mid-conversation system messages and tool changes.
role: "system"messages inside the summarized range are summarized. What they declared stops applying once the block replaces them. If an instruction or a tool change still matters, state it again in arole: "system"message. Send that message right after your next newuserturn, which comes after the kept turns, and leave it in your history from then on. Don't put it between the block and the kept turns, because that breaks the kept turns' thinking. - Task budgets. Don't send the
remainingvalue of a task budget (output_config.task_budget.remaining) withcompactionor on requests that carry the block. Doing so returns a 400 error. - Token counting. The token counting endpoint ignores the
compactionparameter. - Content the summary can't carry. Images, documents,
container_uploadblocks, and fetched URLs inside the summarized messages are gone once the block replaces them. Restate or re-upload anything a later turn still needs.