One read of Claude Developer Platformapi-20261111T173709Z
134 pages moved out of 901 read.
Pages moved
134
significant first
Pages read
901
in this capture
Captured
17:37 UTC
Corpus hash
1ddc0440424a
corpus-hash
What this read moved
26-50 of 134, page 2 of 6This capture is too large to show at once. Changes 26-50 of 134 are below, significant first; the rest are on the following screens.
build-with-claude/batch-processing Changed · +3 / -3 lines
from line 70
7070* Batch results are available for 29 days after creation. After that, you can still view the Batch, but its results will no longer be available for download.
7171* Batches are scoped to a [Workspace](https://platform.claude.com/settings/workspaces) in the Claude Console. You may view all batches (and their results) that were created within the Workspace your request runs in.
7272* Rate limits apply to both Batches API HTTP requests and the number of requests within a batch waiting to be processed. See [Message Batches API rate limits](https://platform.claude.com/docs/en/api/rate-limits#message-batches-api). Additionally, processing might be slowed down based on current demand and your request volume. In that case, you might see more requests expiring after 24 hours.
73* Because of high throughput and concurrent processing, batches may go slightly over the [spend limit](https://platform.claude.com/settings/billing) configured in the Claude Console for your Workspace.
73* Because of high throughput and concurrent processing, batches might go slightly over the [spend limit](https://platform.claude.com/docs/en/manage-claude/workspaces#setting-workspace-limits) configured in the Claude Console for your Workspace.
7474* Each batched request must have [`max_tokens`](https://platform.claude.com/docs/en/api/messages/create#create.max_tokens) of at least `1`. `max_tokens: 0` ([cache pre-warming](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pre-warming-the-cache)) is not supported inside a batch, because an ephemeral cache entry written during batch processing would likely expire before the follow-up request runs.
7575
7676### Supported models
from line 746
746746<CodeGroup>
747747 ```bash cURL
748748 # Streams the batch's .jsonl results, one result on each line.
749 # For per-result handling (retries, validation errors), use the Claude SDK.
749 # For per-result handling (retries, validation errors), use the Anthropic SDK.
750750 curl "https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d/results" \
751751 -H "anthropic-version: 2026-10-21" \
752752 -H "x-api-key: $ANTHROPIC_API_KEY"
from line 754
754754
755755 ```bash CLI
756756 # Prints one result on each line, for example `{"custom_id":"test-1","result":{"type":"succeeded",…}}`.
757 # For per-result handling (retries, validation errors), use the Claude SDK
757 # For per-result handling (retries, validation errors), use the Anthropic SDK
758758 # examples in the other tabs.
759759 ant messages:batches results \
760760 --message-batch-id msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d \
build-with-claude/cache-diagnostics Changed · +252 / -263 lines
The two sides of this change are more than 400 edits apart, too far apart to line up, so this is the differ's own diff of it and the words inside a line are not marked.
from line 33
3333
3434[Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) cuts latency and cost significantly, but only when the beginning of your prompt is byte-for-byte identical to a recent request. A reordered tool, a timestamp interpolated into your system prompt, or an edit to an earlier message can silently invalidate the cache. Without cache diagnostics, the only signal is `usage.cache_read_input_tokens` dropping to zero, with no indication of what changed.
3535
36Cache diagnostics closes that gap. Pass the `id` of your previous response, and the API compares the two requests and tells you where they diverged (the model, the system prompt, the tools, or the message history) so you can fix the root cause instead of guessing.
36Cache diagnostics closes that gap. Pass the `id` of your previous response, and the API compares the two requests. It tells you where they diverged (the model, the system prompt, the tools, or the message history), so you can fix the root cause instead of guessing.
3737
3838## How cache diagnostics works
3939
from line 45
4545
4646## Basic usage
4747
48Include the `diagnostics` object on every turn. The object is the opt-in: the API stores a fingerprint only for requests that include it. On the first turn, pass `"previous_message_id": null` to opt in without a prior message to compare against. On subsequent turns, pass the `id` from the previous response. The `cache-diagnosis-2026-04-07` beta header is no longer required, and requests that send it work as before.
48Include the `diagnostics` object on every turn. The object is the opt-in: the API stores a fingerprint only for requests that include it. On the first turn, pass `"previous_message_id": null` to opt in without a prior message to compare against. On subsequent turns, pass the `id` from the previous response.
4949
5050<CodeGroup>
5151 ```bash cURL
from line 372
372372 SYSTEM = "You are an AI assistant analyzing a large document. <document>...</document>"
373373
374374 r1 = client.beta.messages.create(
375 model: :"claude-opus-5-5",
375 model: Anthropic::Model::CLAUDE_OPUS_5_5,
376376 max_tokens: 1024,
377377 cache_control: {type: "ephemeral"},
378378 system_: SYSTEM,
from line 383
383383 )
384384
385385 r2 = client.beta.messages.create(
386 model: :"claude-opus-5-5",
386 model: Anthropic::Model::CLAUDE_OPUS_5_5,
387387 max_tokens: 1024,
388388 cache_control: {type: "ephemeral"},
389389 system_: SYSTEM,
from line 676
676676 ```ruby Ruby
677677 # Turn 2: stream, referencing the previous response id
678678 stream = client.beta.messages.stream(
679 model: :"claude-opus-5-5",
679 model: Anthropic::Model::CLAUDE_OPUS_5_5,
680680 max_tokens: 1024,
681681 cache_control: {type: "ephemeral"},
682682 system_: SYSTEM,
from line 713
713713
714714In a multi-turn conversation, carry the latest response `id` forward as `previous_message_id` on every turn. The first iteration passes `null` to opt in; each subsequent iteration passes the `id` from the previous response.
715715
716<Tabs>
717 <Tab title="cURL">
718 <Info>
719 This workflow doesn’t translate well to a one-off shell command. Use the Claude SDK to run the loop; the per-turn HTTP request is identical to [Basic usage](https://platform.claude.com/docs/en/build-with-claude/cache-diagnostics#basic-usage).
720 </Info>
721 </Tab>
722
723 <Tab title="CLI">
724 <Info>
725 This workflow doesn’t translate well to a one-off shell command. Use the Claude SDK to run the loop; the per-turn CLI command is identical to [Basic usage](https://platform.claude.com/docs/en/build-with-claude/cache-diagnostics#basic-usage).
726 </Info>
727 </Tab>
728
729 <Tab title="Python">
730 ```python
731 client = anthropic.Anthropic()
732
733 SYSTEM = "You are an AI assistant analyzing a large document. <document>...</document>"
734
735 messages = []
736 prev_id = None
737
738 for i, user_message in enumerate(
739 ["Summarize section 1.", "Now section 2.", "Now section 3."]
740 ):
741 messages.append({"role": "user", "content": user_message})
742
743 r = client.beta.messages.create(
744 model="claude-opus-5-5",
745 max_tokens=1024,
746 cache_control={"type": "ephemeral"},
747 system=SYSTEM,
748 messages=messages,
749 diagnostics={"previous_message_id": prev_id},
750 )
751
752 if r.diagnostics is not None and r.diagnostics.cache_miss_reason is not None:
753 print(f"Turn {i + 1} cache_miss_reason: {r.diagnostics.cache_miss_reason.type}")
754
755 messages.append({"role": "assistant", "content": r.content})
756 prev_id = r.id
757 ```
758 </Tab>
759
760 <Tab title="TypeScript">
761 ```typescript
762 const client = new Anthropic();
763
764 const SYSTEM = "You are an AI assistant analyzing a large document. <document>...</document>";
765
766 const prompts = ["Summarize section 1.", "Now section 2.", "Now section 3."];
767
768 const messages: BetaMessageParam[] = [];
769 let prevId: string | null = null;
770
771 for (const [i, prompt] of prompts.entries()) {
772 messages.push({ role: "user", content: prompt });
773
774 const r: BetaMessage = await client.beta.messages.create({
775 model: "claude-opus-5-5",
776 max_tokens: 1024,
777 cache_control: { type: "ephemeral" },
778 system: SYSTEM,
779 messages,
780 diagnostics: { previous_message_id: prevId }
781 });
782
783 if (r.diagnostics?.cache_miss_reason) {
784 console.log(`Turn ${i + 1} cache_miss_reason: ${r.diagnostics.cache_miss_reason.type}`);
716<CodeGroup exclude="shell:cURL, shell:CLI">
717 <CodeGroupItem language="cURL">
718 This workflow needs more logic than a single shell command. Use the Anthropic SDK to run the loop. Each turn sends the same HTTP request as in [Basic usage](https://platform.claude.com/docs/en/build-with-claude/cache-diagnostics#basic-usage).
719 </CodeGroupItem>
720
721 <CodeGroupItem language="CLI">
722 This workflow needs more logic than a single shell command. Use the Anthropic SDK to run the loop. Each turn sends the same request as in [Basic usage](https://platform.claude.com/docs/en/build-with-claude/cache-diagnostics#basic-usage).
723 </CodeGroupItem>
724
725 ```python Python
726 client = anthropic.Anthropic()
727
728 SYSTEM = "You are an AI assistant analyzing a large document. <document>...</document>"
729
730 messages = []
731 prev_id = None
732
733 for turn, user_message in enumerate(
734 ["Summarize section 1.", "Now section 2.", "Now section 3."]
735 ):
736 messages.append({"role": "user", "content": user_message})
737
738 response = client.beta.messages.create(
739 model="claude-opus-5-5",
740 max_tokens=1024,
741 cache_control={"type": "ephemeral"},
742 system=SYSTEM,
743 messages=messages,
744 diagnostics={"previous_message_id": prev_id},
745 )
746
747 if (
748 response.diagnostics is not None
749 and response.diagnostics.cache_miss_reason is not None
750 ):
751 print(
752 f"Turn {turn + 1} cache_miss_reason: {response.diagnostics.cache_miss_reason.type}"
753 )
754
755 messages.append({"role": "assistant", "content": response.content})
756 prev_id = response.id
757 ```
758
759 ```typescript TypeScript
760 const client = new Anthropic();
761
762 const SYSTEM = "You are an AI assistant analyzing a large document. <document>...</document>";
763
764 const prompts = ["Summarize section 1.", "Now section 2.", "Now section 3."];
765
766 const messages: BetaMessageParam[] = [];
767 let prevId: string | null = null;
768
769 for (const [turn, prompt] of prompts.entries()) {
770 messages.push({ role: "user", content: prompt });
771
772 const response: BetaMessage = await client.beta.messages.create({
773 model: "claude-opus-5-5",
774 max_tokens: 1024,
775 cache_control: { type: "ephemeral" },
776 system: SYSTEM,
777 messages,
778 diagnostics: { previous_message_id: prevId }
779 });
780
781 if (response.diagnostics?.cache_miss_reason) {
782 console.log(
783 `Turn ${turn + 1} cache_miss_reason: ${response.diagnostics.cache_miss_reason.type}`
784 );
785 }
786
787 messages.push({ role: "assistant", content: response.content });
788 prevId = response.id;
789 }
790 ```
791
792 ```csharp C#
793 AnthropicClient client = new();
794
795 var system = "You are an AI assistant analyzing a large document. <document>...</document>";
796
797 List<BetaMessageParam> messages = [];
798 string? prevId = null;
799 string[] prompts = ["Summarize section 1.", "Now section 2.", "Now section 3."];
800
801 for (int turn = 0; turn < prompts.Length; turn++)
802 {
803 messages.Add(new BetaUserMessageParam { Content = prompts[turn] });
804
805 var response = await client.Beta.Messages.Create(
806 new()
807 {
808 Model = Messages::Model.ClaudeOpus5_5,
809 MaxTokens = 1024,
810 CacheControl = new(),
811 System = system,
812 Messages = messages,
813 Diagnostics = new() { PreviousMessageID = prevId },
814 }
815 );
816
817 if (response.Diagnostics?.CacheMissReason is { Type: var type })
818 {
819 Console.WriteLine($"Turn {turn + 1} cache_miss_reason: {type.Raw()}");
785820 }
786821
787 messages.push({ role: "assistant", content: r.content });
788 prevId = r.id;
789 }
790 ```
791 </Tab>
792
793 <Tab title="C#">
794 ```csharp
795 AnthropicClient client = new();
796
797 var system = "You are an AI assistant analyzing a large document. <document>...</document>";
798
799 List<BetaMessageParam> messages = [];
800 string? prevId = null;
801 string[] prompts = ["Summarize section 1.", "Now section 2.", "Now section 3."];
802
803 for (int i = 0; i < prompts.Length; i++)
804 {
805 messages.Add(new BetaUserMessageParam { Content = prompts[i] });
806
807 var r = await client.Beta.Messages.Create(
808 new()
809 {
810 Model = Messages::Model.ClaudeOpus5_5,
811 MaxTokens = 1024,
812 CacheControl = new(),
813 System = system,
814 Messages = messages,
815 Diagnostics = new() { PreviousMessageID = prevId },
816 }
817 );
818
819 if (r.Diagnostics?.CacheMissReason is { Type: var type })
820 {
821 Console.WriteLine($"Turn {i + 1} cache_miss_reason: {type.Raw()}");
822 }
823
824 messages.Add(
825 new BetaAssistantMessageParam
826 {
827 Content = r.Content.Select(block => new BetaContentBlockParam(block.Json)).ToList(),
828 }
829 );
830 prevId = r.ID;
831 }
832 ```
833 </Tab>
834
835 <Tab title="Go">
836 ```go
837 client := anthropic.NewClient()
838 ctx := context.Background()
839
840 system := []anthropic.BetaTextBlockParam{
841 {Text: "You are an AI assistant analyzing a large document. <document>...</document>"},
842 }
843
844 prompts := []string{"Summarize section 1.", "Now section 2.", "Now section 3."}
845
846 var messages []anthropic.BetaMessageParam
847 prevID := param.Null[string]()
848
849 for turn, prompt := range prompts {
850 messages = append(messages, anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock(prompt)))
851
852 r, err := client.Beta.Messages.New(ctx, anthropic.BetaMessageNewParams{
853 Model: anthropic.ModelClaudeOpus5_5,
854 MaxTokens: 1024,
855 CacheControl: anthropic.BetaCacheControlEphemeralParam{},
856 System: system,
857 Messages: messages,
858 Diagnostics: anthropic.BetaDiagnosticsParam{
859 PreviousMessageID: prevID,
860 },
861 })
862 if err != nil {
863 panic(err)
864 }
865
866 if r.JSON.Diagnostics.Valid() && r.Diagnostics.JSON.CacheMissReason.Valid() {
867 fmt.Printf("Turn %d cache_miss_reason: %s\n", turn+1, r.Diagnostics.CacheMissReason.Type)
868 }
869
870 messages = append(messages, r.ToParam())
871 prevID = anthropic.String(r.ID)
872 }
873 ```
874 </Tab>
875
876 <Tab title="Java">
877 ```java
878 var client = AnthropicOkHttpClient.fromEnv();
879
880 var system = "You are an AI assistant analyzing a large document. <document>...</document>";
881 var prompts = List.of("Summarize section 1.", "Now section 2.", "Now section 3.");
882
883 var messages = new ArrayList<BetaMessageParam>();
884 String prevId = null;
885
886 for (var turn = 0; turn < prompts.size(); turn++) {
887 messages.add(BetaMessageParam.ofUser(prompts.get(turn)));
888
889 var r = client.beta().messages().create(
890 MessageCreateParams.builder()
891 .model(Model.CLAUDE_OPUS_5_5)
892 .maxTokens(1024)
893 .cacheControl(BetaCacheControlEphemeral.builder().build())
894 .system(system)
895 .messages(messages)
896 .diagnostics(BetaDiagnosticsParam.builder().previousMessageId(prevId).build())
897 .build()
898 );
899
900 if (r.diagnostics().isPresent() && r.diagnostics().get().cacheMissReason().isPresent()) {
901 var reason = r.diagnostics().get().cacheMissReason().get();
902 IO.println("Turn " + (turn + 1) + " cache_miss_reason: " + reason.type().asString());
903 }
904
905 messages.add(r.toParam());
906 prevId = r.id();
907 }
908 ```
909 </Tab>
910
911 <Tab title="PHP">
912 ```php
913 $client = new Client();
914
915 $system = 'You are an AI assistant analyzing a large document. <document>...</document>';
916
917 $messages = [];
918 $prevId = null;
919
920 foreach (['Summarize section 1.', 'Now section 2.', 'Now section 3.'] as $i => $userMsg) {
921 $turn = $i + 1;
922 $messages[] = ['role' => 'user', 'content' => $userMsg];
923
924 $r = $client->beta->messages->create(
925 model: Model::CLAUDE_OPUS_5_5,
926 maxTokens: 1024,
927 cacheControl: new BetaCacheControlEphemeral,
928 system: $system,
929 messages: $messages,
930 diagnostics: (new BetaDiagnosticsParam)->withPreviousMessageID($prevId),
931 );
932
933 if ($r->diagnostics?->cacheMissReason !== null) {
934 echo "Turn {$turn} cache_miss_reason: {$r->diagnostics->cacheMissReason->type}\n";
935 }
936
937 $messages[] = ['role' => 'assistant', 'content' => $r->content];
938 $prevId = $r->id;
939 }
940 ```
941 </Tab>
942
943 <Tab title="Ruby">
944 ```ruby
945 client = Anthropic::Client.new
946
947 SYSTEM = "You are an AI assistant analyzing a large document. <document>...</document>"
948
949 messages = []
950 prev_id = nil
951
952 ["Summarize section 1.", "Now section 2.", "Now section 3."].each_with_index do |user_msg, i|
953 messages << {role: "user", content: user_msg}
954
955 r = client.beta.messages.create(
956 model: :"claude-opus-5-5",
957 max_tokens: 1024,
958 cache_control: {type: "ephemeral"},
959 system_: SYSTEM,
960 messages: messages,
961 diagnostics: {previous_message_id: prev_id}
962 )
963
964 if (reason = r.diagnostics&.cache_miss_reason)
965 puts "Turn #{i + 1} cache_miss_reason: #{reason.type}"
966 end
967
968 messages << {role: "assistant", content: r.content}
969 prev_id = r.id
822 messages.Add(
823 new BetaAssistantMessageParam
824 {
825 Content = response.Content.Select(block => new BetaContentBlockParam(block.Json)).ToList(),
826 }
827 );
828 prevId = response.ID;
829 }
830 ```
831
832 ```go Go
833 client := anthropic.NewClient()
834 ctx := context.Background()
835
836 system := []anthropic.BetaTextBlockParam{
837 {Text: "You are an AI assistant analyzing a large document. <document>...</document>"},
838 }
839
840 prompts := []string{"Summarize section 1.", "Now section 2.", "Now section 3."}
841
842 var messages []anthropic.BetaMessageParam
843 prevID := param.Null[string]()
844
845 for turn, prompt := range prompts {
846 messages = append(messages, anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock(prompt)))
847
848 response, err := client.Beta.Messages.New(ctx, anthropic.BetaMessageNewParams{
849 Model: anthropic.ModelClaudeOpus5_5,
850 MaxTokens: 1024,
851 CacheControl: anthropic.BetaCacheControlEphemeralParam{},
852 System: system,
853 Messages: messages,
854 Diagnostics: anthropic.BetaDiagnosticsParam{
855 PreviousMessageID: prevID,
856 },
857 })
858 if err != nil {
859 panic(err)
860 }
861
862 if response.JSON.Diagnostics.Valid() && response.Diagnostics.JSON.CacheMissReason.Valid() {
863 fmt.Printf("Turn %d cache_miss_reason: %s\n", turn+1, response.Diagnostics.CacheMissReason.Type)
864 }
865
866 messages = append(messages, response.ToParam())
867 prevID = anthropic.String(response.ID)
868 }
869 ```
870
871 ```java Java
872 var client = AnthropicOkHttpClient.fromEnv();
873
874 var system = "You are an AI assistant analyzing a large document. <document>...</document>";
875 var prompts = List.of("Summarize section 1.", "Now section 2.", "Now section 3.");
876
877 var messages = new ArrayList<BetaMessageParam>();
878 String prevId = null;
879
880 for (var turn = 0; turn < prompts.size(); turn++) {
881 messages.add(BetaMessageParam.ofUser(prompts.get(turn)));
882
883 var response = client.beta().messages().create(
884 MessageCreateParams.builder()
885 .model(Model.CLAUDE_OPUS_5_5)
886 .maxTokens(1024)
887 .cacheControl(BetaCacheControlEphemeral.builder().build())
888 .system(system)
889 .messages(messages)
890 .diagnostics(BetaDiagnosticsParam.builder().previousMessageId(prevId).build())
891 .build()
892 );
893
894 if (response.diagnostics().isPresent() && response.diagnostics().get().cacheMissReason().isPresent()) {
895 var reason = response.diagnostics().get().cacheMissReason().get();
896 IO.println("Turn " + (turn + 1) + " cache_miss_reason: " + reason.type().asString());
897 }
898
899 messages.add(response.toParam());
900 prevId = response.id();
901 }
902 ```
903
904 ```php PHP
905 $client = new Client();
906
907 $system = 'You are an AI assistant analyzing a large document. <document>...</document>';
908
909 $messages = [];
910 $prevId = null;
911
912 foreach (['Summarize section 1.', 'Now section 2.', 'Now section 3.'] as $index => $userMsg) {
913 $turn = $index + 1;
914 $messages[] = ['role' => 'user', 'content' => $userMsg];
915
916 $response = $client->beta->messages->create(
917 model: Model::CLAUDE_OPUS_5_5,
918 maxTokens: 1024,
919 cacheControl: new BetaCacheControlEphemeral,
920 system: $system,
921 messages: $messages,
922 diagnostics: (new BetaDiagnosticsParam)->withPreviousMessageID($prevId),
923 );
924
925 if ($response->diagnostics?->cacheMissReason !== null) {
926 echo "Turn {$turn} cache_miss_reason: {$response->diagnostics->cacheMissReason->type}\n";
927 }
928
929 $messages[] = ['role' => 'assistant', 'content' => $response->content];
930 $prevId = $response->id;
931 }
932 ```
933
934 ```ruby Ruby
935 client = Anthropic::Client.new
936
937 SYSTEM = "You are an AI assistant analyzing a large document. <document>...</document>"
938
939 messages = []
940 prev_id = nil
941
942 ["Summarize section 1.", "Now section 2.", "Now section 3."].each_with_index do |user_msg, turn|
943 messages << {role: "user", content: user_msg}
944
945 response = client.beta.messages.create(
946 model: Anthropic::Model::CLAUDE_OPUS_5_5,
947 max_tokens: 1024,
948 cache_control: {type: "ephemeral"},
949 system_: SYSTEM,
950 messages: messages,
951 diagnostics: {previous_message_id: prev_id}
952 )
953
954 if (reason = response.diagnostics&.cache_miss_reason)
955 puts "Turn #{turn + 1} cache_miss_reason: #{reason.type}"
970956 end
971 ```
972 </Tab>
973</Tabs>
957
958 messages << {role: "assistant", content: response.content}
959 prev_id = response.id
960 end
961 ```
962</CodeGroup>
974963
975964## Response format
976965
from line 1001
10121001| Type | What it means | What to change |
10131002| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
10141003| `model_changed` | The `model` differs from the previous request (for example, a router, A/B test, or fallback selected a different model). The cache is per-model. | Hold the model constant within a cached conversation. |
1015| `system_changed` | The `system` parameter differs. Typically a timestamp, request ID, or other per-request value was interpolated into the system prompt. | Make the system prompt a byte-stable constant and move dynamic data into the first `user` message after your cache breakpoint. |
1004| `system_changed` | The `system` parameter differs. Typically a timestamp, request ID, or other per-request value was interpolated into the system prompt. | Make the system prompt a byte-stable constant and put the changing value in the `user` message you’re about to send. |
10161005| `tools_changed` | The `tools` array differs: tools were added, removed, or reordered between turns, or tool `input_schema` JSON was serialized non-deterministically. | Send the same tool list on every turn in a fixed order with deterministically serialized schemas (for example, sort keys). |
10171006| `messages_changed` | The model, system, and tools all match, but an earlier entry in `messages` was altered, reordered, or removed rather than appended to. Typically conversation history was truncated or edited, or assistant turns and `tool_result` blocks were re-serialized differently on resend. | Treat the history as append-only; echo assistant `content` and tool results back verbatim. |
10181007| `previous_message_not_found` | No stored fingerprint exists for the supplied `previous_message_id`. This is not evidence that your request changed. Typically the previous request did not include the `diagnostics` object, it came from a different workspace, or too much time has passed since it was sent. | Include the `diagnostics` object on every turn and keep consecutive turns close together in time. |
from line 1013
10241013
10251014## Reading diagnostics alongside usage
10261015
1027`diagnostics` answers “did my request change?” whereas `usage.cache_read_input_tokens` answers “did the cache hit?” Combining them tells you where to look.
1016`diagnostics` tells you whether your request changed, and `usage.cache_read_input_tokens` tells you whether the cache hit. Combining them tells you where to look.
10281017
10291018This matrix applies to turns where you passed a real `previous_message_id`. On the first turn (`previous_message_id: null`), `diagnostics` is always `null` and `cache_read_input_tokens` is normally zero because the cache is being written, not read; no troubleshooting is needed. The matrix also does not apply when `cache_miss_reason` is `null` (the comparison is still pending; check the next turn) or when its `type` is `previous_message_not_found` or `unavailable` (no comparison was produced).
10301019
from line 1026
10371026
10381027## Limitations
10391028
1040* **Claude API only:** Not available on Claude Models on Google Cloud (Google managed) or Amazon Bedrock.
1029* **Claude API only:** Cache diagnostics is available on the Claude API.
10411030* **Limited retention:** Fingerprints for `previous_message_id` lookup expire after a short period. Run diagnostic comparisons between closely spaced requests.
10421031* **Same workspace:** The previous request must have run in the same organization and workspace. To check, compare the `anthropic-workspace-id` [response header](https://platform.claude.com/docs/en/api/overview#response-headers) on the two responses.
10431032* **Comparison horizon:** For very long conversations where the only change is deep in the message list, the response might be `unavailable` rather than a precise location.
10441033
build-with-claude/citations Changed · +5 / -5 lines
from line 29
2929 - claude-sonnet-4-5-20250929
3030 supportedPlatforms:
3131 Claude API: stable
32 Claude Platform on AWS: stable
3332 Amazon Bedrock: stable
34 Amazon Bedrock (InvokeModel): stable
33 Amazon Bedrock (bedrock-runtime): stable
34 Claude Platform on AWS: stable
3535 Claude Models on Google Cloud (Google managed): stable
3636 Microsoft Foundry: stable
3737---
from line 2374
23742374
23752375* Availability: Available
23762376
2377| Status | Cloud platforms |
2378| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2379| Available | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), [Amazon Bedrock (InvokeModel)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed), [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry) |
2377| Status | Cloud platforms |
2378| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2379| Available | Claude API, [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), [Amazon Bedrock (bedrock-runtime)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy), [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed), [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry) |
23802380
23812381#### [Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview)
23822382
build-with-claude/claude-in-amazon-bedrock Changed · +5 / -7 lines
from line 1
11---
2title: Claude in Amazon Bedrock (Opus 4.7 and later)
2title: Claude in Amazon Bedrock (bedrock-mantle)
33url: https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock
4description: Access Claude models through Amazon Bedrock with AWS-native authentication, billing, and security boundaries.
4description: Call Claude through the Messages API on Amazon Bedrock's bedrock-mantle endpoint, with AWS-native authentication, billing, and security boundaries.
55---
66
77This guide walks you through setting up and making API calls to Claude in Amazon Bedrock. Claude in Amazon Bedrock runs on AWS-managed infrastructure with zero operator access: Anthropic personnel have no access to the inference infrastructure. You can build sensitive applications entirely inside the AWS security boundary, with the same Messages API shape you use with the Claude API.
88
99<Note>
10 This page covers Claude in Amazon Bedrock, which serves Claude through the Messages API at `/anthropic/v1/messages` on AWS-managed infrastructure. The `InvokeModel` and `Converse` APIs with ARN-versioned model identifiers are documented at [Claude on Amazon Bedrock (Opus 4.6 and earlier)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy). For an Anthropic-operated alternative on AWS with AWS Marketplace billing, see [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws).
10 This page covers Claude in Amazon Bedrock, which serves Claude through the Messages API at `/anthropic/v1/messages` on the `bedrock-mantle` endpoint. That endpoint runs on AWS-managed infrastructure. The `InvokeModel` and `Converse` APIs, on the `bedrock-runtime` endpoint, are documented at [Claude on Amazon Bedrock (`bedrock-runtime`)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy). For an Anthropic-operated alternative on AWS with AWS Marketplace billing, see [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws).
1111</Note>
1212
1313## Access
from line 330
330330
331331## Supported models
332332
333Model IDs in Claude in Amazon Bedrock carry an `anthropic.` provider prefix. Model capabilities and behaviors are documented on the [Models overview](https://platform.claude.com/docs/en/models/overview) page.
333Model IDs in Claude in Amazon Bedrock carry an `anthropic.` provider prefix. For model capabilities and behaviors, see [Models overview](https://platform.claude.com/docs/en/models/overview). Claude Fable 5.2 and Claude Mythos 5.2 aren’t available in Claude in Amazon Bedrock. Amazon Bedrock serves them on the `bedrock-runtime` endpoint only. For their model IDs, see [API model IDs](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy#api-model-ids). To see which endpoint serves each model, see [Endpoint availability by models](https://docs.aws.amazon.com/bedrock/latest/userguide/models-endpoint-availability.html) in the AWS documentation.
334334
335335| Model | Model ID | Access |
336336| :------------------------------------------------------------------------------------------ | :---------------------------- | :-------------------------------------------------------------------------------------------------- |
337| Claude Fable 5.2 | `anthropic.claude-fable-5-2` | [See Access](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock#access) |
338| Claude Mythos 5.2 ([limited availability](https://support.claude.com/en/articles/14604842)) | `anthropic.claude-mythos-5-2` | Active (verification required) |
339337| Claude Fable 5.1 | `anthropic.claude-fable-5-1` | Open |
340338| Claude Mythos 5.1 ([limited availability](https://support.claude.com/en/articles/14604842)) | `anthropic.claude-mythos-5-1` | Active (verification required) |
341339| Claude Fable 5 | `anthropic.claude-fable-5` | Open |
from line 384
386384* **Global:** dynamic routing across all available regions for maximum availability. No pricing premium.
387385* **Regional:** the endpoint resolves to the single AWS region you specify, for data-residency requirements. Regional endpoints carry a 10 percent pricing premium over global endpoints. To route across multiple regions within a geography, use an [inference profile](https://docs.aws.amazon.com/bedrock/latest/userguide/cross-region-inference.html) (US, EU, JP, or AU). Regions marked **In-region only** in the table support direct single-region routing without an inference profile.
388386
389The global endpoint is available for Claude Fable 5.2, Claude Fable 5.1, Claude Fable 5, Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Sonnet 5.5, Claude Sonnet 5, Claude Haiku 5.5, and Claude Haiku 4.5.
387The global endpoint is available for Claude Fable 5.1, Claude Fable 5, Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Sonnet 5.5, Claude Sonnet 5, Claude Haiku 5.5, and Claude Haiku 4.5.
390388
391389| AWS region | Location | Endpoint types |
392390| ---------------- | ------------------------- | -------------------------- |
build-with-claude/claude-on-amazon-bedrock-legacy Changed · +10 / -8 lines
from line 1
11---
2title: Claude on Amazon Bedrock (Opus 4.6 and earlier)
2title: Claude on Amazon Bedrock (bedrock-runtime)
33url: https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy
4description: The legacy Amazon Bedrock integration for Claude models, using InvokeModel and Converse APIs with ARN-versioned model identifiers.
4description: Use Claude models on Amazon Bedrock's bedrock-runtime endpoint, through the InvokeModel and Converse APIs.
55---
66
77<Note>
8 This page covers the legacy Amazon Bedrock integration: the `InvokeModel` and `Converse` APIs with ARN-versioned model identifiers and AWS event-stream encoding. For models available on the Messages-API Bedrock endpoint, see [Claude in Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), which uses the Messages API at `/anthropic/v1/messages` with SSE streaming. For an Anthropic-operated alternative with AWS Marketplace billing and typically same-day feature access, see [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws). Existing Bedrock users can follow the [migration guide](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#migrating-from-amazon-bedrock).
8 This page covers Amazon Bedrock’s `bedrock-runtime` endpoint: the `InvokeModel` and `Converse` APIs, with AWS event-stream encoding. For models available on the `bedrock-mantle` endpoint, see [Claude in Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), which uses the Messages API at `/anthropic/v1/messages` with SSE streaming. For an Anthropic-operated alternative with AWS Marketplace billing and typically same-day feature access, see [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws). Existing Bedrock users can follow the [migration guide](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#migrating-from-amazon-bedrock).
99</Note>
1010
1111<Warning>
12 The latest version of the SDK sends API version `2026-10-21` by default, including through Amazon Bedrock. The ARN-versioned models in the model table on this page don’t support `2026-10-21` on Bedrock, and requests to them that send it can return a 400 error. If you call them through the SDK, keep the SDK on the version you use today, and pin that version where you install it so a later install doesn’t upgrade it. The Boto3 example sets `anthropic_version` in its request body and isn’t affected.
12 The latest version of the SDK sends API version `2026-10-21` by default, including through Amazon Bedrock. The models numbered 4.6 or lower in the model table on this page don’t support `2026-10-21` on Bedrock, and requests to them that send it can return a 400 error. If you call them through the SDK, keep the SDK on the version you use today, and pin that version where you install it so a later install doesn’t upgrade it. If you call `InvokeModel` through an AWS SDK such as Boto3, you set `anthropic_version` in the request body yourself. The Anthropic SDK’s new default doesn’t apply to those requests.
1313
1414 To install an SDK for these models, use the commands in [Install an SDK for accessing Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy#install-an-sdk-for-accessing-bedrock), which install the last major version before API version `2026-10-21`.
1515</Warning>
from line 149
149149#### API model IDs
150150
151151<Note>
152 Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Fable 5, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Sonnet 5, Claude Haiku 5.5, Claude Opus 4.8, and Claude Opus 4.7 are reachable through `InvokeModel` on `bedrock-runtime`. These requests are served by the same infrastructure as the [Claude in Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock) endpoint. For the native Messages API request shape and full feature parity, use that page. These models are omitted from the model table on this page because they do not have ARN-versioned model IDs.
152 Claude Fable 5.1, Claude Fable 5, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Sonnet 5, Claude Haiku 5.5, Claude Opus 4.8, and Claude Opus 4.7 are reachable through `InvokeModel` on `bedrock-runtime`. These requests are served by the same infrastructure as the [Claude in Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock) endpoint. For the native Messages API request shape and full feature parity, use that page. These models are omitted from the model table on this page. The table does list Claude Fable 5.2 and Claude Mythos 5.2, because `bedrock-runtime` is the only Amazon Bedrock endpoint that serves them.
153153</Note>
154154
155155Lifecycle terms (Deprecated, Retired) are defined in [Model deprecations](https://platform.claude.com/docs/en/about-claude/model-deprecations). Lifecycle dates on partner-operated platforms are set by the partner and can differ from the Claude API schedule. For the current retirement date of any model on Amazon Bedrock, see [Amazon Bedrock’s model lifecycle page](https://docs.aws.amazon.com/bedrock/latest/userguide/model-lifecycle.html).
from line 164
164164
165165| Model | Base Bedrock model ID | `global` | `us` | `eu` | `jp` | `apac` |
166166| :---------------------------------------------------------------------------------------------------- | :------------------------------------------ | :------- | :--- | :--- | :--- | :----- |
167| Claude Fable 5.2 | `anthropic.claude-fable-5-2` | Yes | Yes | No | No | No |
168| Claude Mythos 5.2 ([limited availability](https://support.claude.com/en/articles/14604842)) | `anthropic.claude-mythos-5-2` | Yes | Yes | No | No | No |
167169| Claude Opus 4.6 | `anthropic.claude-opus-4-6-v1` | Yes | Yes | Yes | Yes | Yes |
168170| Claude Opus 4.5 | `anthropic.claude-opus-4-5-20251101-v1:0` | Yes | Yes | Yes | No | No |
169171| Claude Opus 4.1 ([deprecated](https://platform.claude.com/docs/en/about-claude/model-deprecations)) | `anthropic.claude-opus-4-1-20250805-v1:0` | No | Yes | No | No | No |
from line 787
785787
786788### Mid-conversation system messages on Bedrock
787789
788[Mid-conversation system messages](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages) are available through the InvokeModel API for Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Fable 5, Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Sonnet 5.5, and Claude Haiku 5.5. As described in the note under [API model IDs](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy#api-model-ids), these requests are served by the same infrastructure as the [Claude in Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock) endpoint. No beta header is required for mid-conversation system messages. This feature is not available on Claude Sonnet 5. Use the top-level `system` field instead. It is not available for the ARN-versioned models in the model table on this page.
790[Mid-conversation system messages](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages) are available through the InvokeModel API for Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Fable 5, Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Sonnet 5.5, and Claude Haiku 5.5. This feature is not available on Claude Sonnet 5. Use the top-level `system` field instead. It is not available for the other models in the model table on this page.
789791
790A `role: "system"` message can also set `output_config.effort` to [change effort mid-conversation](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta) on Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, and Claude Opus 5.5. This is in beta: add `mid-conversation-output-config-2026-07-01` to the `anthropic_beta` array in the request body. Without that value, or on Claude Fable 5, Claude Opus 5, or Claude Opus 4.8, the request returns a 400 error: `messages.N.output_config: Extra inputs are not permitted`. In the error, `N` is the index of the `system` message in `messages`.
792A `role: "system"` message can also set `output_config.effort` to [change effort mid-conversation](https://platform.claude.com/docs/en/build-with-claude/effort-per-message) on Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, and Claude Opus 5.5. This is in beta: add `mid-conversation-output-config-2026-07-01` to the `anthropic_beta` array in the request body. Without that value, or on Claude Fable 5, Claude Opus 5, or Claude Opus 4.8, the request returns a 400 error: `messages.N.output_config: Extra inputs are not permitted`. In the error, `N` is the index of the `system` message in `messages`.
791793
792794**For Converse API users:** the Converse API accepts system instructions through its top-level [`system` parameter](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html). To add system instructions mid-conversation, use the InvokeModel API.
793795
build-with-claude/claude-platform-on-aws Changed · +25 / -25 lines
from line 22
2222
2323Both offerings let you use Claude through AWS, but they differ in architecture, API surface, and feature availability.
2424
25| Aspect | Claude Platform on AWS | [Claude in Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock) | [Amazon Bedrock (Opus 4.6 and earlier)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy) |
26| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
27| **Who operates the stack** | Anthropic | AWS | AWS |
28| **API surface** | Claude API (`/v1/{endpoint}`) | Messages API at `/anthropic/v1/messages` | Bedrock Converse / InvokeModel |
29| **Feature availability** | Typically same-day as Claude API (see [feature limitations](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#features-not-supported)) | Follows the Amazon Bedrock release schedule | Follows the Amazon Bedrock release schedule |
30| **Beta features** | Pass through with `anthropic-beta` headers (see [feature limitations](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#features-not-supported)) | The beta features Amazon Bedrock supports, through the `anthropic-beta` header | The beta features Amazon Bedrock supports, through the `anthropic_beta` field of the InvokeModel request body |
31| **Authentication** | AWS IAM / SigV4 or API key | AWS IAM / SigV4 | AWS IAM / SigV4 or bearer token |
32| **Billing** | AWS Marketplace | AWS (native service) | AWS (native service) |
33| **Base URL** | `aws-external-anthropic.{region}.api.aws` | `bedrock-mantle.{region}.api.aws` | `bedrock-runtime.{region}.amazonaws.com` |
34| **SDK client** | `AnthropicAWS` (typescript: `AnthropicAws`; csharp: `AnthropicAwsClient`; go: `anthropicaws.NewClient()`; java: `AwsBackend`; php: `Anthropic\Aws\Client`; ruby: `Anthropic::AWSClient`), in beta | `AnthropicBedrockMantle` | `AnthropicBedrock` / Bedrock SDK |
35| **Console** | Claude Console (`platform.claude.com`, access through the AWS Console) | Bedrock Console | Bedrock Console |
36| **Rate limits and quotas** | Managed by Anthropic | Managed by AWS | Managed by AWS |
37| **Inference data processor** | Anthropic | AWS | AWS |
25| Aspect | Claude Platform on AWS | [Amazon Bedrock (`bedrock-mantle`)](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock) | [Amazon Bedrock (`bedrock-runtime`)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy) |
26| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
27| **Who operates the stack** | Anthropic | AWS | AWS |
28| **API surface** | Claude API (`/v1/{endpoint}`) | Messages API at `/anthropic/v1/messages` | Bedrock Converse / InvokeModel |
29| **Feature availability** | Typically same-day as Claude API (see [feature limitations](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#features-not-supported)) | Follows the Amazon Bedrock release schedule | Follows the Amazon Bedrock release schedule |
30| **Beta features** | Pass through with `anthropic-beta` headers (see [feature limitations](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#features-not-supported)) | The beta features Amazon Bedrock supports, through the `anthropic-beta` header | The beta features Amazon Bedrock supports, through the `anthropic_beta` field of the InvokeModel request body |
31| **Authentication** | AWS IAM / SigV4 or API key | AWS IAM / SigV4 | AWS IAM / SigV4 or bearer token |
32| **Billing** | AWS Marketplace | AWS (native service) | AWS (native service) |
33| **Base URL** | `aws-external-anthropic.{region}.api.aws` | `bedrock-mantle.{region}.api.aws` | `bedrock-runtime.{region}.amazonaws.com` |
34| **SDK client** | `AnthropicAWS` (typescript: `AnthropicAws`; csharp: `AnthropicAwsClient`; go: `anthropicaws.NewClient()`; java: `AwsBackend`; php: `Anthropic\Aws\Client`; ruby: `Anthropic::AWSClient`), in beta | `AnthropicBedrockMantle` | `AnthropicBedrock` / Bedrock SDK |
35| **Console** | Claude Console (`platform.claude.com`, access through the AWS Console) | Bedrock Console | Bedrock Console |
36| **Rate limits and quotas** | Managed by Anthropic | Managed by AWS | Managed by AWS |
37| **Inference data processor** | Anthropic | AWS | AWS |
3838
3939If you need AWS-operated Claude, see [Claude in Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock). Claude Platform on AWS uses a separate capacity pool from both the first-party Claude API and Amazon Bedrock. You can run workloads on more than one platform and fail over between them.
4040
from line 115
115115
116116Once the new organization is running, the differences are concentrated in billing and authentication, which are handled through AWS:
117117
118* **Billing** moves to AWS Marketplace: usage is billed in Claude Consumption Units rather than prepaid credits (see [Billing](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#billing)), and you set spend limits on the **Billing** page (see [Spend limits](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#spend-limits)). During the transition, billing stays separate: the existing organization continues to be billed as it is today.
119* **Authentication and access** move to AWS: requests authenticate with AWS credentials or with API keys generated in the AWS Console, not the Claude Console (see [Authentication](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#authentication)). Organization membership is managed through AWS IAM rather than the Claude Console (see [Available pages](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#available-pages)), and the Claude SDK provides a platform-specific client class (see [Install an SDK](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#install-an-sdk)).
118* **Billing** moves to AWS Marketplace: usage is billed in Claude Consumption Units rather than prepaid credits (see [Billing](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#billing)). You set spend limits in the Claude Console (see [Spend limits](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#spend-limits)). During the transition, billing stays separate: the existing organization keeps its current billing.
119* **Authentication and access** move to AWS: requests authenticate with AWS credentials or with API keys generated in the AWS Console, not the Claude Console (see [Authentication](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#authentication)). You manage organization membership in AWS IAM, not in the Claude Console (see [Available pages](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#available-pages)). The Anthropic SDK has a separate client class for Claude Platform on AWS (see [Install an SDK](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#install-an-sdk)).
120120* **Day-to-day API usage** works the way it does on the first-party Claude API, except where noted in the [feature limitations](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#features-not-supported). Before shifting production traffic, check your rate limits: new organizations are placed on the Start tier, and limit increases go through your Anthropic account representative (see [Rate limits and quotas](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#rate-limits-and-quotas)).
121121
122122For Claude Enterprise (claude.ai) organizations, which behave differently, see the [offering comparison](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#claude-platform-on-aws-vs-amazon-bedrock).
from line 857
857857| **Webhooks** | Yes | Yes | View and manage webhook endpoints. |
858858| **API keys** | No | N/A | Manage API keys in the AWS Console (**Claude Platform on AWS → API keys**). See [API key authentication](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#api-key-authentication). |
859859| **Members** | No | N/A | Not applicable. AWS IAM manages access. |
860| **Billing** | Yes (limited) | No | Set an organization monthly spend limit; see [Spend limits](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#spend-limits). AWS Marketplace manages invoicing. View cost breakdowns on the **Cost** page. |
860| **Spend limits** | Yes | No | Set an organization monthly spend limit; see [Spend limits](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#spend-limits). AWS Marketplace manages invoicing. View cost breakdowns on the **Cost** page. |
861861| **Claude Code** | No | N/A | View Claude Code usage on the **Usage** page. |
862862
863863### Switching organizations
from line 888
888888
889889The Start, Build, and Scale usage tiers each carry a monthly spend cap; see the [per-tier spend caps](https://platform.claude.com/docs/en/api/rate-limits#spend-limits) for current values. When your organization’s usage for the calendar month reaches its tier’s cap, API requests fail with the [spend-cap error](https://platform.claude.com/docs/en/api/rate-limits#reaching-your-spend-cap) until 00:00 UTC on the first day of the next month, and retrying sooner doesn’t succeed. The spend cap and rate limits belong to the same tier. To raise the cap, or to restore access after reaching it, request a tier increase through your Anthropic account representative or [Anthropic support](https://support.claude.com) (see [Rate limits and quotas](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#rate-limits-and-quotas)).
890890
891You can also set your own monthly spend limits below the cap, after adding at least one recipient under **Email recipients** on the **Billing** page:
891You can also set your own monthly spend limits below the cap. First, [open the Claude Console](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#using-the-claude-console) and go to [Spend limits in the Claude Console](https://platform.claude.com/settings/spend-limits) (`platform.claude.com/settings/spend-limits`). Add at least one recipient to your organization’s **Email recipients**, then set either kind of limit:
892892
893* **Organization spend limit:** Go to [Settings > Billing](https://platform.claude.com/settings/billing) in the [Claude Console](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#using-the-claude-console) to set a monthly spend limit.
893* **Organization spend limit:** On the same page, click **Set limit** or **Adjust limit** next to your organization’s **Monthly spend limit**.
894894* **Workspace spend limits:** On the [Workspaces](https://platform.claude.com/settings/workspaces) page (`platform.claude.com/settings/workspaces`) in the Claude Console, select a workspace. In the panel that opens, click **Spend limits**.
895895
896896When usage reaches a limit you set, requests fail with HTTP 400 (see the [spend limit error](https://platform.claude.com/docs/en/api/rate-limits#setting-your-own-spend-limit)) until 00:00 UTC on the first day of the next month, or until you raise or remove the limit.
897897
898Spend is calculated at list prices and can take about 2 hours to reflect recent usage, so usage can exceed the cap or a limit before requests start failing. The overshoot is billed. When the tier cap or an organization spend limit stops your requests, an email notice goes to the recipients listed under **Email recipients** on the **Billing** page. Role-based recipients, such as all admins, aren’t available on Claude Platform on AWS. The tier-cap notice also goes to the email address used at AWS Marketplace sign-up.
898Spend is calculated at list prices and can take about 2 hours to reflect recent usage. As a result, usage can exceed the cap or a limit before requests start failing. The overshoot is billed. When the tier cap or an organization spend limit stops your requests, an email notice goes to the recipients listed under your organization’s **Email recipients**. Role-based recipients, such as all admins, aren’t available on Claude Platform on AWS. The tier-cap notice also goes to the email address used at AWS Marketplace sign-up.
899899
900900## Monitoring and logging
901901
from line 1114
11141114
11151115### What changes
11161116
1117The migration delta depends on which Bedrock integration you’re coming from. The following table shows both the [current Bedrock integration](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock) (Messages API at `bedrock-mantle.{region}.api.aws`) and the [legacy InvokeModel integration](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy).
1117The migration delta depends on which Bedrock integration you’re coming from. The following table shows both [Claude in Amazon Bedrock (`bedrock-mantle`)](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock) (Messages API at `bedrock-mantle.{region}.api.aws`) and [Claude on Amazon Bedrock (`bedrock-runtime`)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy) (the InvokeModel and Converse APIs).
11181118
1119| Aspect | From [Claude in Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock) | From [Amazon Bedrock (Opus 4.6 and earlier)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy) | To Claude Platform on AWS |
1119| Aspect | From [Amazon Bedrock (`bedrock-mantle`)](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock) | From [Amazon Bedrock (`bedrock-runtime`)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy) | To Claude Platform on AWS |
11201120| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
11211121| **Base URL** | `bedrock-mantle.{region}.api.aws` | `bedrock-runtime.{region}.amazonaws.com` | `aws-external-anthropic.{region}.api.aws` |
11221122| **API format** | Messages API at `/anthropic/v1/messages` | Bedrock Converse / InvokeModel | Claude API (`/v1/{endpoint}`) |
from line 1129
11291129| **Region availability** | See [Amazon Bedrock regions](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-regions.html) | See [Amazon Bedrock regions](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-regions.html) | All AWS commercial regions |
11301130| **Anthropic organization** | None required | None required | New organization created at sign-up. Existing organizations can’t be converted (see [Moving from an existing Anthropic organization](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#moving-from-an-existing-anthropic-organization)) |
11311131
1132If you’re on the current Bedrock integration, the request body format is already the Messages API. The changes are the base URL, SigV4 service name, model IDs, and the added `anthropic-workspace-id` header. If you’re on the legacy InvokeModel or Converse API, you’ll also rewrite the request and response shapes to the Messages API format. See [Claude on Amazon Bedrock (Opus 4.6 and earlier)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy) for the request-shape mapping.
1132If you’re on Claude in Amazon Bedrock, the request body format is already the Messages API. The changes are the base URL, SigV4 service name, model IDs, and the added `anthropic-workspace-id` header. If you’re on the InvokeModel or Converse API, you’ll also rewrite the request and response shapes to the Messages API format. See [Claude on Amazon Bedrock (`bedrock-runtime`)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy) for the request-shape mapping.
11331133
11341134### What you gain
11351135
from line 1260
12601260 View usage, cost, and workspaces in the Claude Console. Sign in through the AWS Console.
12611261 </Card>
12621262
1263 <Card title="Claude in Amazon Bedrock" icon="cloud" href="https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock">
1263 <Card title="Claude in Amazon Bedrock (bedrock-mantle)" icon="cloud" href="https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock">
12641264 Use AWS-operated Claude if you need AWS as the sole data processor.
12651265 </Card>
12661266
build-with-claude/compaction-on-demand Changed · +37 / -22 lines
from line 24
2424 - claude-sonnet-4-6
2525 supportedPlatforms:
2626 Claude API: beta
27 Claude Platform on AWS: beta
2827 Amazon Bedrock: beta
28 Claude Platform on AWS: beta
2929 Claude Models on Google Cloud (Google managed): beta
3030 Microsoft Foundry: beta
3131---
from line 339
339339}
340340```
341341
342This example continues the request sample, which ended on a `user` turn; the diagram shows the simpler case, where no turn is taken while the summary is written. Here the second `assistant` message is the reply to the last summarized `user` turn. It arrived while the summary was being written, so it was not among the messages summarized. Two `assistant` messages in a row are fine here, because the block still comes first.
342This example continues the request sample, which ended on a `user` turn. The diagram shows the simpler case, where nobody takes a turn while the API writes the summary. Here the second `assistant` message is the reply to the last summarized `user` turn. It arrived while the API was writing the summary, so the summary doesn’t cover it. Two `assistant` messages in a row are fine here, because the block still comes first.
343343
344344The API puts the summary where the block stands and passes every later message to Claude unchanged. Follow these rules:
345345
from line 348
348348* Send exactly one `compaction` block in each request, on every later request.
349349
350350<Warning>
351 Two mistakes in the swap raise no error. If summarized messages remain after the block, the API sends them to Claude again. If a later request leaves the block out, Claude gets no summary.
351 Two mistakes in the swap can pass without an error:
352
353 * **The block is left out of a later request:** Claude gets no summary.
354 * **Summarized messages stay after the block:** the API sends them to Claude again.
355
356 On models with [preserved thinking](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking), either mistake can also make thinking blocks in the request fail the [prefix check](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#prefix-check).
352357</Warning>
353358
354359Threshold compaction works the other way around: its block follows the messages it summarizes, and the API drops them for you. See [Passing compaction blocks back](https://platform.claude.com/docs/en/build-with-claude/compaction-threshold#passing-compaction-blocks-back).
355360
356In Python, use `client.beta.messages`, as the samples on this page do. If you call `client.messages` and serialize blocks yourself, use `to_dict()` or `model_dump(exclude_none=True)`: a plain `model_dump()` adds `citations: null` and `text: null` to the block, and the API rejects it.
357
358361If you keep turns after the block and send their thinking blocks back, the conditions that keep that thinking valid are on [Compaction and preserved thinking](https://platform.claude.com/docs/en/build-with-claude/compaction-thinking-blocks).
359362
360363### Compact again
from line 368
365368
366369After each turn, the loop adds the last response’s input and output tokens, because the next request sends the reply too. When that total passes a limit and another turn is still to come, it sends a compaction request with the same model and `system` prompt, checks `stop_reason`, replaces its history with the returned message, and prints the turn it compacted before. The sample’s limit of 2,500 tokens is deliberately low, so that a short conversation compacts. Set yours near your real input budget.
367370
368<CodeGroup exclude="shell">
371<CodeGroup exclude="shell:cURL, shell:CLI">
372 <CodeGroupItem language="cURL">
373 This workflow needs more logic than a single shell command. Use the Anthropic SDK to run it.
374 </CodeGroupItem>
375
376 <CodeGroupItem language="CLI">
377 This workflow needs more logic than a single shell command. Use the Anthropic SDK to run it.
378 </CodeGroupItem>
379
369380 ```python Python
370381 from anthropic.types.beta import BetaMessageParam
371382
from line 421
410421 compaction={"type": "summarize"},
411422 )
412423 if summary.stop_reason == "compaction":
424 # Use client.beta.messages. If you call client.messages and serialize blocks yourself,
425 # use to_dict() or model_dump(exclude_none=True): a plain model_dump() adds
426 # citations: null and text: null to the block, and the API rejects it.
413427 history = [{"role": "assistant", "content": summary.content}]
414428 print(f"Compacted before turn {turn + 1}")
415429 ```
from line 567
553567 }
554568
555569 var history []anthropic.BetaMessageParam
556 for i, question := range questions {
557 turn := i + 1
570 for index, question := range questions {
571 turn := index + 1
558572 history = append(history, anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock(question)))
559573 response, err := client.Beta.Messages.New(ctx, anthropic.BetaMessageNewParams{
560574 Model: anthropic.ModelClaudeOpus5_5,
from line 774
760774
761775The check on `stop_reason` comes before the code looks for the block; [Handle a missing summary or an error](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand#when-no-summary-comes-back) says why. The history is replaced, not appended to: the returned message replaces every message the request carried, under the rules in [Continue from the summary](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand#continue-from-the-summary). When no summary comes back, the loop keeps its history and asks again after the next turn.
762776
763The SDK [tool runner](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-runner) in Python, TypeScript, C#, Go, Java, PHP, and Ruby can send the compaction request for you. When you decide to compact, call `compact_before_next_turn()` (typescript, java, php: `compactBeforeNextTurn()`; csharp, go: `CompactBeforeNextTurn()`) on the runner. Once the current turn and its tool calls complete, the runner sends the compaction request and replaces its history with the returned message. Create the runner with the `compact-2026-09-04` beta, because the runner doesn’t add it.
777The SDK [tool runner](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-runner) can send the compaction request for you. When you decide to compact, call `compact_before_next_turn()` (ruby: `compact_before_next_turn`; typescript, java, php: `compactBeforeNextTurn()`; csharp, go: `CompactBeforeNextTurn()`) on the runner. Once the current turn and its tool calls complete, the runner sends the compaction request and replaces its history with the returned message. Create the runner with the `compact-2026-09-04` beta, because the runner doesn’t add it.
764778
765779The runner builds the compaction request from its own parameters and leaves `context_management` out. It also leaves out `stop_sequences`, a `tool_choice` of type `any` or `tool`, and a structured-output `output_config.format`, which the API rejects on a compaction request. [Request a summary](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand#request-a-summary) explains why. The runner sends them again on its later requests. SDK versions before Python 1.8.0, TypeScript 0.128.0, C# 12.50.0, Go 1.75.0, and Java 2.65.0 send them on the compaction request too. On those versions, a runner that sets any of these parameters gets a 400 error. The runner sends a [task budget](https://platform.claude.com/docs/en/build-with-claude/task-budgets) unchanged. If `output_config.task_budget` sets `remaining`, the compaction request returns a 400 error, so leave `remaining` unset, as [Limits and interactions with other features](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand#how-it-fits-with-the-rest-of-the-api) says. The runner refuses to compact while its `context_management` has a compaction edit, so use one kind of compaction on a runner.
766780
from line 819
805819
806820A compaction request, or a request that carries a block, can also fail outright. Most 400 errors have a message that says what to remove or resend. Some also carry an `error.details.error_code` that starts with `compaction_`. Parameter errors, such as a field that can’t be combined with `compaction`, carry the message only.
807821
808| Error | Cause | What to do |
809| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
810| 529 `overloaded_error`, `error.details.error_code` `compaction_unavailable` | A transient server problem while producing a block, or while reading one you sent back. | Retry the request. |
811| 400 `compaction_block_misplaced` | Summarized messages remain in front of the block. | Remove them, so the block comes first in `messages`. |
812| 400 `compaction_signature_invalid` or `compaction_content_mismatch` | The block’s `signature` or `content` was changed after the API returned it. | Send the block exactly as returned, including its `signature`. |
813| 400 | The request carries more than one `compaction` block. | Send exactly one, the newest. |
814| 400 | The last `assistant` turn ends in a tool call with no result yet. | Send that turn’s tool results, then compact. |
815| 400 `compaction_nothing_to_summarize` | `messages` has no `user` or `assistant` content, for example an empty list. | Send at least one `user` or `assistant` message. |
816| 400 on the compaction request, with a message that says the `compaction` parameter `requires anthropic-beta: compact-2026-09-04` | The compaction request left out the beta header. | Add the beta header; see [Request a summary](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand#request-a-summary). |
817| 400 on a later request that carries the block: a validation error that says `compaction` is not one of the expected content block types. The message doesn’t mention the header. | That request left out the beta header. | Add the beta header to every request that carries the block; see [Request a summary](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand#request-a-summary). |
818| 400 validation error, such as `messages.0.content.0.compaction.citations: Extra inputs are not permitted` | A block was sent back with fields the API didn’t return, such as `citations: null`. | Send the block exactly as returned; see [Continue from the summary](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand#continue-from-the-summary). |
822| Error | Cause | What to do |
823| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
824| 529 `overloaded_error`, `error.details.error_code` `compaction_unavailable` | A transient server problem while producing a block, or while reading one you sent back. | Retry the request. |
825| 400 `compaction_block_misplaced` | Summarized messages remain in front of the block. | Remove them, so the block comes first in `messages`. |
826| 400 `compaction_signature_invalid` or `compaction_content_mismatch` | The block’s `signature` or `content` was changed after the API returned it. | Send the block exactly as returned, including its `signature`. |
827| 400 | The request carries more than one `compaction` block. | Send exactly one, the newest. |
828| 400 | The last `assistant` turn ends in a tool call with no result yet. | Send that turn’s tool results, then compact. |
829| 400 `compaction_nothing_to_summarize` | `messages` has no `user` or `assistant` content, for example an empty list. | Send at least one `user` or `assistant` message. |
830| 400 with a message that a thinking block is `bound to a different conversation` | On a model with preserved thinking, a thinking block in the compaction request failed the [prefix check](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#prefix-check). | [Handle the error](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#handle-the-error-in-code), then compact. |
831| 400 on the compaction request, with a message that says the `compaction` parameter `requires anthropic-beta: compact-2026-09-04` | The compaction request left out the beta header. | Add the beta header; see [Request a summary](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand#request-a-summary). |
832| 400 on a later request that carries the block: a validation error that says `compaction` is not one of the expected content block types. The message doesn’t mention the header. | That request left out the beta header. | Add the beta header to every request that carries the block; see [Request a summary](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand#request-a-summary). |
833| 400 validation error, such as `messages.0.content.0.compaction.citations: Extra inputs are not permitted` | A block was sent back with fields the API didn’t return, such as `citations: null`. | Send the block exactly as returned; see [Continue from the summary](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand#continue-from-the-summary). |
819834
820835## Count compaction usage
821836
from line 842
827842
828843* **Threshold compaction and context editing.** You can’t send `compaction` and `context_management` on the same request. Threshold compaction (`compact_20260112`) can’t run on a request that carries a signed block.
829844* **Prompt caching.** `cache_control` on the block places a breakpoint after the summary.
830* **Mid-conversation system messages and tool changes.** `role: "system"` messages inside the summarized range are summarized too, so their text instructions stop applying once the block replaces them. A [per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta) level they set isn’t carried over either: until a later message sets a level, turns run at the request’s top-level `output_config.effort`, or the model’s default if you don’t set one. If an instruction or effort level still matters, state it again in a `role: "system"` message. Send that message right after your next new `user` turn, and leave it in your history from then on. For [tool changes](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#mid-conversation-tool-changes), and for where that message goes when you keep turns after the block, see [Change the system prompt or tools](https://platform.claude.com/docs/en/build-with-claude/compaction-thinking-blocks#change-the-system-prompt-or-tools).
845* **Mid-conversation system messages and tool changes.** `role: "system"` messages inside the summarized range are summarized too, so their text instructions stop applying once the block replaces them. A [per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort-per-message) level they set isn’t carried over either: until a later message sets a level, turns run at the request’s top-level `output_config.effort`, or the model’s default if you don’t set one. If an instruction or effort level still matters, state it again in a `role: "system"` message. Send that message right after your next new `user` turn, and leave it in your history from then on. For [tool changes](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#mid-conversation-tool-changes), and for where that message goes when you keep turns after the block, see [Change the system prompt or tools](https://platform.claude.com/docs/en/build-with-claude/compaction-thinking-blocks#change-the-system-prompt-or-tools).
831846* **Task budgets.** Don’t send the `remaining` value of a [task budget](https://platform.claude.com/docs/en/build-with-claude/task-budgets) (`output_config.task_budget.remaining`) with `compaction` or on requests that carry the block. Doing so returns a 400 error.
832847* **Token counting.** The [token counting](https://platform.claude.com/docs/en/build-with-claude/token-counting) endpoint ignores the `compaction` parameter.
833848* **Content the summary can’t carry.** Images, documents, `container_upload` blocks, and fetched URLs inside the summarized messages are gone once the block replaces them. Restate or re-upload anything a later turn still needs.
from line 860
845860| Status | Cloud platforms | Models |
846861| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
847862| Beta | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed), [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry) | [Claude Fable 5.2](https://platform.claude.com/docs/en/models/fable-5-2/overview), [Claude Mythos 5.2](https://platform.claude.com/docs/en/models/mythos-5-2/overview), [Claude Fable 5.1](https://platform.claude.com/docs/en/models/fable-5-1/overview), [Claude Mythos 5.1](https://platform.claude.com/docs/en/models/mythos-5-1/overview), [Claude Fable 5](https://platform.claude.com/docs/en/models/fable-5/overview), [Claude Mythos 5](https://platform.claude.com/docs/en/models/mythos-5/overview), Claude Mythos Preview, [Claude Opus 5.5](https://platform.claude.com/docs/en/models/opus-5-5/overview), [Claude Opus 5](https://platform.claude.com/docs/en/models/opus-5/overview), [Claude Sonnet 5.5](https://platform.claude.com/docs/en/models/sonnet-5-5/overview), [Claude Sonnet 5](https://platform.claude.com/docs/en/models/sonnet-5/overview), [Claude Haiku 5.5](https://platform.claude.com/docs/en/models/haiku-5-5/overview), [Claude Opus 4.8](https://platform.claude.com/docs/en/models/opus-4-8/overview), [Claude Opus 4.7](https://platform.claude.com/docs/en/models/opus-4-7/overview), [Claude Opus 4.6](https://platform.claude.com/docs/en/models/opus-4-6/overview), [Claude Sonnet 4.6](https://platform.claude.com/docs/en/models/sonnet-4-6/overview) |
848| Beta | [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock) | [Claude Fable 5.2](https://platform.claude.com/docs/en/models/fable-5-2/overview), [Claude Mythos 5.2](https://platform.claude.com/docs/en/models/mythos-5-2/overview), [Claude Fable 5.1](https://platform.claude.com/docs/en/models/fable-5-1/overview), [Claude Mythos 5.1](https://platform.claude.com/docs/en/models/mythos-5-1/overview), [Claude Fable 5](https://platform.claude.com/docs/en/models/fable-5/overview), [Claude Mythos 5](https://platform.claude.com/docs/en/models/mythos-5/overview), [Claude Opus 5.5](https://platform.claude.com/docs/en/models/opus-5-5/overview), [Claude Opus 5](https://platform.claude.com/docs/en/models/opus-5/overview), [Claude Sonnet 5.5](https://platform.claude.com/docs/en/models/sonnet-5-5/overview), [Claude Sonnet 5](https://platform.claude.com/docs/en/models/sonnet-5/overview), [Claude Haiku 5.5](https://platform.claude.com/docs/en/models/haiku-5-5/overview), [Claude Opus 4.8](https://platform.claude.com/docs/en/models/opus-4-8/overview), [Claude Opus 4.7](https://platform.claude.com/docs/en/models/opus-4-7/overview) |
863| Beta | [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock) | [Claude Fable 5.1](https://platform.claude.com/docs/en/models/fable-5-1/overview), [Claude Mythos 5.1](https://platform.claude.com/docs/en/models/mythos-5-1/overview), [Claude Fable 5](https://platform.claude.com/docs/en/models/fable-5/overview), [Claude Mythos 5](https://platform.claude.com/docs/en/models/mythos-5/overview), [Claude Opus 5.5](https://platform.claude.com/docs/en/models/opus-5-5/overview), [Claude Opus 5](https://platform.claude.com/docs/en/models/opus-5/overview), [Claude Sonnet 5.5](https://platform.claude.com/docs/en/models/sonnet-5-5/overview), [Claude Sonnet 5](https://platform.claude.com/docs/en/models/sonnet-5/overview), [Claude Haiku 5.5](https://platform.claude.com/docs/en/models/haiku-5-5/overview), [Claude Opus 4.8](https://platform.claude.com/docs/en/models/opus-4-8/overview), [Claude Opus 4.7](https://platform.claude.com/docs/en/models/opus-4-7/overview) |
849864
850865### Required beta headers
851866
build-with-claude/compaction-thinking-blocks Changed · +38 / -7 lines
from line 29
2929 Microsoft Foundry: beta
3030---
3131
32Skip this page unless you send thinking blocks back to a model with [preserved thinking](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking) and keep turns after the compaction block. Kept turns are the turns that follow the block: recent turns you left out of the compaction request, as in [Compaction that keeps recent turns](https://platform.claude.com/docs/en/build-with-claude/compaction-keep-recent-turns), or turns that arrived while the summary was being written, as in [Compaction in the background](https://platform.claude.com/docs/en/build-with-claude/compaction-background).
32Skip this page unless you send thinking blocks back to a model with [preserved thinking](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking) and keep turns after the compaction block. Kept turns are the turns that follow the block. They’re either recent turns you left out of the compaction request, as in [Compaction that keeps recent turns](https://platform.claude.com/docs/en/build-with-claude/compaction-keep-recent-turns), or turns that arrived while the API was writing the summary, as in [Compaction in the background](https://platform.claude.com/docs/en/build-with-claude/compaction-background).
3333
3434Models with preserved thinking check earlier thinking blocks against the conversation that produced them. A summary replaces part of that conversation, but the check accepts the swap when the API wrote the summary, so the thinking in kept turns can stay valid.
3535
from line 39
3939
4040* **The compaction request runs on a model with preserved thinking.** This condition covers every compaction request since a thinking block was produced, not only the most recent one. One way to meet it is to send every compaction request to the model the conversation uses.
4141* **The kept turns directly follow the summarized messages, and you send them unchanged.** Send each kept message exactly as it is in your history. Don’t skip or add a message between the last summarized message and the first kept one. The first kept message must also have a different role from the last summarized message, and it can’t be a mid-conversation `role: "system"` message. Otherwise, the API merges it into the last summarized message. One way to get the first kept message right is to compact exactly the `messages` of a request you already sent. The kept turns then start with Claude’s reply to it.
42* **`system` and the `tools` not marked `defer_loading: true` don’t change.** They are the same on the compaction request as on the requests that produced the kept thinking, and they stay the same on the requests that follow. [Change the system prompt or tools](https://platform.claude.com/docs/en/build-with-claude/compaction-thinking-blocks#change-the-system-prompt-or-tools) covers how to change them safely.
42* **`system` and `tools` don’t change.** They are the same on the compaction request as on the requests that produced the kept thinking, and they stay the same on the requests that follow. The exception is a tool marked `defer_loading: true` that nothing in the conversation has referenced. [Change the system prompt or tools](https://platform.claude.com/docs/en/build-with-claude/compaction-thinking-blocks#change-the-system-prompt-or-tools) covers how to change them safely.
4343
44If a condition doesn’t hold, nothing fails when you compact, and the API accepts the compaction block on later requests either way. What fails is the kept thinking, on the first later request that sends it. [What the API does with an invalid block](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#mismatch-behavior) describes what happens then, and [When `prefix_mismatch_behavior` is unset](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#enforcement) covers requests that don’t set the field, including Message Batches items.
44If a condition doesn’t hold, the API still accepts the compaction block on later requests. What fails is the kept thinking, on the first later request that sends it. The compaction request runs the same check on the thinking blocks it carries, so a changed `system` or `tools`, or an edited message, can fail that request too. [What the API does with an invalid block](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#mismatch-behavior) describes what happens then, and [When `prefix_mismatch_behavior` is unset](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#enforcement) covers requests that don’t set the field, including Message Batches items.
4545
4646## Compact again without breaking older thinking
4747
from line 59
5959
6060To add an instruction or change the available tools without touching `system` or `tools`, append the change to `messages`, as described in [Make changes without editing the prefix](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#replace-prefix-edits).
6161
62Mid-conversation system messages inside the summarized turns are summarized too, so their text instructions stop applying after the swap. A [per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta) level they set isn’t carried over either: until a later message sets a level, turns run at the request’s top-level `output_config.effort`, or the model’s default if you don’t set one. To keep an instruction or effort level in force, state it again in a `role: "system"` message directly after the first new `user` turn that follows the kept turns. Tool changes inside those turns carry over on their own when the compaction request also carries `inline-tools-2026-09-15`: the returned block records their net effect in its `tool_changes` field, so send the block back unmodified. If the block has no `tool_changes` field, restate those tool changes the same way. A system message placed between the block and the kept turns breaks their thinking.
62The summarized turns can include mid-conversation system messages, which are `role: "system"` entries in `messages` (see [Mid-conversation system messages and tool changes](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages)). They’re summarized with the rest. What happens next depends on what a message carried:
6363
64* **Text instructions** stop applying.
65* **A [per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort-per-message) level** stops applying too. Turns then run at the request’s top-level `output_config.effort`. If the request sets none, they run at the model’s default. A later message can set a level again.
66* **Tool changes** can carry over. See the steps that follow.
67
68To carry tool changes over:
69
701. Send the `inline-tools-2026-09-15` beta header on the compaction request. The returned block then records the changes in a `tool_changes` field.
712. Send the block back unmodified. The API then applies the recorded changes on each request that includes the block. If the field is missing, the API accepts the block but applies nothing.
723. Send the same header on every request that includes the block.
73
74If the summarized turns changed your tools and the returned block has no `tool_changes` field, the changes weren’t recorded. State them again, as described next.
75
76You can state an instruction, an effort level, or a tool change again. Put it in a `role: "system"` message at the end of your next request, directly after the `user` message. The request’s `messages` then run in this order:
77
781. The compaction block.
792. The kept turns, if any.
803. Your `user` message.
814. The `role: "system"` message.
82
83On later requests, leave those entries as they are, and add new turns after the system message.
84
85Don’t put the system message before or between the kept turns. There, it invalidates every kept thinking block that comes after it.
86
6487## Check that the kept thinking held
6588
6689The compaction response doesn’t say whether the kept thinking holds. The first request after the swap does. To check in your tests:
from line 97
7497
7598The following program runs the four steps. It prints how many thinking blocks the kept turn holds and how many entries `input_transformations` has; no entries means the kept thinking held:
7699
77<CodeGroup exclude="shell">
100<CodeGroup exclude="shell:cURL, shell:CLI">
101 <CodeGroupItem language="cURL">
102 This workflow needs more logic than a single shell command. Use the Anthropic SDK to run it.
103 </CodeGroupItem>
104
105 <CodeGroupItem language="CLI">
106 This workflow needs more logic than a single shell command. Use the Anthropic SDK to run it.
107 </CodeGroupItem>
108
78109 ```python Python
79110 from anthropic.types.beta import BetaMessageParam, BetaThinkingConfigParam
80111
from line 181
150181 )
151182
152183 # 4. A 200 with no dropped blocks means the kept thinking held.
153 print(f"Dropped thinking blocks: {len(third.input_transformations)}")
184 print(f"Dropped thinking blocks: {len(third.input_transformations or [])}")
154185 ```
155186
156187 ```typescript TypeScript
build-with-claude/compaction-threshold Changed · +486 / -438 lines
The two sides of this change are more than 400 edits apart, too far apart to line up, so this is the differ's own diff of it and the words inside a line are not marked.
from line 28
2828 - claude-sonnet-4-6
2929 supportedPlatforms:
3030 Claude API: beta
31 Amazon Bedrock: beta
32 Amazon Bedrock (bedrock-runtime): beta
3133 Claude Platform on AWS: beta
32 Amazon Bedrock: beta
33 Amazon Bedrock (InvokeModel): beta
3434 Claude Models on Google Cloud (Google managed): beta
3535 Microsoft Foundry: beta
3636---
from line 219
219219 import com.anthropic.models.beta.messages.BetaContextManagementConfig;
220220 import com.anthropic.models.beta.messages.BetaCompact20260112Edit;
221221 // ...
222 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
223
224 MessageCreateParams params = MessageCreateParams.builder()
225 .addBeta("compact-2026-01-12")
226 .model(Model.CLAUDE_OPUS_5_5)
227 .maxTokens(4096L)
228 .addUserMessage("Help me build a website")
229 .contextManagement(BetaContextManagementConfig.builder()
230 .addEdit(BetaCompact20260112Edit.builder().build())
231 .build())
232 .build();
233
234 BetaMessage response = client.beta().messages().create(params);
235
236 // Append the response (including any compaction block) to continue the conversation
237 // by including it in the next request's messages
238 System.out.println(response);
222
223 void main() {
224 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
225
226 MessageCreateParams params = MessageCreateParams.builder()
227 .addBeta("compact-2026-01-12")
228 .model(Model.CLAUDE_OPUS_5_5)
229 .maxTokens(4096L)
230 .addUserMessage("Help me build a website")
231 .contextManagement(BetaContextManagementConfig.builder()
232 .addEdit(BetaCompact20260112Edit.builder().build())
233 .build())
234 .build();
235
236 BetaMessage response = client.beta().messages().create(params);
237
238 // To continue the conversation, add response.toParam() (including any
239 // compaction block) to the next request's messages
240 System.out.println(response);
241 }
239242 ```
240243
241244 ```php PHP
from line 316
313316 "messages": [
314317 {
315318 "role": "user",
316 "content": "Hello, Claude"
319 "content": "Help me build a website"
317320 }
318321 ],
319322 "context_management": {
from line 339
336339 max_tokens: 4096
337340 messages:
338341 - role: user
339 content: Hello, Claude
342 content: Help me build a website
340343 context_management:
341344 edits:
342345 - type: compact_20260112
from line 351
348351
349352 ```python Python
350353 client = anthropic.Anthropic()
351 messages = [{"role": "user", "content": "Hello, Claude"}]
354 messages = [{"role": "user", "content": "Help me build a website"}]
352355 response = client.beta.messages.create(
353356 betas=["compact-2026-01-12"],
354357 model="claude-opus-5-5",
from line 371
368371 ```typescript TypeScript
369372 const client = new Anthropic();
370373 const messages: Anthropic.Beta.Messages.BetaMessageParam[] = [
371 { role: "user", content: "Hello, Claude" }
374 { role: "user", content: "Help me build a website" }
372375 ];
373376
374377 const response = await client.beta.messages.create({
from line 395
392395
393396 ```csharp C#
394397 AnthropicClient client = new();
395 List<BetaMessageParam> messages = [new BetaUserMessageParam { Content = "Hello" }];
398 List<BetaMessageParam> messages = [new BetaUserMessageParam { Content = "Help me build a website" }];
396399
397400 var parameters = new MessageCreateParams
398401 {
from line 418
415418
416419 ```go Go
417420 client := anthropic.NewClient()
418 messages := []anthropic.BetaMessageParam{anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello, Claude"))}
421 messages := []anthropic.BetaMessageParam{anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Help me build a website"))}
419422
420423 response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
421424 Model: anthropic.ModelClaudeOpus5_5,
from line 444
441444 import com.anthropic.models.beta.messages.BetaCompact20260112Edit;
442445 import com.anthropic.models.beta.messages.BetaInputTokensTrigger;
443446 // ...
444 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
445
446 MessageCreateParams params = MessageCreateParams.builder()
447 .model(Model.CLAUDE_OPUS_5_5)
448 .maxTokens(4096L)
449 .addBeta("compact-2026-01-12")
450 .addUserMessage("Hello, Claude")
451 .contextManagement(BetaContextManagementConfig.builder()
452 .addEdit(BetaCompact20260112Edit.builder()
453 .trigger(BetaInputTokensTrigger.builder()
454 .value(150000L)
455 .build())
447
448 void main() {
449 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
450
451 MessageCreateParams params = MessageCreateParams.builder()
452 .model(Model.CLAUDE_OPUS_5_5)
453 .maxTokens(4096L)
454 .addBeta("compact-2026-01-12")
455 .addUserMessage("Help me build a website")
456 .contextManagement(BetaContextManagementConfig.builder()
457 .addEdit(BetaCompact20260112Edit.builder()
458 .trigger(BetaInputTokensTrigger.builder()
459 .value(150000L)
456460 .build())
457461 .build())
458 .build();
459
460 BetaMessage response = client.beta().messages().create(params);
461 System.out.println(response);
462 .build())
463 .build();
464
465 BetaMessage response = client.beta().messages().create(params);
466 System.out.println(response);
467 }
462468 ```
463469
464470 ```php PHP
465471 $client = new Client();
466 $messages = [['role' => 'user', 'content' => 'Hello, Claude']];
472 $messages = [['role' => 'user', 'content' => 'Help me build a website']];
467473
468474 $message = $client->beta->messages->create(
469475 maxTokens: 4096,
from line 494
488494
489495 ```ruby Ruby
490496 client = Anthropic::Client.new
491 messages = [{ role: "user", content: "Hello, Claude" }]
497 messages = [{ role: "user", content: "Help me build a website" }]
492498
493499 response = client.beta.messages.create(
494500 betas: ["compact-2026-01-12"],
from line 519
513519
514520### Custom summarization instructions
515521
516The 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:
522The 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, this is one of the default prompts:
517523
518524```text wrap
519525You 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.
from line 540
534540 "messages": [
535541 {
536542 "role": "user",
537 "content": "Hello, Claude"
543 "content": "Help me build a website"
538544 }
539545 ],
540546 "context_management": {
from line 560
554560 max_tokens: 4096
555561 messages:
556562 - role: user
557 content: Hello, Claude
563 content: Help me build a website
558564 context_management:
559565 edits:
560566 - type: compact_20260112
from line 572
566572
567573 ```python Python
568574 client = anthropic.Anthropic()
569 messages = [{"role": "user", "content": "Hello, Claude"}]
575 messages = [{"role": "user", "content": "Help me build a website"}]
570576 response = client.beta.messages.create(
571577 betas=["compact-2026-01-12"],
572578 model="claude-opus-5-5",
from line 592
586592 ```typescript TypeScript
587593 const client = new Anthropic();
588594 const messages: Anthropic.Beta.Messages.BetaMessageParam[] = [
589 { role: "user", content: "Hello, Claude" }
595 { role: "user", content: "Help me build a website" }
590596 ];
591597
592598 const response = await client.beta.messages.create({
from line 669
663669 import com.anthropic.models.beta.messages.BetaContextManagementConfig;
664670 import com.anthropic.models.beta.messages.BetaCompact20260112Edit;
665671 // ...
666 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
667
668 MessageCreateParams params = MessageCreateParams.builder()
669 .addBeta("compact-2026-01-12")
670 .model(Model.CLAUDE_OPUS_5_5)
671 .maxTokens(4096L)
672 .addUserMessage("Help me build a Python web scraper")
673 .addAssistantMessage("I'll help you build a web scraper...")
674 .addUserMessage("Add support for JavaScript-rendered pages")
675 .contextManagement(BetaContextManagementConfig.builder()
676 .addEdit(BetaCompact20260112Edit.builder()
677 .instructions("Focus on preserving code snippets, variable names, and technical decisions.")
678 .build())
672
673 void main() {
674 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
675
676 MessageCreateParams params = MessageCreateParams.builder()
677 .addBeta("compact-2026-01-12")
678 .model(Model.CLAUDE_OPUS_5_5)
679 .maxTokens(4096L)
680 .addUserMessage("Help me build a Python web scraper")
681 .addAssistantMessage("I'll help you build a web scraper...")
682 .addUserMessage("Add support for JavaScript-rendered pages")
683 .contextManagement(BetaContextManagementConfig.builder()
684 .addEdit(BetaCompact20260112Edit.builder()
685 .instructions("Focus on preserving code snippets, variable names, and technical decisions.")
679686 .build())
680 .build();
681
682 BetaMessage response = client.beta().messages().create(params);
683 System.out.println(response);
687 .build())
688 .build();
689
690 BetaMessage response = client.beta().messages().create(params);
691 System.out.println(response);
692 }
684693 ```
685694
686695 ```php PHP
from line 744
735744 ```
736745</CodeGroup>
737746
738On Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5, a request with custom `instructions` summarizes from the visible conversation only: earlier thinking blocks are not part of the summarizer’s input.
747On some models, a request with custom `instructions` summarizes from the visible conversation only, without earlier thinking blocks. Those models are Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5.
739748
740749### Pausing after compaction
741750
from line 755
746755<CodeGroup>
747756 ```bash cURL
748757 # pause_after_compaction stops the response right after the compaction
749 # summary so you can adjust the messages before continuing. The continue
750 # step doesn't translate well to a one-off shell command; see the SDK tabs
751 # for the full pause-and-continue flow. Single paused request:
758 # summary so you can adjust the messages before continuing. Continuing
759 # needs more logic than a one-off shell command. Single paused request:
752760 curl https://api.anthropic.com/v1/messages \
753761 -H "x-api-key: $ANTHROPIC_API_KEY" \
754762 -H "anthropic-version: 2026-10-21" \
from line 768
760768 "messages": [
761769 {
762770 "role": "user",
763 "content": "Hello, Claude"
771 "content": "Help me build a website"
764772 }
765773 ],
766774 "context_management": {
from line 784
776784
777785 ```bash CLI
778786 # pause_after_compaction stops the response right after the compaction
779 # summary so you can adjust the messages before continuing. The continue
780 # step doesn't translate well to a one-off CLI command; see the SDK tabs
781 # for the full pause-and-continue flow. Single paused request:
782 ant beta:messages create --beta compact-2026-01-12 --format jsonl <<'YAML'
787 # summary so you can adjust the messages before continuing. Continuing
788 # needs more logic than a one-off CLI command. Single paused request:
789 ant beta:messages create --beta compact-2026-01-12 <<'YAML'
783790 model: claude-opus-5-5
784791 max_tokens: 4096
785792 messages:
786793 - role: user
787 content: Hello, Claude
794 content: Help me build a website
788795 context_management:
789796 edits:
790797 - type: compact_20260112
from line 801
794801
795802 ```python Python
796803 client = anthropic.Anthropic()
797 messages = [{"role": "user", "content": "Hello, Claude"}]
804 messages = [{"role": "user", "content": "Help me build a website"}]
798805 response = client.beta.messages.create(
799806 betas=["compact-2026-01-12"],
800807 model="claude-opus-5-5",
from line 830
823830 ```typescript TypeScript
824831 const client = new Anthropic();
825832 const messages: Anthropic.Beta.Messages.BetaMessageParam[] = [
826 { role: "user", content: "Hello, Claude" }
833 { role: "user", content: "Help me build a website" }
827834 ];
828835
829836 let response = await client.beta.messages.create({
from line 873
866873 var client = new AnthropicClient();
867874 var messages = new List<BetaMessageParam>
868875 {
869 new BetaUserMessageParam { Content = "Hello, Claude" }
876 new BetaUserMessageParam { Content = "Help me build a website" }
870877 };
871878
872879 var parameters = new MessageCreateParams
from line 920
913920
914921 ```go Go
915922 client := anthropic.NewClient()
916 messages := []anthropic.BetaMessageParam{anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello, Claude"))}
923 messages := []anthropic.BetaMessageParam{anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Help me build a website"))}
917924
918925 compactEdit := anthropic.BetaContextManagementConfigParam{
919926 Edits: []anthropic.BetaContextManagementConfigEditUnionParam{
from line 968
961968 import com.anthropic.models.beta.messages.BetaCompact20260112Edit;
962969 import com.anthropic.models.beta.messages.BetaStopReason;
963970 // ...
964 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
965
966 MessageCreateParams params = MessageCreateParams.builder()
971
972 void main() {
973 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
974
975 MessageCreateParams params = MessageCreateParams.builder()
976 .model(Model.CLAUDE_OPUS_5_5)
977 .maxTokens(4096L)
978 .addBeta("compact-2026-01-12")
979 .addUserMessage("Help me build a website")
980 .contextManagement(BetaContextManagementConfig.builder()
981 .addEdit(BetaCompact20260112Edit.builder()
982 .pauseAfterCompaction(true)
983 .build())
984 .build())
985 .build();
986
987 BetaMessage response = client.beta().messages().create(params);
988
989 // Check if compaction triggered a pause
990 if (response.stopReason().isPresent()
991 && response.stopReason().get().equals(BetaStopReason.COMPACTION)) {
992 // Append the compaction block and continue the request
993 // by building a new request with the compacted context
994 MessageCreateParams continueParams = MessageCreateParams.builder()
967995 .model(Model.CLAUDE_OPUS_5_5)
968996 .maxTokens(4096L)
969997 .addBeta("compact-2026-01-12")
970998 .addUserMessage("Help me build a website")
999 .addMessage(response)
9711000 .contextManagement(BetaContextManagementConfig.builder()
972 .addEdit(BetaCompact20260112Edit.builder()
973 .pauseAfterCompaction(true)
974 .build())
1001 .addEdit(BetaCompact20260112Edit.builder().build())
9751002 .build())
9761003 .build();
9771004
978 BetaMessage response = client.beta().messages().create(params);
979
980 // Check if compaction triggered a pause
981 if (response.stopReason().isPresent()
982 && response.stopReason().get().equals(BetaStopReason.COMPACTION)) {
983 // Append the compaction block and continue the request
984 // by building a new request with the compacted context
985 MessageCreateParams continueParams = MessageCreateParams.builder()
986 .model(Model.CLAUDE_OPUS_5_5)
987 .maxTokens(4096L)
988 .addBeta("compact-2026-01-12")
989 .addUserMessage("Help me build a website")
990 .addMessage(response)
991 .contextManagement(BetaContextManagementConfig.builder()
992 .addEdit(BetaCompact20260112Edit.builder().build())
993 .build())
994 .build();
995
996 response = client.beta().messages().create(continueParams);
997 }
998
999 System.out.println(response);
1005 response = client.beta().messages().create(continueParams);
1006 }
1007
1008 System.out.println(response);
1009 }
10001010 ```
10011011
10021012 ```php PHP
10031013 $client = new Client();
1004 $messages = [['role' => 'user', 'content' => 'Hello, Claude']];
1014 $messages = [['role' => 'user', 'content' => 'Help me build a website']];
10051015
10061016 $response = $client->beta->messages->create(
10071017 maxTokens: 4096,
10081018 messages: $messages,
1009 model: 'claude-opus-5-5',
1019 model: Model::CLAUDE_OPUS_5_5,
10101020 betas: ['compact-2026-01-12'],
10111021 contextManagement: [
10121022 'edits' => [
from line 1037
10271037 $response = $client->beta->messages->create(
10281038 maxTokens: 4096,
10291039 messages: $messages,
1030 model: 'claude-opus-5-5',
1040 model: Model::CLAUDE_OPUS_5_5,
10311041 betas: ['compact-2026-01-12'],
10321042 contextManagement: [
10331043 'edits' => [
from line 1052
10421052
10431053 ```ruby Ruby
10441054 client = Anthropic::Client.new
1045 messages = [{ role: "user", content: "Hello, Claude" }]
1055 messages = [{ role: "user", content: "Help me build a website" }]
10461056
10471057 response = client.beta.messages.create(
10481058 betas: ["compact-2026-01-12"],
from line 1093
10831093
10841094When 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 conclude the task once a budget is reached.
10851095
1086This 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](https://platform.claude.com/docs/en/build-with-claude/compaction-threshold#trigger-configuration) with `pause_after_compaction` from [Pausing after compaction](https://platform.claude.com/docs/en/build-with-claude/compaction-threshold#pausing-after-compaction).
1087
1088<CodeGroup exclude="shell">
1096The request combines the `trigger` from [Trigger configuration](https://platform.claude.com/docs/en/build-with-claude/compaction-threshold#trigger-configuration) with `pause_after_compaction` from [Pausing after compaction](https://platform.claude.com/docs/en/build-with-claude/compaction-threshold#pausing-after-compaction).
1097
1098<CodeGroup exclude="shell:cURL, shell:CLI">
1099 <CodeGroupItem language="cURL">
1100 This workflow needs more logic than a single shell command. Use the Anthropic SDK to run it.
1101 </CodeGroupItem>
1102
1103 <CodeGroupItem language="CLI">
1104 This workflow needs more logic than a single shell command. Use the Anthropic SDK to run it.
1105 </CodeGroupItem>
1106
10891107 ```python Python
10901108 client = anthropic.Anthropic()
1091 messages = [{"role": "user", "content": "Hello, Claude"}]
1109 messages = [{"role": "user", "content": "Help me build a website"}]
10921110 TRIGGER_THRESHOLD = 100_000
10931111 TOTAL_TOKEN_BUDGET = 3_000_000
10941112 n_compactions = 0
from line 1144
11261144 ```typescript TypeScript
11271145 const client = new Anthropic();
11281146 const messages: Anthropic.Beta.Messages.BetaMessageParam[] = [
1129 { role: "user", content: "Hello, Claude" }
1147 { role: "user", content: "Help me build a website" }
11301148 ];
11311149 const TRIGGER_THRESHOLD = 100_000;
11321150 const TOTAL_TOKEN_BUDGET = 3_000_000;
from line 1182
11641182
11651183 ```csharp C#
11661184 AnthropicClient client = new();
1167 List<BetaMessageParam> messages = [new BetaUserMessageParam { Content = "Hello, Claude" }];
1185 List<BetaMessageParam> messages = [new BetaUserMessageParam { Content = "Help me build a website" }];
11681186
11691187 const int TriggerThreshold = 100_000;
11701188 const int TotalTokenBudget = 3_000_000;
from line 1227
12091227
12101228 ```go Go
12111229 client := anthropic.NewClient()
1212 messages := []anthropic.BetaMessageParam{anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello, Claude"))}
1230 messages := []anthropic.BetaMessageParam{anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Help me build a website"))}
12131231
12141232 const triggerThreshold = 100_000
12151233 const totalTokenBudget = 3_000_000
from line 1270
12521270 import com.anthropic.models.beta.messages.BetaInputTokensTrigger;
12531271 import com.anthropic.models.beta.messages.BetaStopReason;
12541272 // ...
1255 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
1256
1257 long triggerThreshold = 100_000;
1258 long totalTokenBudget = 3_000_000;
1259 int compactionCount = 0;
1260
1261 List<BetaMessageParam> messages = new ArrayList<>();
1262 messages.add(BetaMessageParam.ofUser("Hello, Claude"));
1263
1264 MessageCreateParams params = MessageCreateParams.builder()
1265 .addBeta("compact-2026-01-12")
1266 .model(Model.CLAUDE_OPUS_5_5)
1267 .maxTokens(4096L)
1268 .messages(messages)
1269 .contextManagement(BetaContextManagementConfig.builder()
1270 .addEdit(BetaCompact20260112Edit.builder()
1271 .trigger(BetaInputTokensTrigger.builder()
1272 .value(triggerThreshold)
1273 .build())
1274 .pauseAfterCompaction(true)
1273
1274 void main() {
1275 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
1276
1277 long triggerThreshold = 100_000;
1278 long totalTokenBudget = 3_000_000;
1279 int compactionCount = 0;
1280
1281 List<BetaMessageParam> messages = new ArrayList<>();
1282 messages.add(BetaMessageParam.ofUser("Help me build a website"));
1283
1284 MessageCreateParams params = MessageCreateParams.builder()
1285 .addBeta("compact-2026-01-12")
1286 .model(Model.CLAUDE_OPUS_5_5)
1287 .maxTokens(4096L)
1288 .messages(messages)
1289 .contextManagement(BetaContextManagementConfig.builder()
1290 .addEdit(BetaCompact20260112Edit.builder()
1291 .trigger(BetaInputTokensTrigger.builder()
1292 .value(triggerThreshold)
12751293 .build())
1294 .pauseAfterCompaction(true)
12761295 .build())
1277 .build();
1278
1279 BetaMessage response = client.beta().messages().create(params);
1280
1281 if (response.stopReason().isPresent()
1282 && response.stopReason().get().equals(BetaStopReason.COMPACTION)) {
1283 compactionCount += 1;
1284 messages.add(response.toParam());
1285
1286 // Estimate total tokens consumed; prompt wrap-up if over budget
1287 if (compactionCount * triggerThreshold >= totalTokenBudget) {
1288 messages.add(BetaMessageParam.ofUser(
1289 "Please wrap up your current work and summarize the final state."));
1290 }
1296 .build())
1297 .build();
1298
1299 BetaMessage response = client.beta().messages().create(params);
1300
1301 if (response.stopReason().isPresent()
1302 && response.stopReason().get().equals(BetaStopReason.COMPACTION)) {
1303 compactionCount += 1;
1304 messages.add(response.toParam());
1305
1306 // Estimate total tokens consumed; prompt wrap-up if over budget
1307 if (compactionCount * triggerThreshold >= totalTokenBudget) {
1308 messages.add(BetaMessageParam.ofUser(
1309 "Please wrap up your current work and summarize the final state."));
12911310 }
1292
1293 System.out.println(response);
1311 }
1312
1313 System.out.println(response);
1314 }
12941315 ```
12951316
12961317 ```php PHP
from line 1321
13001321 $totalTokenBudget = 3_000_000;
13011322 $compactionCount = 0;
13021323
1303 $messages = [['role' => 'user', 'content' => 'Hello, Claude']];
1324 $messages = [['role' => 'user', 'content' => 'Help me build a website']];
13041325
13051326 $response = $client->beta->messages->create(
13061327 maxTokens: 4096,
13071328 messages: $messages,
1308 model: 'claude-opus-5-5',
1329 model: Model::CLAUDE_OPUS_5_5,
13091330 betas: ['compact-2026-01-12'],
13101331 contextManagement: [
13111332 'edits' => [
from line 1355
13341355
13351356 ```ruby Ruby
13361357 client = Anthropic::Client.new
1337 messages = [{ role: "user", content: "Hello, Claude" }]
1358 messages = [{ role: "user", content: "Help me build a website" }]
13381359 TRIGGER_THRESHOLD = 100_000
13391360 TOTAL_TOKEN_BUDGET = 3_000_000
13401361 compaction_count = 0
from line 1418
13971418
13981419<CodeGroup exclude="shell:cURL, shell:CLI">
13991420 <CodeGroupItem language="cURL">
1400 This workflow needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
1421 This workflow needs more logic than a single shell command. Use the [Anthropic SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
14011422 </CodeGroupItem>
14021423
14031424 <CodeGroupItem language="CLI">
1404 This workflow needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
1425 This workflow needs more logic than a single shell command. Use the [Anthropic SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
14051426 </CodeGroupItem>
14061427
1407 ```python Python
1408 client = anthropic.Anthropic()
1409 messages = [{"role": "user", "content": "Hello, Claude"}]
1410 response = client.beta.messages.create(
1411 betas=["compact-2026-01-12"],
1412 model="claude-opus-5-5",
1413 max_tokens=4096,
1414 messages=messages,
1415 context_management={"edits": [{"type": "compact_20260112"}]},
1416 )
1417 # After receiving a response with a compaction block
1418 messages.append({"role": "assistant", "content": response.content})
1419
1420 # Continue the conversation
1421 messages.append({"role": "user", "content": "Now add error handling"})
1422
1423 response = client.beta.messages.create(
1424 betas=["compact-2026-01-12"],
1425 model="claude-opus-5-5",
1426 max_tokens=4096,
1427 messages=messages,
1428 context_management={"edits": [{"type": "compact_20260112"}]},
1429 )
1430 ```
1428 <CodeGroupItem>
1429 ```python Python
1430 client = anthropic.Anthropic()
1431 messages = [{"role": "user", "content": "Help me build a website"}]
1432 response = client.beta.messages.create(
1433 betas=["compact-2026-01-12"],
1434 model="claude-opus-5-5",
1435 max_tokens=4096,
1436 messages=messages,
1437 context_management={"edits": [{"type": "compact_20260112"}]},
1438 )
1439 # After receiving a response with a compaction block
1440 messages.append({"role": "assistant", "content": response.content})
1441
1442 # Continue the conversation
1443 messages.append({"role": "user", "content": "Now add error handling"})
1444
1445 response = client.beta.messages.create(
1446 betas=["compact-2026-01-12"],
1447 model="claude-opus-5-5",
1448 max_tokens=4096,
1449 messages=messages,
1450 context_management={"edits": [{"type": "compact_20260112"}]},
1451 )
1452 ```
1453
1454 In Python, use `client.beta.messages`, as the samples on this page do. If you call `client.messages` and serialize blocks yourself, a plain `model_dump()` adds `text: null` and `citations: null` to the `compaction` block. The API then rejects the request with a 400 error (`Extra inputs are not permitted`). Use `to_dict()` or `model_dump(exclude_none=True)` instead.
1455 </CodeGroupItem>
14311456
14321457 ```typescript TypeScript
14331458 const client = new Anthropic();
14341459 const messages: Anthropic.Beta.Messages.BetaMessageParam[] = [
1435 { role: "user", content: "Hello, Claude" }
1460 { role: "user", content: "Help me build a website" }
14361461 ];
14371462
14381463 const response = await client.beta.messages.create({
from line 1578
15531578 import com.anthropic.models.beta.messages.BetaContextManagementConfig;
15541579 import com.anthropic.models.beta.messages.BetaCompact20260112Edit;
15551580 // ...
1556 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
1557
1558 // First request
1559 BetaMessage response = client.beta().messages().create(
1560 MessageCreateParams.builder()
1561 .addBeta("compact-2026-01-12")
1562 .model(Model.CLAUDE_OPUS_5_5)
1563 .maxTokens(4096L)
1564 .addUserMessage("Help me build a web scraper")
1565 .contextManagement(BetaContextManagementConfig.builder()
1566 .addEdit(BetaCompact20260112Edit.builder().build())
1567 .build())
1568 .build());
1569
1570 // After receiving a response with a compaction block, append the full
1571 // content (including compaction blocks) and continue the conversation
1572 BetaMessage nextResponse = client.beta().messages().create(
1573 MessageCreateParams.builder()
1574 .addBeta("compact-2026-01-12")
1575 .model(Model.CLAUDE_OPUS_5_5)
1576 .maxTokens(4096L)
1577 .addUserMessage("Help me build a web scraper")
1578 .addMessage(response)
1579 .addUserMessage("Now add error handling")
1580 .contextManagement(BetaContextManagementConfig.builder()
1581 .addEdit(BetaCompact20260112Edit.builder().build())
1582 .build())
1583 .build());
1584
1585 System.out.println(nextResponse);
1581
1582 void main() {
1583 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
1584
1585 // First request
1586 BetaMessage response = client.beta().messages().create(
1587 MessageCreateParams.builder()
1588 .addBeta("compact-2026-01-12")
1589 .model(Model.CLAUDE_OPUS_5_5)
1590 .maxTokens(4096L)
1591 .addUserMessage("Help me build a web scraper")
1592 .contextManagement(BetaContextManagementConfig.builder()
1593 .addEdit(BetaCompact20260112Edit.builder().build())
1594 .build())
1595 .build());
1596
1597 // After receiving a response with a compaction block, append the full
1598 // content (including compaction blocks) and continue the conversation
1599 BetaMessage nextResponse = client.beta().messages().create(
1600 MessageCreateParams.builder()
1601 .addBeta("compact-2026-01-12")
1602 .model(Model.CLAUDE_OPUS_5_5)
1603 .maxTokens(4096L)
1604 .addUserMessage("Help me build a web scraper")
1605 .addMessage(response)
1606 .addUserMessage("Now add error handling")
1607 .contextManagement(BetaContextManagementConfig.builder()
1608 .addEdit(BetaCompact20260112Edit.builder().build())
1609 .build())
1610 .build());
1611
1612 System.out.println(nextResponse);
1613 }
15861614 ```
15871615
15881616 ```php PHP
from line 1623
15951623 $response = $client->beta->messages->create(
15961624 maxTokens: 4096,
15971625 messages: $messages,
1598 model: 'claude-opus-5-5',
1626 model: Model::CLAUDE_OPUS_5_5,
15991627 betas: ['compact-2026-01-12'],
16001628 contextManagement: [
16011629 'edits' => [['type' => 'compact_20260112']]
from line 1637
16091637 $nextResponse = $client->beta->messages->create(
16101638 maxTokens: 4096,
16111639 messages: $messages,
1612 model: 'claude-opus-5-5',
1640 model: Model::CLAUDE_OPUS_5_5,
16131641 betas: ['compact-2026-01-12'],
16141642 contextManagement: [
16151643 'edits' => [['type' => 'compact_20260112']]
from line 1681
16531681 puts next_response.content
16541682 ```
16551683</CodeGroup>
1656
1657In Python, use `client.beta.messages`, as the samples on this page do. If you call `client.messages` and serialize blocks yourself, a plain `model_dump()` adds `text: null` and `citations: null` to the `compaction` block. The API then rejects the request with a 400 error (`Extra inputs are not permitted`). Use `to_dict()` or `model_dump(exclude_none=True)` instead. [Continue from the summary](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand#continue-from-the-summary) gives the same advice for on-demand compaction.
16581684
16591685When the API receives a `compaction` block, all content blocks before it are ignored. You can either:
16601686
from line 1709
16831709 "messages": [
16841710 {
16851711 "role": "user",
1686 "content": "Hello, Claude"
1712 "content": "Help me build a website"
16871713 }
16881714 ],
16891715 "context_management": {
from line 1731
17051731 max_tokens: 4096
17061732 messages:
17071733 - role: user
1708 content: Hello, Claude
1734 content: Help me build a website
17091735 context_management:
17101736 edits:
17111737 - type: compact_20260112
from line 1740
17141740
17151741 ```python Python
17161742 client = anthropic.Anthropic()
1717 messages = [{"role": "user", "content": "Hello, Claude"}]
1743 messages = [{"role": "user", "content": "Help me build a website"}]
17181744
17191745 with client.beta.messages.stream(
17201746 betas=["compact-2026-01-12"],
from line 1775
17491775 ```typescript TypeScript
17501776 const client = new Anthropic();
17511777 const messages: Anthropic.Beta.Messages.BetaMessageParam[] = [
1752 { role: "user", content: "Hello, Claude" }
1778 { role: "user", content: "Help me build a website" }
17531779 ];
17541780
17551781 const stream = await client.beta.messages.stream({
from line 1823
17971823
17981824 ```csharp C#
17991825 var client = new AnthropicClient();
1800 List<BetaMessageParam> messages = [new BetaUserMessageParam { Content = "Hello" }];
1826 List<BetaMessageParam> messages = [new BetaUserMessageParam { Content = "Help me build a website" }];
18011827
18021828 var parameters = new MessageCreateParams
18031829 {
from line 1866
18401866
18411867 ```go Go
18421868 client := anthropic.NewClient()
1843 messages := []anthropic.BetaMessageParam{anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello, Claude"))}
1869 messages := []anthropic.BetaMessageParam{anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Help me build a website"))}
18441870
18451871 stream := client.Beta.Messages.NewStreaming(context.TODO(), anthropic.BetaMessageNewParams{
18461872 Model: anthropic.ModelClaudeOpus5_5,
from line 1908
18821908 import com.anthropic.models.beta.messages.BetaContextManagementConfig;
18831909 import com.anthropic.models.beta.messages.BetaCompact20260112Edit;
18841910 // ...
1885 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
1886
1887 MessageCreateParams params = MessageCreateParams.builder()
1888 .model(Model.CLAUDE_OPUS_5_5)
1889 .maxTokens(4096L)
1890 .addBeta("compact-2026-01-12")
1891 .addUserMessage("Hello, Claude")
1892 .contextManagement(BetaContextManagementConfig.builder()
1893 .addEdit(BetaCompact20260112Edit.builder().build())
1894 .build())
1895 .build();
1896
1897 try (var streamResponse = client.beta().messages().createStreaming(params)) {
1898 streamResponse.stream().forEach(event -> {
1899 event.contentBlockStart().ifPresent(startEvent -> {
1900 startEvent.contentBlock().compaction().ifPresent(compactionBlock ->
1901 System.out.println("Compaction started...")
1902 );
1903 startEvent.contentBlock().text().ifPresent(textBlock ->
1904 System.out.println("Text response started...")
1905 );
1906 });
1907
1908 event.contentBlockDelta().ifPresent(deltaEvent -> {
1909 deltaEvent.delta().compaction().ifPresent(compactionDelta ->
1910 System.out.println("Compaction complete: " + compactionDelta.content().map(String::length).orElse(0) + " chars")
1911 );
1912 deltaEvent.delta().text().ifPresent(textDelta ->
1913 System.out.print(textDelta.text())
1914 );
1915 });
1916 });
1917 }
1911
1912 void main() {
1913 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
1914
1915 MessageCreateParams params = MessageCreateParams.builder()
1916 .model(Model.CLAUDE_OPUS_5_5)
1917 .maxTokens(4096L)
1918 .addBeta("compact-2026-01-12")
1919 .addUserMessage("Help me build a website")
1920 .contextManagement(BetaContextManagementConfig.builder()
1921 .addEdit(BetaCompact20260112Edit.builder().build())
1922 .build())
1923 .build();
1924
1925 try (var streamResponse = client.beta().messages().createStreaming(params)) {
1926 streamResponse.stream().forEach(event -> {
1927 switch (event.type().value()) {
1928 case CONTENT_BLOCK_START -> {
1929 var block = event.asContentBlockStart().contentBlock();
1930 switch (block.type().value()) {
1931 case COMPACTION -> System.out.println("Compaction started...");
1932 case TEXT -> System.out.println("Text response started...");
1933 default -> {}
1934 }
1935 }
1936 case CONTENT_BLOCK_DELTA -> {
1937 var delta = event.asContentBlockDelta().delta();
1938 switch (delta.type().value()) {
1939 case COMPACTION_DELTA -> System.out.println("Compaction complete: " + delta.asCompaction().content().map(String::length).orElse(0) + " chars");
1940 case TEXT_DELTA -> System.out.print(delta.asText().text());
1941 default -> {}
1942 }
1943 }
1944 default -> {}
1945 }
1946 });
1947 }
1948 }
19181949 ```
19191950
19201951 ```php PHP
from line 1958
19271958 use Anthropic\Messages\Model;
19281959
19291960 $client = new Client();
1930 $messages = [['role' => 'user', 'content' => 'Hello, Claude']];
1961 $messages = [['role' => 'user', 'content' => 'Help me build a website']];
19311962
19321963 $stream = $client->beta->messages->createStream(
19331964 maxTokens: 4096,
from line 2000
19692000
19702001 ```ruby Ruby
19712002 client = Anthropic::Client.new
1972 messages = [{ role: "user", content: "Hello, Claude" }]
2003 messages = [{ role: "user", content: "Help me build a website" }]
19732004
19742005 stream = client.beta.messages.stream(
19752006 betas: ["compact-2026-01-12"],
from line 2086
20552086 "messages": [
20562087 {
20572088 "role": "user",
2058 "content": "Hello, Claude"
2089 "content": "Help me build a website"
20592090 }
20602091 ],
20612092 "context_management": {
from line 2110
20792110 type: ephemeral
20802111 messages:
20812112 - role: user
2082 content: Hello, Claude
2113 content: Help me build a website
20832114 context_management:
20842115 edits:
20852116 - type: compact_20260112
from line 2119
20882119
20892120 ```python Python
20902121 client = anthropic.Anthropic()
2091 messages = [{"role": "user", "content": "Hello, Claude"}]
2122 messages = [{"role": "user", "content": "Help me build a website"}]
20922123 response = client.beta.messages.create(
20932124 betas=["compact-2026-01-12"],
20942125 model="claude-opus-5-5",
from line 2141
21102141 ```typescript TypeScript
21112142 const client = new Anthropic();
21122143 const messages: Anthropic.Beta.Messages.BetaMessageParam[] = [
2113 { role: "user", content: "Hello, Claude" }
2144 { role: "user", content: "Help me build a website" }
21142145 ];
21152146
21162147 const response = await client.beta.messages.create({
from line 2178
21472178 CacheControl = new BetaCacheControlEphemeral()
21482179 }
21492180 },
2150 Messages = [new BetaUserMessageParam { Content = "Hello, Claude" }],
2181 Messages = [new BetaUserMessageParam { Content = "Help me build a website" }],
21512182 ContextManagement = new BetaContextManagementConfig
21522183 {
21532184 Edits = [new BetaCompact20260112Edit()]
from line 2201
21702201 CacheControl: anthropic.NewBetaCacheControlEphemeralParam(),
21712202 },
21722203 },
2173 Messages: []anthropic.BetaMessageParam{anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello, Claude"))},
2204 Messages: []anthropic.BetaMessageParam{anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Help me build a website"))},
21742205 ContextManagement: anthropic.BetaContextManagementConfigParam{
21752206 Edits: []anthropic.BetaContextManagementConfigEditUnionParam{
21762207 {OfCompact20260112: &anthropic.BetaCompact20260112EditParam{}},
from line 2220
21892220 import com.anthropic.models.beta.messages.BetaCompact20260112Edit;
21902221 import com.anthropic.models.beta.messages.BetaCacheControlEphemeral;
21912222 // ...
2192 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
2193
2194 MessageCreateParams params = MessageCreateParams.builder()
2195 .model(Model.CLAUDE_OPUS_5_5)
2196 .maxTokens(4096L)
2197 .addBeta("compact-2026-01-12")
2198 .systemOfBetaTextBlockParams(List.of(
2199 BetaTextBlockParam.builder()
2200 .text("You are a helpful coding assistant...")
2201 .cacheControl(BetaCacheControlEphemeral.builder().build())
2202 .build()
2203 ))
2204 .addUserMessage("Hello, Claude")
2205 .contextManagement(BetaContextManagementConfig.builder()
2206 .addEdit(BetaCompact20260112Edit.builder().build())
2207 .build())
2208 .build();
2209
2210 BetaMessage response = client.beta().messages().create(params);
2211 System.out.println(response);
2223
2224 void main() {
2225 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
2226
2227 MessageCreateParams params = MessageCreateParams.builder()
2228 .model(Model.CLAUDE_OPUS_5_5)
2229 .maxTokens(4096L)
2230 .addBeta("compact-2026-01-12")
2231 .systemOfBetaTextBlockParams(List.of(
2232 BetaTextBlockParam.builder()
2233 .text("You are a helpful coding assistant...")
2234 .cacheControl(BetaCacheControlEphemeral.builder().build())
2235 .build()
2236 ))
2237 .addUserMessage("Help me build a website")
2238 .contextManagement(BetaContextManagementConfig.builder()
2239 .addEdit(BetaCompact20260112Edit.builder().build())
2240 .build())
2241 .build();
2242
2243 BetaMessage response = client.beta().messages().create(params);
2244 System.out.println(response);
2245 }
22122246 ```
22132247
22142248 ```php PHP
from line 2250
22162250
22172251 $response = $client->beta->messages->create(
22182252 maxTokens: 4096,
2219 messages: [['role' => 'user', 'content' => 'Hello, Claude']],
2253 messages: [['role' => 'user', 'content' => 'Help me build a website']],
22202254 model: Model::CLAUDE_OPUS_5_5,
22212255 betas: ['compact-2026-01-12'],
22222256 system: [
from line 2288
22542288 }
22552289 }
22562290 ],
2257 messages: [{ role: "user", content: "Hello, Claude" }],
2291 messages: [{ role: "user", content: "Help me build a website" }],
22582292 context_management: {
22592293 edits: [{ type: "compact_20260112" }]
22602294 }
from line 2329
22952329<Note>
22962330 The top-level `input_tokens` and `output_tokens` do not include compaction iteration usage. They reflect the sum of all non-compaction iterations. To calculate total tokens consumed and billed for a request, sum across all entries in the `usage.iterations` array.
22972331
2298 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.
2332 To track cost or audit usage when compaction is enabled, aggregate across `usage.iterations` instead of reading only `usage.input_tokens` and `usage.output_tokens`. 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.
22992333</Note>
23002334
23012335## Combining with other features
from line 2354
23202354 "messages": [
23212355 {
23222356 "role": "user",
2323 "content": "Hello, Claude"
2357 "content": "Help me build a website"
23242358 }
23252359 ],
23262360 "context_management": {
from line 2372
23382372 model: claude-opus-5-5
23392373 messages:
23402374 - role: user
2341 content: Hello, Claude
2375 content: Help me build a website
23422376 context_management:
23432377 edits:
23442378 - type: compact_20260112
from line 2381
23472381
23482382 ```python Python
23492383 client = anthropic.Anthropic()
2350 messages = [{"role": "user", "content": "Hello, Claude"}]
2384 messages = [{"role": "user", "content": "Help me build a website"}]
23512385 count_response = client.beta.messages.count_tokens(
23522386 betas=["compact-2026-01-12"],
23532387 model="claude-opus-5-5",
from line 2414
23802414
23812415 ```csharp C#
23822416 AnthropicClient client = new();
2383 List<BetaMessageParam> messages = [new BetaUserMessageParam { Content = "Hello" }];
2417 List<BetaMessageParam> messages = [new BetaUserMessageParam { Content = "Help me build a website" }];
23842418
23852419 var countParams = new MessageCountTokensParams
23862420 {
from line 2434
24002434
24012435 ```go Go
24022436 client := anthropic.NewClient()
2403 messages := []anthropic.BetaMessageParam{anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello, Claude"))}
2437 messages := []anthropic.BetaMessageParam{anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Help me build a website"))}
24042438
24052439 countResponse, err := client.Beta.Messages.CountTokens(context.TODO(), anthropic.BetaMessageCountTokensParams{
24062440 Model: anthropic.ModelClaudeOpus5_5,
from line 2460
24262460 import com.anthropic.models.beta.messages.BetaContextManagementConfig;
24272461 import com.anthropic.models.beta.messages.BetaCompact20260112Edit;
24282462 // ...
2429 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
2430
2431 MessageCountTokensParams params = MessageCountTokensParams.builder()
2432 .model(Model.CLAUDE_OPUS_5_5)
2433 .addUserMessage("Hello, Claude")
2434 .contextManagement(BetaContextManagementConfig.builder()
2435 .addEdit(BetaCompact20260112Edit.builder().build())
2436 .build())
2437 .addBeta("compact-2026-01-12")
2438 .build();
2439
2440 BetaMessageTokensCount countResponse = client.beta().messages().countTokens(params);
2441 System.out.println("Current tokens: " + countResponse.inputTokens());
2442 System.out.println("Original tokens: " + countResponse.contextManagement().get().originalInputTokens());
2463
2464 void main() {
2465 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
2466
2467 MessageCountTokensParams params = MessageCountTokensParams.builder()
2468 .model(Model.CLAUDE_OPUS_5_5)
2469 .addUserMessage("Help me build a website")
2470 .contextManagement(BetaContextManagementConfig.builder()
2471 .addEdit(BetaCompact20260112Edit.builder().build())
2472 .build())
2473 .addBeta("compact-2026-01-12")
2474 .build();
2475
2476 BetaMessageTokensCount countResponse = client.beta().messages().countTokens(params);
2477 System.out.println("Current tokens: " + countResponse.inputTokens());
2478 System.out.println("Original tokens: " + countResponse.contextManagement().get().originalInputTokens());
2479 }
24432480 ```
24442481
24452482 ```php PHP
24462483 $client = new Client();
2447 $messages = [['role' => 'user', 'content' => 'Hello, Claude']];
2484 $messages = [['role' => 'user', 'content' => 'Help me build a website']];
24482485
24492486 $countResponse = $client->beta->messages->countTokens(
24502487 messages: $messages,
2451 model: 'claude-opus-5-5',
2488 model: Model::CLAUDE_OPUS_5_5,
24522489 betas: ['compact-2026-01-12'],
24532490 contextManagement: [
24542491 'edits' => [
from line 2500
24632500
24642501 ```ruby Ruby
24652502 client = Anthropic::Client.new
2466 messages = [{ role: "user", content: "Hello, Claude" }]
2503 messages = [{ role: "user", content: "Help me build a website" }]
24672504
24682505 count_response = client.beta.messages.count_tokens(
24692506 betas: ["compact-2026-01-12"],
from line 2522
24852522
24862523<CodeGroup exclude="shell:cURL, shell:CLI">
24872524 <CodeGroupItem language="cURL">
2488 This workflow needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
2525 This workflow needs more logic than a single shell command. Use the [Anthropic SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
24892526 </CodeGroupItem>
24902527
24912528 <CodeGroupItem language="CLI">
2492 This workflow needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
2529 This workflow needs more logic than a single shell command. Use the [Anthropic SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
24932530 </CodeGroupItem>
24942531
24952532 ```python Python
from line 2705
26682705 import com.anthropic.models.beta.messages.BetaCompact20260112Edit;
26692706 import com.anthropic.models.beta.messages.BetaInputTokensTrigger;
26702707 // ...
2671 private static final AnthropicClient client = AnthropicOkHttpClient.fromEnv();
2672 private static final List<BetaMessageParam> messages = new ArrayList<>();
2673
2674 public static void main(String[] args) {
2675 System.out.println(chat("Briefly, help me build a Python web scraper"));
2676 System.out.println(chat("Briefly, add support for JavaScript-rendered pages"));
2677 System.out.println(chat("Briefly, add rate limiting and error handling"));
2678 }
2679
2680 private static String chat(String userMessage) {
2681 messages.add(BetaMessageParam.ofUser(userMessage));
2682
2683 MessageCreateParams params = MessageCreateParams.builder()
2684 .addBeta("compact-2026-01-12")
2685 .model(Model.CLAUDE_OPUS_5_5)
2686 .maxTokens(4096L)
2687 .messages(messages)
2688 .contextManagement(BetaContextManagementConfig.builder()
2689 .addEdit(BetaCompact20260112Edit.builder()
2690 .trigger(BetaInputTokensTrigger.builder()
2691 .value(100000L)
2692 .build())
2708 final AnthropicClient client = AnthropicOkHttpClient.fromEnv();
2709 final List<BetaMessageParam> messages = new ArrayList<>();
2710
2711 void main() {
2712 System.out.println(chat("Briefly, help me build a Python web scraper"));
2713 System.out.println(chat("Briefly, add support for JavaScript-rendered pages"));
2714 System.out.println(chat("Briefly, add rate limiting and error handling"));
2715 }
2716
2717 String chat(String userMessage) {
2718 messages.add(BetaMessageParam.ofUser(userMessage));
2719
2720 MessageCreateParams params = MessageCreateParams.builder()
2721 .addBeta("compact-2026-01-12")
2722 .model(Model.CLAUDE_OPUS_5_5)
2723 .maxTokens(4096L)
2724 .messages(messages)
2725 .contextManagement(BetaContextManagementConfig.builder()
2726 .addEdit(BetaCompact20260112Edit.builder()
2727 .trigger(BetaInputTokensTrigger.builder()
2728 .value(100000L)
26932729 .build())
26942730 .build())
2695 .build();
2696
2697 BetaMessage response = client.beta().messages().create(params);
2698
2699 // Append response (compaction blocks are automatically included)
2700 messages.add(response.toParam());
2701
2702 return response.content().stream()
2703 .filter(block -> block.text().isPresent())
2704 .map(block -> block.text().get().text())
2705 .findFirst()
2706 .orElse("");
2707 }
2731 .build())
2732 .build();
2733
2734 BetaMessage response = client.beta().messages().create(params);
2735
2736 // Append response (compaction blocks are automatically included)
2737 messages.add(response.toParam());
2738
2739 return response.content().stream()
2740 .flatMap(block -> block.text().stream())
2741 .map(textBlock -> textBlock.text())
2742 .findFirst()
2743 .orElse("");
2744 }
27082745 ```
27092746
27102747 ```php PHP
from line 2755
27182755 $response = $client->beta->messages->create(
27192756 maxTokens: 4096,
27202757 messages: $messages,
2721 model: 'claude-opus-5-5',
2758 model: Model::CLAUDE_OPUS_5_5,
27222759 betas: ['compact-2026-01-12'],
27232760 contextManagement: [
27242761 'edits' => [
from line 2770
27332770 $messages[] = ['role' => 'assistant', 'content' => $response->content];
27342771
27352772 foreach ($response->content as $block) {
2736 if ($block->type === 'text') {
2773 if ($block instanceof \Anthropic\Beta\Messages\BetaTextBlock) {
27372774 return $block->text;
27382775 }
27392776 }
from line 2815
27782815 ```
27792816</CodeGroup>
27802817
2781On Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5, thinking blocks in any assistant turn you reinsert after the compaction block fail the [prefix check](https://platform.claude.com/docs/en/build-with-claude/thinking#preserved-in-conversation), because they were produced when the full history was present. Strip the `thinking` and `redacted_thinking` blocks from those turns. Alternatively, send `thinking.block_binding.prefix_mismatch_behavior: "drop_block"` with the `thinking-binding-controls-2026-08-01` [beta header](https://platform.claude.com/docs/en/api/beta-headers). The preserved text and tool blocks can stay as they are. Letting the API summarize everything, without reinserting earlier turns, avoids this. On Claude Sonnet 5.5 and Claude Haiku 5.5, `block_binding` works only with `thinking: {"type": "adaptive"}`. With any other thinking setting on those models, strip the blocks.
2818When you reinsert an earlier assistant turn after the compaction block, that turn’s thinking blocks fail the [prefix check](https://platform.claude.com/docs/en/build-with-claude/thinking#preserved-in-conversation) on some models. Those models are Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5. The blocks fail because they were produced when the full history was present.
2819
2820To avoid the failure, do one of the following:
2821
2822* **Strip the blocks:** Remove the `thinking` and `redacted_thinking` blocks from the turns you reinsert. The preserved text and tool blocks can stay as they are.
2823* **Have the API drop the blocks:** Send `thinking.block_binding.prefix_mismatch_behavior: "drop_block"`. This needs the `thinking-binding-controls-2026-08-01` beta header (see [Beta headers](https://platform.claude.com/docs/en/api/beta-headers)).
2824* **Don’t reinsert earlier turns:** Let the API summarize everything.
2825
2826On Claude Sonnet 5.5 and Claude Haiku 5.5, `block_binding` works only with `thinking: {"type": "adaptive"}`. With any other thinking setting on those two models, strip the blocks.
27822827
27832828Here’s an example that uses `pause_after_compaction` to preserve the prior exchange and the current user message (three messages total) instead of summarizing them. It keeps their text and tool blocks unchanged, removes the `thinking` and `redacted_thinking` blocks from the preserved assistant turn, and drops that turn if nothing else is left:
27842829
27852830<CodeGroup exclude="shell:cURL, shell:CLI">
27862831 <CodeGroupItem language="cURL">
2787 This workflow needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
2832 This workflow needs more logic than a single shell command. Use the [Anthropic SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
27882833 </CodeGroupItem>
27892834
27902835 <CodeGroupItem language="CLI">
2791 This workflow needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
2836 This workflow needs more logic than a single shell command. Use the [Anthropic SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
27922837 </CodeGroupItem>
27932838
27942839 ```python Python
from line 2887
28422887 else message
28432888 for message in messages[-3:]
28442889 ]
2845 preserved_messages = [m for m in preserved_messages if m["content"]]
2890 preserved_messages = [
2891 message for message in preserved_messages if message["content"]
2892 ]
28462893
28472894 # Build new message list: compaction + preserved messages
28482895 new_assistant_content = [compaction_block]
from line 3225
31783225 import com.anthropic.models.beta.messages.BetaCompact20260112Edit;
31793226 import com.anthropic.models.beta.messages.BetaInputTokensTrigger;
31803227 // ...
3181 private static final AnthropicClient client = AnthropicOkHttpClient.fromEnv();
3182 private static final List<BetaMessageParam> messages = new ArrayList<>();
3183
3184 public static String chat(String userMessage) {
3185 messages.add(BetaMessageParam.ofUser(userMessage));
3186
3187 MessageCreateParams params = MessageCreateParams.builder()
3228 final AnthropicClient client = AnthropicOkHttpClient.fromEnv();
3229 final List<BetaMessageParam> messages = new ArrayList<>();
3230
3231 String chat(String userMessage) {
3232 messages.add(BetaMessageParam.ofUser(userMessage));
3233
3234 MessageCreateParams params = MessageCreateParams.builder()
3235 .addBeta("compact-2026-01-12")
3236 .model(Model.CLAUDE_OPUS_5_5)
3237 .maxTokens(4096L)
3238 .messages(messages)
3239 .contextManagement(BetaContextManagementConfig.builder()
3240 .addEdit(BetaCompact20260112Edit.builder()
3241 .trigger(BetaInputTokensTrigger.builder()
3242 .value(100000L)
3243 .build())
3244 .pauseAfterCompaction(true)
3245 .build())
3246 .build())
3247 .build();
3248
3249 BetaMessage response = client.beta().messages().create(params);
3250
3251 // Look for the compaction block, not the stop reason:
3252 // stopReason() is REFUSAL, not COMPACTION, if the summary was blocked
3253 var compactionBlock = response.content().stream()
3254 .flatMap(block -> block.compaction().stream())
3255 .findFirst();
3256
3257 // Replace the history only if a summary was generated
3258 if (compactionBlock.flatMap(block -> block.content()).isPresent()) {
3259 // Preserve the prior exchange + current user message (3 messages),
3260 // without thinking blocks; an assistant turn left empty is dropped
3261 List<BetaMessageParam> preservedMessages = new ArrayList<>();
3262 for (BetaMessageParam message : messages.subList(Math.max(0, messages.size() - 3), messages.size())) {
3263 if (message.isAssistant() && message.asAssistant().content().isContentBlockParams()) {
3264 var keptBlocks = message.asAssistant().content().asContentBlockParams().stream()
3265 .filter(block -> !block.isThinking() && !block.isRedactedThinking())
3266 .toList();
3267 if (keptBlocks.isEmpty()) {
3268 continue;
3269 }
3270 message = BetaMessageParam.ofAssistantOfContentBlockParams(keptBlocks);
3271 }
3272 preservedMessages.add(message);
3273 }
3274
3275 // Build new message list: compaction + preserved messages
3276 List<BetaMessageParam> messagesAfterCompaction = new ArrayList<>();
3277 messagesAfterCompaction.add(response.toParam());
3278 messagesAfterCompaction.addAll(preservedMessages);
3279
3280 // Update the message list to reflect the compaction
3281 messages.clear();
3282 messages.addAll(messagesAfterCompaction);
3283 }
3284
3285 if (compactionBlock.isPresent()) {
3286 // Continue the request, with the full history if there is no summary
3287 MessageCreateParams continueParams = MessageCreateParams.builder()
31883288 .addBeta("compact-2026-01-12")
31893289 .model(Model.CLAUDE_OPUS_5_5)
31903290 .maxTokens(4096L)
31913291 .messages(messages)
31923292 .contextManagement(BetaContextManagementConfig.builder()
3193 .addEdit(BetaCompact20260112Edit.builder()
3194 .trigger(BetaInputTokensTrigger.builder()
3195 .value(100000L)
3196 .build())
3197 .pauseAfterCompaction(true)
3198 .build())
3293 .addEdit(BetaCompact20260112Edit.builder().build())
31993294 .build())
32003295 .build();
32013296
3202 BetaMessage response = client.beta().messages().create(params);
3203
3204 // Look for the compaction block, not the stop reason:
3205 // stopReason() is REFUSAL, not COMPACTION, if the summary was blocked
3206 var compactionBlock = response.content().stream()
3207 .flatMap(block -> block.compaction().stream())
3208 .findFirst();
3209
3210 // Replace the history only if a summary was generated
3211 if (compactionBlock.flatMap(block -> block.content()).isPresent()) {
3212 // Preserve the prior exchange + current user message (3 messages),
3213 // without thinking blocks; an assistant turn left empty is dropped
3214 List<BetaMessageParam> preservedMessages = new ArrayList<>();
3215 for (BetaMessageParam message : messages.subList(Math.max(0, messages.size() - 3), messages.size())) {
3216 if (message.isAssistant() && message.asAssistant().content().isContentBlockParams()) {
3217 var keptBlocks = message.asAssistant().content().asContentBlockParams().stream()
3218 .filter(block -> !block.isThinking() && !block.isRedactedThinking())
3219 .toList();
3220 if (keptBlocks.isEmpty()) {
3221 continue;
3222 }
3223 message = BetaMessageParam.ofAssistantOfContentBlockParams(keptBlocks);
3224 }
3225 preservedMessages.add(message);
3226 }
3227
3228 // Build new message list: compaction + preserved messages
3229 List<BetaMessageParam> messagesAfterCompaction = new ArrayList<>();
3230 messagesAfterCompaction.add(response.toParam());
3231 messagesAfterCompaction.addAll(preservedMessages);
3232
3233 // Update the message list to reflect the compaction
3234 messages.clear();
3235 messages.addAll(messagesAfterCompaction);
3236 }
3237
3238 if (compactionBlock.isPresent()) {
3239 // Continue the request, with the full history if there is no summary
3240 MessageCreateParams continueParams = MessageCreateParams.builder()
3241 .addBeta("compact-2026-01-12")
3242 .model(Model.CLAUDE_OPUS_5_5)
3243 .maxTokens(4096L)
3244 .messages(messages)
3245 .contextManagement(BetaContextManagementConfig.builder()
3246 .addEdit(BetaCompact20260112Edit.builder().build())
3247 .build())
3248 .build();
3249
3250 response = client.beta().messages().create(continueParams);
3251 }
3252
3253 // Append the final response
3254 messages.add(response.toParam());
3255
3256 return response.content().stream()
3257 .filter(block -> block.text().isPresent())
3258 .map(block -> block.text().get().text())
3259 .findFirst()
3260 .orElse("");
3261 }
3262
3263 public static void main(String[] args) {
3264 System.out.println(chat("Briefly, help me build a Python web scraper"));
3265 System.out.println(chat("Briefly, add support for JavaScript-rendered pages"));
3266 System.out.println(chat("Briefly, add rate limiting and error handling"));
3267 }
3297 response = client.beta().messages().create(continueParams);
3298 }
3299
3300 // Append the final response
3301 messages.add(response.toParam());
3302
3303 return response.content().stream()
3304 .flatMap(block -> block.text().stream())
3305 .map(textBlock -> textBlock.text())
3306 .findFirst()
3307 .orElse("");
3308 }
3309
3310 void main() {
3311 System.out.println(chat("Briefly, help me build a Python web scraper"));
3312 System.out.println(chat("Briefly, add support for JavaScript-rendered pages"));
3313 System.out.println(chat("Briefly, add rate limiting and error handling"));
3314 }
32683315 ```
32693316
32703317 ```php PHP
from line 3325
32783325 $response = $client->beta->messages->create(
32793326 maxTokens: 4096,
32803327 messages: $messages,
3281 model: 'claude-opus-5-5',
3328 model: Model::CLAUDE_OPUS_5_5,
32823329 betas: ['compact-2026-01-12'],
32833330 contextManagement: [
32843331 'edits' => [
from line 3375
33283375 $response = $client->beta->messages->create(
33293376 maxTokens: 4096,
33303377 messages: $messages,
3331 model: 'claude-opus-5-5',
3378 model: Model::CLAUDE_OPUS_5_5,
33323379 betas: ['compact-2026-01-12'],
33333380 contextManagement: [
33343381 'edits' => [['type' => 'compact_20260112']]
from line 3386
33393386 $messages[] = ['role' => 'assistant', 'content' => $response->content];
33403387
33413388 foreach ($response->content as $block) {
3342 if ($block->type === 'text') {
3389 if ($block instanceof \Anthropic\Beta\Messages\BetaTextBlock) {
33433390 return $block->text;
33443391 }
33453392 }
from line 3504
34573504* Availability: Available
34583505* Usage: Opt in with a `compact_20260112` edit in `context_management.edits`. Compaction starts when input tokens reach the trigger, 150,000 by default and at least 50,000.
34593506
3460| Status | Cloud platforms | Models |
3461| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
3462| Beta | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), [Amazon Bedrock (InvokeModel)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed), [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry) | [Claude Fable 5.2](https://platform.claude.com/docs/en/models/fable-5-2/overview), [Claude Mythos 5.2](https://platform.claude.com/docs/en/models/mythos-5-2/overview), [Claude Fable 5.1](https://platform.claude.com/docs/en/models/fable-5-1/overview), [Claude Mythos 5.1](https://platform.claude.com/docs/en/models/mythos-5-1/overview), [Claude Fable 5](https://platform.claude.com/docs/en/models/fable-5/overview), [Claude Mythos 5](https://platform.claude.com/docs/en/models/mythos-5/overview), Claude Mythos Preview, [Claude Opus 5.5](https://platform.claude.com/docs/en/models/opus-5-5/overview), [Claude Opus 5](https://platform.claude.com/docs/en/models/opus-5/overview), [Claude Sonnet 5.5](https://platform.claude.com/docs/en/models/sonnet-5-5/overview), [Claude Sonnet 5](https://platform.claude.com/docs/en/models/sonnet-5/overview), [Claude Haiku 5.5](https://platform.claude.com/docs/en/models/haiku-5-5/overview), [Claude Opus 4.8](https://platform.claude.com/docs/en/models/opus-4-8/overview), [Claude Opus 4.7](https://platform.claude.com/docs/en/models/opus-4-7/overview), [Claude Opus 4.6](https://platform.claude.com/docs/en/models/opus-4-6/overview), [Claude Sonnet 4.6](https://platform.claude.com/docs/en/models/sonnet-4-6/overview) |
3507| Status | Cloud platforms | Models |
3508| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
3509| Beta | Claude API, [Amazon Bedrock (bedrock-runtime)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy), [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed), [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry) | [Claude Fable 5.2](https://platform.claude.com/docs/en/models/fable-5-2/overview), [Claude Mythos 5.2](https://platform.claude.com/docs/en/models/mythos-5-2/overview), [Claude Fable 5.1](https://platform.claude.com/docs/en/models/fable-5-1/overview), [Claude Mythos 5.1](https://platform.claude.com/docs/en/models/mythos-5-1/overview), [Claude Fable 5](https://platform.claude.com/docs/en/models/fable-5/overview), [Claude Mythos 5](https://platform.claude.com/docs/en/models/mythos-5/overview), Claude Mythos Preview, [Claude Opus 5.5](https://platform.claude.com/docs/en/models/opus-5-5/overview), [Claude Opus 5](https://platform.claude.com/docs/en/models/opus-5/overview), [Claude Sonnet 5.5](https://platform.claude.com/docs/en/models/sonnet-5-5/overview), [Claude Sonnet 5](https://platform.claude.com/docs/en/models/sonnet-5/overview), [Claude Haiku 5.5](https://platform.claude.com/docs/en/models/haiku-5-5/overview), [Claude Opus 4.8](https://platform.claude.com/docs/en/models/opus-4-8/overview), [Claude Opus 4.7](https://platform.claude.com/docs/en/models/opus-4-7/overview), [Claude Opus 4.6](https://platform.claude.com/docs/en/models/opus-4-6/overview), [Claude Sonnet 4.6](https://platform.claude.com/docs/en/models/sonnet-4-6/overview) |
3510| Beta | [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock) | [Claude Fable 5.1](https://platform.claude.com/docs/en/models/fable-5-1/overview), [Claude Mythos 5.1](https://platform.claude.com/docs/en/models/mythos-5-1/overview), [Claude Fable 5](https://platform.claude.com/docs/en/models/fable-5/overview), [Claude Mythos 5](https://platform.claude.com/docs/en/models/mythos-5/overview), [Claude Opus 5.5](https://platform.claude.com/docs/en/models/opus-5-5/overview), [Claude Opus 5](https://platform.claude.com/docs/en/models/opus-5/overview), [Claude Sonnet 5.5](https://platform.claude.com/docs/en/models/sonnet-5-5/overview), [Claude Sonnet 5](https://platform.claude.com/docs/en/models/sonnet-5/overview), [Claude Haiku 5.5](https://platform.claude.com/docs/en/models/haiku-5-5/overview), [Claude Opus 4.8](https://platform.claude.com/docs/en/models/opus-4-8/overview), [Claude Opus 4.7](https://platform.claude.com/docs/en/models/opus-4-7/overview) |
34633511
34643512#### [Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview)
34653513
34663514
build-with-claude/context-editing Changed · +5 / -5 lines
from line 30
3030 - claude-sonnet-4-5-20250929
3131 supportedPlatforms:
3232 Claude API: beta
33 Claude Platform on AWS: beta
3433 Amazon Bedrock: beta
35 Amazon Bedrock (InvokeModel): beta
34 Amazon Bedrock (bedrock-runtime): beta
35 Claude Platform on AWS: beta
3636 Claude Models on Google Cloud (Google managed): beta
3737 Microsoft Foundry: beta
3838---
from line 2980
29802980
29812981* Availability: Available
29822982
2983| Status | Cloud platforms |
2984| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2985| Beta | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), [Amazon Bedrock (InvokeModel)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed), [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry) |
2983| Status | Cloud platforms |
2984| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
2985| Beta | Claude API, [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), [Amazon Bedrock (bedrock-runtime)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy), [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed), [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry) |
29862986
29872987### Required beta headers
29882988
build-with-claude/context-windows Changed · +3 / -3 lines
from line 41
4141
4242A single request can include up to 600 images or PDF pages (100 for models with a 200k-token context window). If you send many images or large documents, you might reach [request size limits](https://platform.claude.com/docs/en/api/overview#request-size-limits) before the token limit.
4343
44See the [model comparison](https://platform.claude.com/docs/en/models/overview#latest-models-comparison) table for a list of context window sizes by model.
44See the [All models](https://platform.claude.com/docs/en/models/overview#all-models) table for a list of context window sizes by model.
4545
4646## The context window with thinking
4747
from line 165
165165 Automatically manage conversation context as it grows with context editing.
166166 </Card>
167167
168 <Card title="Model comparison table" icon="scales" href="https://platform.claude.com/docs/en/models/overview#latest-models-comparison">
169 See the model comparison table for a list of context window sizes and input/output token pricing by model.
168 <Card title="All models table" icon="scales" href="https://platform.claude.com/docs/en/models/overview#all-models">
169 See the All models table for a list of context window sizes and input/output token pricing by model.
170170 </Card>
171171
172172 <Card title="Thinking" icon="settings" href="https://platform.claude.com/docs/en/build-with-claude/thinking">
build-with-claude/effort Changed · +25 / -294 lines
### Per-message effort ### Per-message effort (beta)
from line 27
2727 - claude-opus-4-5-20251101
2828 supportedPlatforms:
2929 Claude API: stable
30 Amazon Bedrock: stable
31 Amazon Bedrock (bedrock-runtime): stable
3032 Claude Platform on AWS: stable
3133 Claude Models on Google Cloud (Anthropic managed): stable
32 Amazon Bedrock: stable
33 Amazon Bedrock (InvokeModel): stable
3434 Claude Models on Google Cloud (Google managed): stable
3535 Microsoft Foundry: stable
3636---
from line 40
4040* **Messages API**: Set `output_config.effort` on the request. With no value, the model’s default level applies.
4141* **Managed Agents**: Set `effort` on the agent’s model object, or in a session’s model override. With no value, Managed Agents fills in the model’s default.
4242
43The effort parameter lets you control how many tokens Claude spends when responding to requests. You can trade off between response thoroughness and token efficiency with a single model. The top-level effort parameter is available on all supported models with no beta header required. [Per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta) is in beta.
43The effort parameter lets you control how many tokens Claude spends when responding to requests. You can trade off between response thoroughness and token efficiency with a single model.
4444
4545<Tip>
4646 To learn how effort interacts with thinking and which control to reach for, see [Thinking and effort](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-and-effort). Where adaptive thinking is available, effort is the recommended way to control thinking depth.
from line 187
187187 ```
188188
189189 ```php PHP
190 use Anthropic\Client;
191 use Anthropic\Messages\Model;
192 use Anthropic\Messages\TextBlock;
193
190194 $client = new Client();
191195
192196 $message = $client->messages->create(
from line 198
194198 messages: [
195199 ['role' => 'user', 'content' => 'Analyze the trade-offs between microservices and monolithic architectures']
196200 ],
197 model: 'claude-opus-5-5',
201 model: Model::CLAUDE_OPUS_5_5,
198202 outputConfig: ['effort' => 'medium'],
199203 );
200204
201205 foreach ($message->content as $block) {
202 if ($block->type === 'text') {
206 if ($block instanceof TextBlock) {
203207 echo $block->text, PHP_EOL;
204208 }
205209 }
from line 224
220224 )
221225
222226 message.content.each do |block|
223 puts block.text if block.type == :text
227 case block
228 when Anthropic::Models::TextBlock
229 puts block.text
230 end
224231 end
225232 ```
226233</CodeGroup>
from line 272
265272
266273Claude Fable 5.2 supports all five effort levels. The API default is `high`. Adaptive thinking is always on, so effort is your main control for thinking depth, latency, and cost. Start with `high`. Most of the gain in capability is already present at `high`, and above it, gains are uneven and depend on the task. Step up to `xhigh` for your hardest long-running coding and agentic work, where you’ve measured a gain. Step down to `medium` or `low` where your evals show quality holds. Reserve `max` for measuring the model’s ceiling and for the rare task where time and tokens don’t matter. At `max` the model optimizes for capability without regard to token cost. It runs slower and costs more than at `xhigh`, often for only a small gain. Run an effort sweep on your own evals rather than carrying settings over from Claude Fable 5.1. At `high` and above, set a large `max_tokens`. It’s a hard limit on total output (thinking plus response text). Effort barely changes how long the model’s replies are, so use your prompt to change reply length and tone. The same recommendations apply to Claude Mythos 5.2.
267274
268Where your platform supports it, Claude Fable 5.2 and Claude Mythos 5.2 also support [changing effort mid-conversation](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta) with a per-message `output_config`, which preserves the prompt cache.
275Where your platform supports it, Claude Fable 5.2 and Claude Mythos 5.2 also support [changing effort mid-conversation](https://platform.claude.com/docs/en/build-with-claude/effort-per-message) with a per-message `output_config`, which preserves the prompt cache.
269276
270277See also: [Prompting Claude Fable 5.2](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2#calibrate-effort)
271278
272279**[Claude Opus 5.5](https://platform.claude.com/docs/en/models/opus-5-5/overview)** — *For long-running agentic coding and knowledge work*
273280
274Claude Opus 5.5 supports all five effort levels, and `medium` is the default (Claude Opus 5 and earlier Opus models default to `high`, so a request that omits `effort` runs one level lower than it did on Claude Opus 5). Adaptive thinking is always on and can’t be turned off, so effort is the primary control for how much the model reasons and what a request costs. Run an effort sweep on your own evals rather than carrying settings over from an earlier model, and set a large `max_tokens` at the higher levels: it’s a hard limit on total output (thinking plus response text). Requests that set `thinking: {"type": "disabled"}` return a 400 error at every effort level. Claude Opus 5.5 also supports [changing effort mid-conversation](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta) with a per-message `output_config`, which preserves the prompt cache.
281Claude Opus 5.5 supports all five effort levels, and `medium` is the default (Claude Opus 5 and earlier Opus models default to `high`, so a request that omits `effort` runs one level lower than it did on Claude Opus 5). Adaptive thinking is always on and can’t be turned off, so effort is the primary control for how much the model reasons and what a request costs. Run an effort sweep on your own evals rather than carrying settings over from an earlier model, and set a large `max_tokens` at the higher levels: it’s a hard limit on total output (thinking plus response text). Requests that set `thinking: {"type": "disabled"}` return a 400 error at every effort level. Claude Opus 5.5 also supports [changing effort mid-conversation](https://platform.claude.com/docs/en/build-with-claude/effort-per-message) with a per-message `output_config`, which preserves the prompt cache.
275282
276283See also: [Prompting Claude Opus 5.5](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5)
277284
from line 288
281288
282289To turn off up-front thinking, send `thinking: {"type": "between_tools"}` instead of `"disabled"`. It’s the lowest thinking setting on Claude Sonnet 5.5, and it works at `low`, `medium`, and `high` effort. At `xhigh` or `max`, a request with it returns a 400 error, so use adaptive thinking at those levels: omit the `thinking` field or send `thinking: {"type": "adaptive"}`. See [Running without up-front thinking](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5#running-without-up-front-thinking).
283290
284Claude Sonnet 5.5 also supports [changing effort mid-conversation](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta) with a per-message `output_config`, which preserves the prompt cache. With `between_tools`, effort can’t change mid-conversation: a per-message `output_config.effort` that differs from the level in effect returns a 400 error. To vary effort for each turn, use adaptive thinking.
291Where your platform supports it, Claude Sonnet 5.5 also supports [changing effort mid-conversation](https://platform.claude.com/docs/en/build-with-claude/effort-per-message) with a per-message `output_config`, which preserves the prompt cache. With `between_tools`, effort can’t change mid-conversation: a per-message `output_config.effort` that differs from the level in effect returns a 400 error. To vary effort for each turn, use adaptive thinking.
285292
286293See also: [Prompting Claude Sonnet 5.5](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5#calibrate-effort)
287294
from line 298
291298
292299To get less thinking, lower the effort level. You can also send `thinking: {"type": "disabled"}` at `high` effort or below. At `xhigh` or `max`, it returns a 400 error, so use adaptive thinking there: omit the `thinking` field or send `thinking: {"type": "adaptive"}`.
293300
294Where your platform supports it, Claude Haiku 5.5 also lets you [change effort mid-conversation](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta) with a per-message `output_config`, which preserves the prompt cache. With `thinking: {"type": "disabled"}`, effort can’t change mid-conversation: a per-message `output_config.effort` that differs from the level in effect returns a 400 error. To vary effort for each turn, use adaptive thinking.
301Where your platform supports it, Claude Haiku 5.5 also lets you [change effort mid-conversation](https://platform.claude.com/docs/en/build-with-claude/effort-per-message) with a per-message `output_config`, which preserves the prompt cache. With `thinking: {"type": "disabled"}`, effort can’t change mid-conversation: a per-message `output_config.effort` that differs from the level in effect returns a 400 error. To vary effort for each turn, use adaptive thinking.
295302
296303See also: [Prompting Claude Haiku 5.5](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-haiku-5-5#use-effort-to-control-thinking)
297304
from line 306
299306
300307Claude Fable 5.1 supports all five effort levels. **Start with `high`, the default.** Step up to `xhigh` or `max` for the most capability-sensitive agentic and coding work, and step down to `medium` or `low` for routine or latency-sensitive work once your evals show quality holds. At `high` and above, set a large `max_tokens`. It’s a hard limit on total output (thinking plus response text).
301308
302Claude Fable 5.1 also supports [changing effort mid-conversation](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta) with a per-message `output_config`, which preserves the prompt cache.
309Claude Fable 5.1 also supports [changing effort mid-conversation](https://platform.claude.com/docs/en/build-with-claude/effort-per-message) with a per-message `output_config`, which preserves the prompt cache.
303310
304311See also: [Prompting Claude Fable 5.1](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1#consider-all-effort-levels)
305312
from line 330
323330
324331When running Claude Opus 5 at `xhigh` or `max` effort, set a large `max_tokens` so the model has room to think and act across subagents and tool calls. Starting at 64k tokens and tuning from there is a reasonable default.
325332
326Claude Opus 5 also supports [changing effort mid-conversation](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta) with a per-message `output_config`, which preserves the prompt cache. Per-message effort isn’t available for Claude Opus 5 on Amazon Bedrock.
333Where your platform supports it, Claude Opus 5 also supports [changing effort mid-conversation](https://platform.claude.com/docs/en/build-with-claude/effort-per-message) with a per-message `output_config`, which preserves the prompt cache.
327334
328335See also: [Prompting Claude Opus 5](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5)
329336
from line 413
406413
407414## Change effort mid-conversation
408415
409You can run later turns of a conversation at a different effort level in two ways. On Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, and Claude Haiku 5.5, use a per-message effort change, which keeps the prompt cache. On other models, set a new top-level value on the next request, which starts the cache over.
416You can run later turns of a conversation at a different effort level in two ways: a per-message effort change, which keeps the prompt cache, or a new top-level value on the next request, which starts the cache over.
410417
411### Per-message effort (beta)
418### Per-message effort
412419
413Per-message effort is in beta. On the Claude API and [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed), it’s available on Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, and Claude Haiku 5.5. On the Claude API, it’s also available on Claude Fable 5.2 and Claude Mythos 5.2. On Claude Models on Google Cloud (Google managed), it’s also available on Claude Fable 5.2 and Claude Mythos 5.2. On [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed), it’s available on Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, and Claude Haiku 5.5. On [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), it’s available on Claude Fable 5.2, Claude Fable 5.1, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, and Claude Haiku 5.5. On [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), it’s available on Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, and Claude Opus 5.5. It requires the [beta header](https://platform.claude.com/docs/en/api/beta-headers) `mid-conversation-output-config-2026-07-01`. With the Amazon Bedrock [InvokeModel API](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy), it’s available on Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, and Claude Opus 5.5, and you send that value in the `anthropic_beta` array of the request body instead.
420[Per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort-per-message) sets a new level with a `system` message in `messages`.
414421
415Without the beta value, a per-message `output_config` returns a 400 error: `messages.N.output_config: Extra inputs are not permitted`, where `N` is the index of the `system` message in `messages`. With the beta value, models without per-message effort, including Claude Fable 5, return a 400 error: `output_config.effort requires a model that supports per-turn effort; this model does not`. On Amazon Bedrock, those models and Claude Opus 5 return the `Extra inputs are not permitted` error instead. On Claude Sonnet 5.5 with `thinking: {"type": "between_tools"}` and on Claude Haiku 5.5 with `thinking: {"type": "disabled"}`, effort can’t change mid-conversation: a per-message `output_config.effort` that differs from the level in effect returns a 400 error. To vary effort for each turn, use adaptive thinking.
416
417Add a `role: "system"` message with empty `content` and the new level in `output_config.effort`. Placed directly after a `user` turn with new input, it sets the level for Claude’s reply to that turn. Placed anywhere else, such as between an `assistant` turn and the next `user` turn as in the following example, it takes effect from the next `user` turn with new input. A `user` turn that holds only `tool_result` blocks doesn’t count as new input, so a change placed after one in a tool-use loop waits for the next `user` turn with new input. The new level then holds until a later message changes it. Everything before that message is unchanged, so the cached prefix still matches.
418
419The following example starts at `high`, then drops to `low` for a routine follow-up:
420
421<CodeGroup>
422 ```bash cURL
423 # Effort-only system message: the new level takes effect from the next user turn.
424 curl https://api.anthropic.com/v1/messages \
425 -H "x-api-key: $ANTHROPIC_API_KEY" \
426 -H "anthropic-version: 2026-10-21" \
427 -H "anthropic-beta: mid-conversation-output-config-2026-07-01" \
428 -H "content-type: application/json" \
429 -d '{
430 "model": "claude-fable-5-1",
431 "max_tokens": 4096,
432 "output_config": {"effort": "high"},
433 "messages": [
434 {"role": "user", "content": "Plan a migration from SQLite to PostgreSQL in three short steps."},
435 {"role": "assistant", "content": "1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts."},
436 {"role": "system", "content": [], "output_config": {"effort": "low"}},
437 {"role": "user", "content": "Summarize the plan in one sentence."}
438 ]
439 }'
440 ```
441
442 ```bash CLI
443 ant beta:messages create \
444 --beta mid-conversation-output-config-2026-07-01 <<'YAML'
445 model: claude-fable-5-1
446 max_tokens: 4096
447 output_config:
448 effort: high
449 messages:
450 - role: user
451 content: Plan a migration from SQLite to PostgreSQL in three short steps.
452 - role: assistant
453 content: "1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts."
454 # Effort-only system message: the new level takes effect from the next user turn.
455 - role: system
456 content: []
457 output_config:
458 effort: low
459 - role: user
460 content: Summarize the plan in one sentence.
461 YAML
462 ```
463
464 ```python Python
465 client = anthropic.Anthropic()
466
467 response = client.beta.messages.create(
468 model="claude-fable-5-1",
469 max_tokens=4096,
470 output_config={"effort": "high"},
471 messages=[
472 {
473 "role": "user",
474 "content": "Plan a migration from SQLite to PostgreSQL in three short steps.",
475 },
476 {
477 "role": "assistant",
478 "content": "1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts.",
479 },
480 # Effort-only system message: the new level takes effect from the next user turn.
481 {"role": "system", "content": [], "output_config": {"effort": "low"}},
482 {"role": "user", "content": "Summarize the plan in one sentence."},
483 ],
484 betas=["mid-conversation-output-config-2026-07-01"],
485 )
486
487 for block in response.content:
488 if block.type == "text":
489 print(block.text)
490 ```
491
492 ```typescript TypeScript
493 const client = new Anthropic();
494
495 const response = await client.beta.messages.create({
496 model: "claude-fable-5-1",
497 max_tokens: 4096,
498 output_config: { effort: "high" },
499 messages: [
500 {
501 role: "user",
502 content: "Plan a migration from SQLite to PostgreSQL in three short steps."
503 },
504 {
505 role: "assistant",
506 content:
507 "1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts."
508 },
509 // Effort-only system message: the new level takes effect from the next user turn.
510 { role: "system", content: [], output_config: { effort: "low" } },
511 { role: "user", content: "Summarize the plan in one sentence." }
512 ],
513 betas: ["mid-conversation-output-config-2026-07-01"]
514 });
515
516 for (const block of response.content) {
517 if (block.type === "text") {
518 console.log(block.text);
519 }
520 }
521 ```
522
523 ```csharp C#
524 using Anthropic.Models.Beta;
525 using Anthropic.Models.Beta.Messages;
526 using Model = Anthropic.Models.Messages.Model;
527
528 AnthropicClient client = new();
529
530 var response = await client.Beta.Messages.Create(new MessageCreateParams
531 {
532 Model = Model.ClaudeFable5_1,
533 MaxTokens = 4096,
534 OutputConfig = new() { Effort = Effort.High },
535 Messages =
536 [
537 new BetaUserMessageParam { Content = "Plan a migration from SQLite to PostgreSQL in three short steps." },
538 new BetaAssistantMessageParam { Content = "1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts." },
539 // Effort-only system message: the new level takes effect from the next user turn.
540 new BetaSystemMessageParam
541 {
542 Content = new([]),
543 OutputConfig = new() { Effort = BetaSystemMessageOutputConfigEffort.Low },
544 },
545 new BetaUserMessageParam { Content = "Summarize the plan in one sentence." },
546 ],
547 Betas = [AnthropicBeta.MidConversationOutputConfig2026_07_01],
548 });
549
550 foreach (var block in response.Content)
551 {
552 if (block.TryPickText(out var textBlock))
553 {
554 Console.WriteLine(textBlock.Text);
555 }
556 }
557 ```
558
559 ```go Go
560 client := anthropic.NewClient()
561
562 response, err := client.Beta.Messages.New(context.Background(), anthropic.BetaMessageNewParams{
563 Model: anthropic.ModelClaudeFable5_1,
564 MaxTokens: 4096,
565 OutputConfig: anthropic.BetaOutputConfigParam{
566 Effort: anthropic.BetaOutputConfigEffortHigh,
567 },
568 Messages: []anthropic.BetaMessageParam{
569 anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Plan a migration from SQLite to PostgreSQL in three short steps.")),
570 {OfAssistant: &anthropic.BetaAssistantMessageParam{
571 Content: []anthropic.BetaContentBlockParamUnion{anthropic.NewBetaTextBlock("1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts.")},
572 }},
573 // Effort-only system message: the new level takes effect from the next user turn.
574 anthropic.NewBetaSystemMessage(anthropic.BetaSystemMessageOutputConfigParam{
575 Effort: anthropic.BetaSystemMessageOutputConfigEffortLow,
576 }),
577 anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Summarize the plan in one sentence.")),
578 },
579 Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaMidConversationOutputConfig2026_07_01},
580 })
581 if err != nil {
582 log.Fatal(err)
583 }
584
585 for _, block := range response.Content {
586 if textBlock, ok := block.AsAny().(anthropic.BetaTextBlock); ok {
587 fmt.Println(textBlock.Text)
588 }
589 }
590 ```
591
592 ```java Java
593 import com.anthropic.models.beta.AnthropicBeta;
594 import com.anthropic.models.beta.messages.BetaMessage;
595 import com.anthropic.models.beta.messages.BetaOutputConfig;
596 import com.anthropic.models.beta.messages.BetaSystemMessageOutputConfig;
597 import com.anthropic.models.beta.messages.BetaSystemMessageParam;
598 import com.anthropic.models.beta.messages.MessageCreateParams;
599 import com.anthropic.models.messages.Model;
600
601 void main() {
602 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
603
604 MessageCreateParams params = MessageCreateParams.builder()
605 .model(Model.CLAUDE_FABLE_5_1)
606 .maxTokens(4096L)
607 .addBeta(AnthropicBeta.MID_CONVERSATION_OUTPUT_CONFIG_2026_07_01)
608 .outputConfig(BetaOutputConfig.builder()
609 .effort(BetaOutputConfig.Effort.HIGH)
610 .build())
611 .addUserMessage("Plan a migration from SQLite to PostgreSQL in three short steps.")
612 .addAssistantMessage("1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts.")
613 // Effort-only system message: the new level takes effect from the next user turn.
614 .addMessage(BetaSystemMessageParam.builder()
615 .contentOfBlocks(List.of())
616 .outputConfig(BetaSystemMessageOutputConfig.builder()
617 .effort(BetaSystemMessageOutputConfig.Effort.LOW)
618 .build())
619 .build())
620 .addUserMessage("Summarize the plan in one sentence.")
621 .build();
622
623 BetaMessage response = client.beta().messages().create(params);
624 response.content().stream()
625 .flatMap(block -> block.text().stream())
626 .forEach(textBlock -> IO.println(textBlock.text()));
627 }
628 ```
629
630 ```php PHP
631 use Anthropic\Beta\AnthropicBeta;
632 use Anthropic\Beta\Messages\BetaMessageParam;
633 use Anthropic\Beta\Messages\BetaOutputConfig;
634 use Anthropic\Beta\Messages\BetaSystemMessageOutputConfig;
635 use Anthropic\Client;
636
637 $client = new Client();
638
639 $response = $client->beta->messages->create(
640 model: 'claude-fable-5-1',
641 maxTokens: 4096,
642 outputConfig: BetaOutputConfig::with(effort: 'high'),
643 messages: [
644 BetaMessageParam::with(role: 'user', content: 'Plan a migration from SQLite to PostgreSQL in three short steps.'),
645 BetaMessageParam::with(role: 'assistant', content: '1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts.'),
646 // Effort-only system message: the new level takes effect from the next user turn.
647 BetaMessageParam::with(
648 role: 'system',
649 content: [],
650 outputConfig: BetaSystemMessageOutputConfig::with(effort: 'low'),
651 ),
652 BetaMessageParam::with(role: 'user', content: 'Summarize the plan in one sentence.'),
653 ],
654 betas: [AnthropicBeta::MID_CONVERSATION_OUTPUT_CONFIG_2026_07_01],
655 );
656
657 foreach ($response->content as $block) {
658 if ($block->type === 'text') {
659 echo $block->text, PHP_EOL;
660 }
661 }
662 ```
663
664 ```ruby Ruby
665 client = Anthropic::Client.new
666
667 response = client.beta.messages.create(
668 model: Anthropic::Model::CLAUDE_FABLE_5_1,
669 max_tokens: 4096,
670 output_config: {effort: :high},
671 messages: [
672 {role: "user", content: "Plan a migration from SQLite to PostgreSQL in three short steps."},
673 {role: "assistant", content: "1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts."},
674 # Effort-only system message: the new level takes effect from the next user turn.
675 {role: "system", content: [], output_config: {effort: :low}},
676 {role: "user", content: "Summarize the plan in one sentence."}
677 ],
678 betas: [Anthropic::AnthropicBeta::MID_CONVERSATION_OUTPUT_CONFIG_2026_07_01]
679 )
680
681 response.content.each do |block|
682 puts block.text if block.type == :text
683 end
684 ```
685</CodeGroup>
686
687An effort-only system message carries no text, so the [placement rules for mid-conversation system messages](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#limitations) don’t apply. It can appear anywhere in `messages`, including as the first entry or between an `assistant` turn and the next `user` turn. Values are the level names (`low`, `medium`, `high`, `xhigh`, and `max`).
688
689Prefer this form over changing the top-level value between requests. A top-level change restarts the cache and, on Claude Fable 5.1, also steers the model less reliably: its earlier replies were written at the previous level, and it tends to stay consistent with them.
690
691422### Top-level effort on the next request
692423
693424The top-level `output_config.effort` applies to the whole request. To run a later part of a conversation at a different level, set the new value on the next request. Because top-level effort shapes the rendered prompt, changing it between requests doesn’t preserve cached prefixes from earlier turns. If you rely on [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) across a long session and your model doesn’t support per-message effort, pick an effort level at the start and keep it constant.
from line 429
6984292. **Use low for speed-sensitive or simple tasks:** When latency matters or tasks are straightforward, low effort can significantly reduce response times and costs.
6994303. **Test your use case:** The impact of effort levels varies by task type. Evaluate performance on your specific use cases before deploying.
7004314. **Consider dynamic effort:** Adjust effort based on task complexity. Simple queries might warrant low effort, whereas agentic coding and complex reasoning benefit from high effort. See the next item before varying it within one conversation.
7015. **Hold top-level effort constant within cached conversations:** Changing the top-level effort value between requests invalidates [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching), so vary it across workloads rather than within a conversation that relies on cache hits. On models that support it, use a [per-message effort change](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta) instead, which preserves the cache. See [Thinking and prompt caching](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-and-prompt-caching).
4325. **Hold top-level effort constant within cached conversations:** Changing the top-level effort value between requests invalidates [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching), so vary it across workloads rather than within a conversation that relies on cache hits. On models that support it, use a [per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort-per-message) change instead, which preserves the cache. See [Thinking and prompt caching](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-and-prompt-caching).
702433
703434## Next steps
704435
build-with-claude/effort-per-message New page · 368 lines, new page
## Change the effort level ## Errors ## Per-message or top-level effort ## Availability ### API support #### [Messages API](https://platform.claude.com/docs/en/build-with-claude/working-with-messages) #### [Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) ### Required beta headers
A whole new page. There's nothing to diff it against, so here is what it says.
---
title: Per-message effort
url: https://platform.claude.com/docs/en/build-with-claude/effort-per-message
description: Use a system message to change the effort level partway through a conversation and keep the prompt cache.
featureMetadata:
status: beta
betaHeader: mid-conversation-output-config-2026-07-01
supportedModels:
- claude-fable-5-2
- claude-mythos-5-2
- claude-fable-5-1
- claude-mythos-5-1
- claude-opus-5-5
- claude-opus-5
- claude-sonnet-5-5
- claude-haiku-5-5
supportedPlatforms:
Claude API: beta
Amazon Bedrock: beta
Amazon Bedrock (bedrock-runtime):
availability: beta
note: Send the beta value in the `anthropic_beta` array of the request body.
Claude Platform on AWS: beta
Claude Models on Google Cloud (Anthropic managed): beta
Claude Models on Google Cloud (Google managed): beta
Microsoft Foundry: beta
---
A per-message effort change sets a new effort level for later turns of a conversation without changing the request’s top-level value, so the cached prefix still matches.
## Change the effort level
To change the level partway through a conversation:
1. Add a `role: "system"` message to `messages`, with empty `content` and the new [effort](https://platform.claude.com/docs/en/build-with-claude/effort) level in `output_config.effort`.
2. Send the `mid-conversation-output-config-2026-07-01` [beta header](https://platform.claude.com/docs/en/api/beta-headers).
3. Leave the top-level value unchanged.
The following example keeps the top-level value at `high` and drops to `low` for a routine follow-up:
<CodeGroup>
```bash cURL
# Effort-only system message: the new level takes effect from the next user turn.
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-H "anthropic-beta: mid-conversation-output-config-2026-07-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-fable-5-1",
"max_tokens": 4096,
"output_config": {"effort": "high"},
"messages": [
{"role": "user", "content": "Plan a migration from SQLite to PostgreSQL in three short steps."},
{"role": "assistant", "content": "1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts."},
{"role": "system", "content": [], "output_config": {"effort": "low"}},
{"role": "user", "content": "Summarize the plan in one sentence."}
]
}'
```
```bash CLI
ant beta:messages create \
--beta mid-conversation-output-config-2026-07-01 <<'YAML'
model: claude-fable-5-1
max_tokens: 4096
output_config:
effort: high
messages:
- role: user
content: Plan a migration from SQLite to PostgreSQL in three short steps.
- role: assistant
content: "1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts."
# Effort-only system message: the new level takes effect from the next user turn.
- role: system
content: []
output_config:
effort: low
- role: user
content: Summarize the plan in one sentence.
YAML
```
```python Python
client = anthropic.Anthropic()
response = client.beta.messages.create(
model="claude-fable-5-1",
max_tokens=4096,
output_config={"effort": "high"},
messages=[
{
"role": "user",
"content": "Plan a migration from SQLite to PostgreSQL in three short steps.",
},
{
"role": "assistant",
"content": "1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts.",
},
# Effort-only system message: the new level takes effect from the next user turn.
{"role": "system", "content": [], "output_config": {"effort": "low"}},
{"role": "user", "content": "Summarize the plan in one sentence."},
],
betas=["mid-conversation-output-config-2026-07-01"],
)
for block in response.content:
if block.type == "text":
print(block.text)
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.beta.messages.create({
model: "claude-fable-5-1",
max_tokens: 4096,
output_config: { effort: "high" },
messages: [
{
role: "user",
content: "Plan a migration from SQLite to PostgreSQL in three short steps."
},
{
role: "assistant",
content:
"1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts."
},
// Effort-only system message: the new level takes effect from the next user turn.
{ role: "system", content: [], output_config: { effort: "low" } },
{ role: "user", content: "Summarize the plan in one sentence." }
],
betas: ["mid-conversation-output-config-2026-07-01"]
});
for (const block of response.content) {
if (block.type === "text") {
console.log(block.text);
}
}
```
```csharp C#
using Anthropic.Models.Beta;
using Anthropic.Models.Beta.Messages;
using Model = Anthropic.Models.Messages.Model;
AnthropicClient client = new();
var response = await client.Beta.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeFable5_1,
MaxTokens = 4096,
OutputConfig = new() { Effort = Effort.High },
Messages =
[
new BetaUserMessageParam { Content = "Plan a migration from SQLite to PostgreSQL in three short steps." },
new BetaAssistantMessageParam { Content = "1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts." },
// Effort-only system message: the new level takes effect from the next user turn.
new BetaSystemMessageParam
{
Content = new([]),
OutputConfig = new() { Effort = BetaSystemMessageOutputConfigEffort.Low },
},
new BetaUserMessageParam { Content = "Summarize the plan in one sentence." },
],
Betas = [AnthropicBeta.MidConversationOutputConfig2026_07_01],
});
foreach (var block in response.Content)
{
if (block.TryPickText(out var textBlock))
{
Console.WriteLine(textBlock.Text);
}
}
```
```go Go
client := anthropic.NewClient()
response, err := client.Beta.Messages.New(context.Background(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeFable5_1,
MaxTokens: 4096,
OutputConfig: anthropic.BetaOutputConfigParam{
Effort: anthropic.BetaOutputConfigEffortHigh,
},
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Plan a migration from SQLite to PostgreSQL in three short steps.")),
{OfAssistant: &anthropic.BetaAssistantMessageParam{
Content: []anthropic.BetaContentBlockParamUnion{anthropic.NewBetaTextBlock("1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts.")},
}},
// Effort-only system message: the new level takes effect from the next user turn.
anthropic.NewBetaSystemMessage(anthropic.BetaSystemMessageOutputConfigParam{
Effort: anthropic.BetaSystemMessageOutputConfigEffortLow,
}),
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Summarize the plan in one sentence.")),
},
Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaMidConversationOutputConfig2026_07_01},
})
if err != nil {
log.Fatal(err)
}
for _, block := range response.Content {
if textBlock, ok := block.AsAny().(anthropic.BetaTextBlock); ok {
fmt.Println(textBlock.Text)
}
}
```
```java Java
import com.anthropic.models.beta.AnthropicBeta;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.BetaOutputConfig;
import com.anthropic.models.beta.messages.BetaSystemMessageOutputConfig;
import com.anthropic.models.beta.messages.BetaSystemMessageParam;
import com.anthropic.models.beta.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_FABLE_5_1)
.maxTokens(4096L)
.addBeta(AnthropicBeta.MID_CONVERSATION_OUTPUT_CONFIG_2026_07_01)
.outputConfig(BetaOutputConfig.builder()
.effort(BetaOutputConfig.Effort.HIGH)
.build())
.addUserMessage("Plan a migration from SQLite to PostgreSQL in three short steps.")
.addAssistantMessage("1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts.")
// Effort-only system message: the new level takes effect from the next user turn.
.addMessage(BetaSystemMessageParam.builder()
.contentOfBlocks(List.of())
.outputConfig(BetaSystemMessageOutputConfig.builder()
.effort(BetaSystemMessageOutputConfig.Effort.LOW)
.build())
.build())
.addUserMessage("Summarize the plan in one sentence.")
.build();
BetaMessage response = client.beta().messages().create(params);
response.content().stream()
.flatMap(block -> block.text().stream())
.forEach(textBlock -> IO.println(textBlock.text()));
}
```
```php PHP
use Anthropic\Beta\AnthropicBeta;
use Anthropic\Beta\Messages\BetaMessageParam;
use Anthropic\Beta\Messages\BetaOutputConfig;
use Anthropic\Beta\Messages\BetaSystemMessageOutputConfig;
use Anthropic\Beta\Messages\BetaTextBlock;
use Anthropic\Client;
use Anthropic\Messages\Model;
$client = new Client();
$response = $client->beta->messages->create(
model: Model::CLAUDE_FABLE_5_1,
maxTokens: 4096,
outputConfig: BetaOutputConfig::with(effort: 'high'),
messages: [
BetaMessageParam::with(role: 'user', content: 'Plan a migration from SQLite to PostgreSQL in three short steps.'),
BetaMessageParam::with(role: 'assistant', content: '1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts.'),
// Effort-only system message: the new level takes effect from the next user turn.
BetaMessageParam::with(
role: 'system',
content: [],
outputConfig: BetaSystemMessageOutputConfig::with(effort: 'low'),
),
BetaMessageParam::with(role: 'user', content: 'Summarize the plan in one sentence.'),
],
betas: [AnthropicBeta::MID_CONVERSATION_OUTPUT_CONFIG_2026_07_01],
);
foreach ($response->content as $block) {
if ($block instanceof BetaTextBlock) {
echo $block->text, PHP_EOL;
}
}
```
```ruby Ruby
client = Anthropic::Client.new
response = client.beta.messages.create(
model: Anthropic::Model::CLAUDE_FABLE_5_1,
max_tokens: 4096,
output_config: {effort: :high},
messages: [
{role: "user", content: "Plan a migration from SQLite to PostgreSQL in three short steps."},
{role: "assistant", content: "1. Export the SQLite data. 2. Create the PostgreSQL schema. 3. Import the data and verify row counts."},
# Effort-only system message: the new level takes effect from the next user turn.
{role: "system", content: [], output_config: {effort: :low}},
{role: "user", content: "Summarize the plan in one sentence."}
],
betas: [Anthropic::AnthropicBeta::MID_CONVERSATION_OUTPUT_CONFIG_2026_07_01]
Cut at 300 lines. The page has the rest.
build-with-claude/extended-thinking Changed · +3 / -3 lines
from line 12
1212 - claude-sonnet-4-5-20250929
1313 supportedPlatforms:
1414 Claude API: stable
15 Amazon Bedrock: stable
16 Amazon Bedrock (bedrock-runtime): stable
1517 Claude Platform on AWS: stable
1618 Claude Models on Google Cloud (Anthropic managed): stable
17 Amazon Bedrock: stable
18 Amazon Bedrock (InvokeModel): stable
1919 Claude Models on Google Cloud (Google managed): stable
2020 Microsoft Foundry: stable
2121---
from line 363
363363You need to migrate off `type: "enabled"` if:
364364
365365* You use Claude Opus 4.6 or Claude Sonnet 4.6, where `budget_tokens` is deprecated.
366* You use Claude 4.7 or a later model, such as Claude Opus 5.5, Claude Sonnet 5, Claude Sonnet 5.5, Claude Fable 5.2, Claude Fable 5.1, or Claude Haiku 5.5, where `type: "enabled"` returns a 400 error.
366* You use a model numbered 4.7 or higher, where `type: "enabled"` returns a 400 error. Examples include Claude Opus 5.5, Claude Sonnet 5, Claude Sonnet 5.5, Claude Fable 5.2, Claude Fable 5.1, and Claude Haiku 5.5.
367367
368368The mapping is small: remove `budget_tokens`, set `thinking: {type: "adaptive"}`, and control reasoning depth with `output_config: {effort: ...}` instead of a token budget.
369369
build-with-claude/fallback-credit Changed · +8 / -7 lines
from line 16
1616 - claude-sonnet-5-5
1717 supportedPlatforms:
1818 Claude API: beta
19 Claude Platform on AWS: beta
2019 Amazon Bedrock:
2120 availability: beta
2221 note: On Amazon Bedrock and Google Cloud the token is bound to your caller identity (there are no workspaces), and `allowed_fallback_models` is not exposed.
22 Claude Platform on AWS: beta
2323 Claude Models on Google Cloud (Google managed):
2424 availability: beta
2525 note: On Amazon Bedrock and Google Cloud the token is bound to your caller identity (there are no workspaces), and `allowed_fallback_models` is not exposed.
from line 70
7070
7171<CodeGroup exclude="shell:cURL, shell:CLI">
7272 <CodeGroupItem language="cURL">
73 This workflow needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
73 This workflow needs more logic than a single shell command. Use the [Anthropic SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
7474 </CodeGroupItem>
7575
7676 <CodeGroupItem language="CLI">
77 This workflow needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
77 This workflow needs more logic than a single shell command. Use the [Anthropic SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
7878 </CodeGroupItem>
7979
8080 ```python Python
from line 655
655655* Availability: Available
656656* Usage: Needed only when you write the retry yourself: send the `fallback-credit-2026-07-01` beta header and put the refusal’s `fallback_credit_token` on the retry.
657657
658| Status | Cloud platforms | Models |
659| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
660| Beta | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry) | [Claude Fable 5.2](https://platform.claude.com/docs/en/models/fable-5-2/overview), [Claude Mythos 5.2](https://platform.claude.com/docs/en/models/mythos-5-2/overview), [Claude Fable 5.1](https://platform.claude.com/docs/en/models/fable-5-1/overview), [Claude Mythos 5.1](https://platform.claude.com/docs/en/models/mythos-5-1/overview), [Claude Fable 5](https://platform.claude.com/docs/en/models/fable-5/overview), [Claude Opus 5.5](https://platform.claude.com/docs/en/models/opus-5-5/overview), [Claude Opus 5](https://platform.claude.com/docs/en/models/opus-5/overview), [Claude Sonnet 5.5](https://platform.claude.com/docs/en/models/sonnet-5-5/overview) |
661| Beta<sup>1</sup> | [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed) | [Claude Fable 5.2](https://platform.claude.com/docs/en/models/fable-5-2/overview), [Claude Mythos 5.2](https://platform.claude.com/docs/en/models/mythos-5-2/overview), [Claude Fable 5.1](https://platform.claude.com/docs/en/models/fable-5-1/overview), [Claude Mythos 5.1](https://platform.claude.com/docs/en/models/mythos-5-1/overview), [Claude Fable 5](https://platform.claude.com/docs/en/models/fable-5/overview), [Claude Opus 5.5](https://platform.claude.com/docs/en/models/opus-5-5/overview), [Claude Opus 5](https://platform.claude.com/docs/en/models/opus-5/overview), [Claude Sonnet 5.5](https://platform.claude.com/docs/en/models/sonnet-5-5/overview) |
658| Status | Cloud platforms | Models |
659| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
660| Beta | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry) | [Claude Fable 5.2](https://platform.claude.com/docs/en/models/fable-5-2/overview), [Claude Mythos 5.2](https://platform.claude.com/docs/en/models/mythos-5-2/overview), [Claude Fable 5.1](https://platform.claude.com/docs/en/models/fable-5-1/overview), [Claude Mythos 5.1](https://platform.claude.com/docs/en/models/mythos-5-1/overview), [Claude Fable 5](https://platform.claude.com/docs/en/models/fable-5/overview), [Claude Opus 5.5](https://platform.claude.com/docs/en/models/opus-5-5/overview), [Claude Opus 5](https://platform.claude.com/docs/en/models/opus-5/overview), [Claude Sonnet 5.5](https://platform.claude.com/docs/en/models/sonnet-5-5/overview) |
661| Beta<sup>1</sup> | [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed) | [Claude Fable 5.2](https://platform.claude.com/docs/en/models/fable-5-2/overview), [Claude Mythos 5.2](https://platform.claude.com/docs/en/models/mythos-5-2/overview), [Claude Fable 5.1](https://platform.claude.com/docs/en/models/fable-5-1/overview), [Claude Mythos 5.1](https://platform.claude.com/docs/en/models/mythos-5-1/overview), [Claude Fable 5](https://platform.claude.com/docs/en/models/fable-5/overview), [Claude Opus 5.5](https://platform.claude.com/docs/en/models/opus-5-5/overview), [Claude Opus 5](https://platform.claude.com/docs/en/models/opus-5/overview), [Claude Sonnet 5.5](https://platform.claude.com/docs/en/models/sonnet-5-5/overview) |
662| Beta<sup>1</sup> | [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock) | [Claude Fable 5.1](https://platform.claude.com/docs/en/models/fable-5-1/overview), [Claude Mythos 5.1](https://platform.claude.com/docs/en/models/mythos-5-1/overview), [Claude Fable 5](https://platform.claude.com/docs/en/models/fable-5/overview), [Claude Opus 5.5](https://platform.claude.com/docs/en/models/opus-5-5/overview), [Claude Opus 5](https://platform.claude.com/docs/en/models/opus-5/overview), [Claude Sonnet 5.5](https://platform.claude.com/docs/en/models/sonnet-5-5/overview) |
662663
6636641. On Amazon Bedrock and Google Cloud the token is bound to your caller identity (there are no workspaces), and `allowed_fallback_models` is not exposed.
664665
build-with-claude/fast-mode Changed · +38 / -27 lines
from line 14
1414 - claude-opus-5
1515 - claude-opus-4-8
1616 supportedPlatforms:
17 Claude API: stable
17 Claude API:
18 availability: stable
19 note: 'Removal date: November 30, 2026. After removal, requests to `claude-opus-4-8` with `speed: "fast"` will return an error. To continue using fast mode, migrate to Claude Opus 5.5. See [Migrating to Claude Opus 5.5 from Claude Opus 4.8](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#migrating-from-claude-opus-4-8).'
1820 Claude Models on Google Cloud (Anthropic managed): stable
1921 Claude Models on Google Cloud (Google managed): stable
2022 Microsoft Foundry:
2123 availability: stable
22 note: On Microsoft Foundry, fast mode is a separate model whose ID ends in `-fast`. Send requests to a deployment of that model, and leave out `speed`.
24 note: On Microsoft Foundry, fast mode has its own model IDs, which end in `-fast`. Send requests to a deployment of the fast mode model, and leave out `speed`.
2325 details:
24 - Fast mode on Claude Opus 5 and Claude Opus 4.8 is in research preview and needs the `fast-mode-2026-02-01` beta header.
26 - Fast mode is in research preview on Claude Opus 5 and deprecated on Claude Opus 4.8, and needs the `fast-mode-2026-02-01` beta header on both models.
2527---
2628
2729**API support**: Usage differs by product.
from line 31
2931* **Messages API**: Set `speed: "fast"` on the request.
3032* **Managed Agents**: Set `speed` on the agent’s model object, for example `{"id": "claude-opus-5-5", "speed": "fast"}`.
3133
32Fast mode delivers up to 2.5x higher output tokens per second at premium pricing. Set `speed: "fast"` on your request to opt in. Fast mode is available on Claude Fable 5.2 and Claude Opus 5.5. Fast mode for Claude Opus 5 and Claude Opus 4.8 is in research preview. Claude Mythos 5.2 supports fast mode too.
34Fast mode delivers up to 2.5x higher output tokens per second at premium pricing. Set `speed: "fast"` on your request to opt in. Fast mode is available on Claude Fable 5.2, Claude Mythos 5.2, and Claude Opus 5.5. Fast mode is in research preview on Claude Opus 5 and deprecated on Claude Opus 4.8.
3335
3436## How fast mode works
3537
from line 45
4345
4446Fast mode works only on supported models. See [Availability](https://platform.claude.com/docs/en/build-with-claude/fast-mode#feature-availability) for details, including which models need a beta header.
4547
46On [Claude in Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry), fast mode is a separate model, such as `claude-opus-5-5-fast`. For Claude Fable 5.2, it is `claude-fable-5-2-fast`. For Claude Mythos 5.2, it is `claude-mythos-5-2-fast`. Send fast mode requests to a deployment of the fast model, and leave out `speed`. A request that sets `speed` on a deployment of the model without `-fast` returns an error.
47
4848<CodeGroup>
4949 ```bash cURL
5050 curl https://api.anthropic.com/v1/messages \
from line 203
203203 ```
204204</CodeGroup>
205205
206On [Claude in Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry), fast mode has its own model IDs, and the deployment sets the speed. Send fast mode requests to a deployment of the fast mode model, and leave out `speed`:
207
208| Model | Fast mode model ID |
209| ----------------- | ------------------------ |
210| Claude Fable 5.2 | `claude-fable-5-2-fast` |
211| Claude Mythos 5.2 | `claude-mythos-5-2-fast` |
212| Claude Opus 5.5 | `claude-opus-5-5-fast` |
213
214A request that sets `speed` on a deployment of the standard model, such as `claude-opus-5-5`, returns an error.
215
206216## Rate limits
207217
208218Fast mode has a dedicated rate limit that is separate from standard rate limits. When you exceed your fast mode rate limit, the API returns a `429` error with a `retry-after` header that says when capacity is available. On [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed#rate-limits), Google Cloud manages rate limits and quotas.
209219
210Claude Opus 5.5 has a default fast mode rate limit in the Start, Build, and Scale [usage tiers](https://platform.claude.com/docs/en/api/rate-limits), so you don’t need to request access to use fast mode with it. Organizations in the Evaluation tier can use fast mode with Claude Opus 5.5 once they move to the Start, Build, or Scale tier. The same applies to Claude Fable 5.2. It also applies to Claude Mythos 5.2.
220Claude Fable 5.2, Claude Mythos 5.2, and Claude Opus 5.5 have a default fast mode rate limit. The default limit applies in the Start, Build, and Scale [usage tiers](https://platform.claude.com/docs/en/api/rate-limits). You don’t need to request fast mode access for these models. Organizations in the Evaluation tier can use fast mode with these models once they move to the Start, Build, or Scale tier.
211221
212222The response includes headers that indicate your fast mode rate limit status:
213223
from line 383
373383
374384### Falling back to standard speed
375385
376If you’d prefer to fall back to standard speed rather than wait for fast mode capacity, catch the rate limit error and retry without `speed: "fast"`. On Claude in Microsoft Foundry, the deployment sets the speed, so retry on a deployment of the model without `-fast` instead. Set `max_retries` (typescript, php: `maxRetries`; java: `.maxRetries()`; csharp: `MaxRetries`; go: `option.WithMaxRetries()`) to `0` on the initial fast request to skip automatic retries and fail immediately on rate limit errors.
386If you’d prefer to fall back to standard speed rather than wait for fast mode capacity, catch the rate limit error and retry without `speed: "fast"`. On Claude in Microsoft Foundry, the deployment sets the speed, so retry on a deployment of the standard model instead. Set `max_retries` (typescript, php: `maxRetries`; java: `.maxRetries()`; csharp: `MaxRetries`; go: `option.WithMaxRetries()`) to `0` on the initial fast request to skip automatic retries and fail immediately on rate limit errors.
377387
378388<Note>
379389 Falling back from fast to standard speed results in a [prompt cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) miss. Requests at different speeds do not share cached prefixes.
from line 610
600610 use Anthropic\Core\Exceptions\RateLimitException;
601611 use Anthropic\Messages\Model;
602612 use Anthropic\RequestOptions;
603 // ...
613
604614 $client = new Client();
605615
606616 function createMessageWithFastFallback(
from line 702
692702
693703## Availability
694704
695Fast mode is available or in research preview on select models and eligible for zero data retention and HIPAA readiness.
705Fast mode is available or in research preview or deprecated on select models and eligible for zero data retention and HIPAA readiness.
696706
697707### API support
698708
from line 710
700710
701711To access fast mode on Claude Opus 5, contact your account manager or [join the waitlist](https://claude.com/fast-mode).
702712
703<Warning>
704 Fast mode on Claude Opus 4.8 is deprecated and will be removed on November 30, 2026. After removal, requests to `claude-opus-4-8` with `speed: "fast"` will return an error. To continue using fast mode, migrate to Claude Opus 5.5. See [Migrating to Claude Opus 5.5 from Claude Opus 4.8](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#migrating-from-claude-opus-4-8).
705</Warning>
706
707713#### [Messages API](https://platform.claude.com/docs/en/build-with-claude/working-with-messages)
708714
709715* Availability: Available
710716* Usage: Set `speed: "fast"` on the request.
711717
712| Status | Cloud platforms | Models |
713| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
714| Available | Claude API, [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed) | [Claude Fable 5.2](https://platform.claude.com/docs/en/models/fable-5-2/overview), [Claude Mythos 5.2](https://platform.claude.com/docs/en/models/mythos-5-2/overview) |
715| Available<sup>1</sup> | [Microsoft Foundry (hosted on Anthropic)](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry) | [Claude Fable 5.2](https://platform.claude.com/docs/en/models/fable-5-2/overview), [Claude Mythos 5.2](https://platform.claude.com/docs/en/models/mythos-5-2/overview) |
716| Available | Claude API, [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed) | [Claude Opus 5.5](https://platform.claude.com/docs/en/models/opus-5-5/overview) |
717| Available<sup>1</sup> | [Microsoft Foundry (hosted on Azure)](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry) | [Claude Opus 5.5](https://platform.claude.com/docs/en/models/opus-5-5/overview) |
718| Research preview | Claude API | [Claude Opus 5](https://platform.claude.com/docs/en/models/opus-5/overview), [Claude Opus 4.8](https://platform.claude.com/docs/en/models/opus-4-8/overview) |
718| Status | Cloud platforms | Models |
719| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
720| Available | Claude API, [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed) | [Claude Fable 5.2](https://platform.claude.com/docs/en/models/fable-5-2/overview), [Claude Mythos 5.2](https://platform.claude.com/docs/en/models/mythos-5-2/overview) |
721| Available<sup>1</sup> | [Microsoft Foundry (hosted on Anthropic)](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry) | [Claude Fable 5.2](https://platform.claude.com/docs/en/models/fable-5-2/overview), [Claude Mythos 5.2](https://platform.claude.com/docs/en/models/mythos-5-2/overview) |
722| Available | Claude API, [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed) | [Claude Opus 5.5](https://platform.claude.com/docs/en/models/opus-5-5/overview) |
723| Available<sup>1</sup> | [Microsoft Foundry (hosted on Azure)](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry) | [Claude Opus 5.5](https://platform.claude.com/docs/en/models/opus-5-5/overview) |
724| Research preview | Claude API | [Claude Opus 5](https://platform.claude.com/docs/en/models/opus-5/overview) |
725| Deprecated<sup>2</sup> | Claude API | [Claude Opus 4.8](https://platform.claude.com/docs/en/models/opus-4-8/overview) |
719726
7201. On Microsoft Foundry, fast mode is a separate model whose ID ends in `-fast`. Send requests to a deployment of that model, and leave out `speed`.
7271. On Microsoft Foundry, fast mode has its own model IDs, which end in `-fast`. Send requests to a deployment of the fast mode model, and leave out `speed`.
7282. Removal date: November 30, 2026. After removal, requests to `claude-opus-4-8` with `speed: "fast"` will return an error. To continue using fast mode, migrate to Claude Opus 5.5. See [Migrating to Claude Opus 5.5 from Claude Opus 4.8](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#migrating-from-claude-opus-4-8).
721729
722730#### [Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview)
723731
from line 732
724732* Availability: Available
725733* Usage: Set `speed` on the agent’s model object, for example `{"id": "claude-opus-5-5", "speed": "fast"}`.
726734
727| Status | Cloud platforms | Models |
728| ---------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
729| Available | Claude API | [Claude Opus 5.5](https://platform.claude.com/docs/en/models/opus-5-5/overview) |
730| Research preview | Claude API | [Claude Opus 5](https://platform.claude.com/docs/en/models/opus-5/overview), [Claude Opus 4.8](https://platform.claude.com/docs/en/models/opus-4-8/overview) |
735| Status | Cloud platforms | Models |
736| ---------------------- | --------------- | ------------------------------------------------------------------------------- |
737| Available | Claude API | [Claude Opus 5.5](https://platform.claude.com/docs/en/models/opus-5-5/overview) |
738| Research preview | Claude API | [Claude Opus 5](https://platform.claude.com/docs/en/models/opus-5/overview) |
739| Deprecated<sup>1</sup> | Claude API | [Claude Opus 4.8](https://platform.claude.com/docs/en/models/opus-4-8/overview) |
740
7411. Removal date: November 30, 2026. After removal, requests to `claude-opus-4-8` with `speed: "fast"` will return an error. To continue using fast mode, migrate to Claude Opus 5.5. See [Migrating to Claude Opus 5.5 from Claude Opus 4.8](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#migrating-from-claude-opus-4-8).
731742
732743### Required beta headers
733744
build-with-claude/handling-stop-reasons Changed · +5 / -5 lines
from line 888
888888
889889 <CodeGroup exclude="shell:cURL, shell:CLI">
890890 <CodeGroupItem language="cURL">
891 This workflow needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
891 This workflow needs more logic than a single shell command. Use the [Anthropic SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
892892 </CodeGroupItem>
893893
894894 <CodeGroupItem language="CLI">
895 This workflow needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
895 This workflow needs more logic than a single shell command. Use the [Anthropic SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
896896 </CodeGroupItem>
897897
898898 ```python Python
from line 1899
18991899
19001900On a refusal, the [`stop_details`](https://platform.claude.com/docs/en/api/messages/create#message.stop_details) object identifies the policy category that triggered it. The categories and the full refusal response shape are covered in [What a refusal looks like](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#refusal-response). `stop_details` is `null` for all stop reasons other than `refusal`.
19011901
1902You can usually get a response to a refused request by retrying it on another Claude model. This works for Claude Fable 5.2, Claude Fable 5.1, Claude Fable 5, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, and Claude Haiku 5.5. [Refusals and fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback) shows how to set up that retry, server-side or in your client. Claude Haiku 5.5 has no server-side fallback, so set up its retry with [client-side fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#client-side-fallback). If you build the retry yourself from any of these models except Claude Haiku 5.5, [fallback credit](https://platform.claude.com/docs/en/build-with-claude/fallback-credit) covers how to avoid paying the prompt-cache cost twice.
1902You can usually get a response to a refused request by retrying it on another Claude model. This works for Claude Fable 5.2, Claude Fable 5.1, Claude Fable 5, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, and Claude Haiku 5.5. [Refusals and fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback) shows how to set up that retry, server-side or in your client. Claude Haiku 5.5 has no server-side fallback, so set up its retry with [client-side fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#client-side-fallback). If you build the retry yourself from any of these models except Claude Haiku 5.5, [Fallback credit](https://platform.claude.com/docs/en/build-with-claude/fallback-credit) covers how to avoid paying the prompt-cache cost twice.
19031903
19041904### model\_context\_window\_exceeded
19051905
from line 2337
23372337
23382338<CodeGroup exclude="shell:cURL, shell:CLI">
23392339 <CodeGroupItem language="cURL">
2340 This workflow needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
2340 This workflow needs more logic than a single shell command. Use the [Anthropic SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
23412341 </CodeGroupItem>
23422342
23432343 <CodeGroupItem language="CLI">
2344 This workflow needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
2344 This workflow needs more logic than a single shell command. Use the [Anthropic SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
23452345 </CodeGroupItem>
23462346
23472347 ```python Python
build-with-claude/message-threads Changed · +8 / -5 lines
from line 228
228228 $second = $thread->send(['role' => 'user', 'content' => 'How long does standard shipping usually take?']);
229229
230230 foreach ($second->content as $block) {
231 if ($block instanceof BetaTextBlock) {
231 if ($block instanceof \Anthropic\Beta\Messages\BetaTextBlock) {
232232 echo $block->text, PHP_EOL;
233233 }
234234 }
from line 549
549549 );
550550
551551 foreach ($second->content as $block) {
552 if ($block instanceof BetaTextBlock) {
552 if ($block instanceof \Anthropic\Beta\Messages\BetaTextBlock) {
553553 echo $block->text, PHP_EOL;
554554 }
555555 }
from line 602
602602
603603To change a create-only or fixed field, start a new thread: send the full conversation in a create request with the new values.
604604
605On Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5, changing `system` or `tools` makes the `thinking` and `redacted_thinking` blocks already in the conversation invalid, and the create request can return a 400 error. To avoid it, leave every `thinking` and `redacted_thinking` block out of the conversation you send. The model then answers without that earlier reasoning. See [What counts as an edit](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#what-counts-as-an-edit), [When `prefix_mismatch_behavior` is unset](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#enforcement), and [What the API does with an invalid block](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#mismatch-behavior).
605**If you change `system` or `tools`:** On the following models, leave every `thinking` and `redacted_thinking` block out of the conversation that you send in the new create request: Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5. The model then answers without that earlier reasoning.
606606
607* **Why:** Changing `system` or `tools` makes the `thinking` and `redacted_thinking` blocks already in the conversation invalid. See [What counts as an edit](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#what-counts-as-an-edit).
608* **If you send the blocks anyway:** The create request can return a 400 error. Whether it does depends on the model and your account. See [When `prefix_mismatch_behavior` is unset](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#enforcement) and [What the API does with an invalid block](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#mismatch-behavior).
609
607610Send only the new messages on a continue request. The API doesn’t check them against the messages it already has. A message you send again can appear twice in the conversation, or the request can return an error. For example, a continue request that starts with the previous response returns an error.
608611
609612The new messages usually start with a `user` message: your next user turn, or the `tool_result` blocks that answer a `tool_use` in the previous response. If a response stops with [`stop_reason: "pause_turn"`](https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons#pause-turn), resume it with a continue request from that response’s `id` and an empty `messages` list (`"messages": []`). If that request returns a 404 error, replay the full conversation, including the paused response, in a new create request. Don’t send a new `user` message while the turn is paused: the API rejects it. With the SDK thread helper, call `send()` (go, csharp: `Send()`; ruby: `send_message()`) with no messages: the helper sends this request and replays on a 404 error.
from line 818
815818## See also
816819
817820* [Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)
818* [Streaming](https://platform.claude.com/docs/en/build-with-claude/streaming)
819* [Errors](https://platform.claude.com/docs/en/api/errors)
821* [Streaming messages](https://platform.claude.com/docs/en/build-with-claude/streaming)
822* [Claude API errors](https://platform.claude.com/docs/en/api/errors)
820823
821824## Availability
822825
build-with-claude/mid-conversation-effort-example Changed · +6 / -6 lines
from line 1444
14441444
14451445<CodeGroup exclude="shell:cURL, shell:CLI">
14461446 <CodeGroupItem language="cURL">
1447 The full example needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
1447 The full example needs more logic than a single shell command. Use the [Anthropic SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
14481448 </CodeGroupItem>
14491449
14501450 <CodeGroupItem language="CLI">
1451 The full example needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
1451 The full example needs more logic than a single shell command. Use the [Anthropic SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
14521452 </CodeGroupItem>
14531453
14541454 ```python Python
from line 2295
22952295
22962296<CodeGroup exclude="shell:cURL, shell:CLI">
22972297 <CodeGroupItem language="cURL">
2298 The full example needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
2298 The full example needs more logic than a single shell command. Use the [Anthropic SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
22992299 </CodeGroupItem>
23002300
23012301 <CodeGroupItem language="CLI">
2302 The full example needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
2302 The full example needs more logic than a single shell command. Use the [Anthropic SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
23032303 </CodeGroupItem>
23042304
23052305 ```python Python
from line 3839
38393839
38403840<CodeGroup exclude="shell:cURL, shell:CLI">
38413841 <CodeGroupItem language="cURL">
3842 The full example needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
3842 The full example needs more logic than a single shell command. Use the [Anthropic SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
38433843 </CodeGroupItem>
38443844
38453845 <CodeGroupItem language="CLI">
3846 The full example needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
3846 The full example needs more logic than a single shell command. Use the [Anthropic SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
38473847 </CodeGroupItem>
38483848
38493849 ```python Python
build-with-claude/mid-conversation-system-messages Changed · +15 / -8 lines
from line 22
2222 - claude-opus-4-8
2323 supportedPlatforms:
2424 Claude API: stable
25 Amazon Bedrock: stable
26 Amazon Bedrock (bedrock-runtime):
27 availability: stable
28 note: Through InvokeModel only (not Converse).
2529 Claude Platform on AWS: stable
2630 Claude Models on Google Cloud (Anthropic managed): stable
27 Amazon Bedrock: stable
2831 Claude Models on Google Cloud (Google managed): stable
2932---
3033
from line 41
3841Mid-conversation system messages close that gap. You append a `{"role": "system"}` message at the point in the conversation where the new instruction becomes relevant, instead of editing the top-level `system` field. The cached prefix stays the same, so the next request still reads it from cache, and the new instruction is still applied as a system instruction rather than as ordinary user text.
3942
4043<Note>
41 Mid-conversation system messages are available on Claude Fable 5.2, [Claude Mythos 5.2](https://platform.claude.com/docs/en/models/mythos-5-2/overview), Claude Fable 5.1, [Claude Mythos 5.1](https://platform.claude.com/docs/en/models/mythos-5-1/overview), Claude Fable 5, [Claude Mythos 5](https://platform.claude.com/docs/en/models/mythos-5/overview), Claude Opus 5.5, Claude Opus 4.8, Claude Opus 5, Claude Sonnet 5.5, and Claude Haiku 5.5. No beta header is required for mid-conversation system messages. This feature is not available on Claude Sonnet 5. Use the top-level `system` field there instead.
44 Mid-conversation system messages are available on Claude Fable 5.2, [Claude Mythos 5.2](https://platform.claude.com/docs/en/models/mythos-5-2/overview), Claude Fable 5.1, [Claude Mythos 5.1](https://platform.claude.com/docs/en/models/mythos-5-1/overview), Claude Fable 5, [Claude Mythos 5](https://platform.claude.com/docs/en/models/mythos-5/overview), Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Sonnet 5.5, and Claude Haiku 5.5. This feature is not available on Claude Sonnet 5. Use the top-level `system` field there instead.
4245
4346 [Mid-conversation tool changes](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#mid-conversation-tool-changes) are in beta on the same models. On the Claude API, Claude Platform on AWS, and Claude Models on Google Cloud (Anthropic managed), send the `inline-tools-2026-09-15` beta header, which also covers [defining a tool inside a `tool_addition` block](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#define-tools-in-a-message-beta). [Adding an MCP server that way](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#add-an-mcp-server-mid-conversation-beta) needs a second beta header, `mcp-client-2026-09-15`, which is available on the Claude API. The `mid-conversation-tool-changes-2026-07-01` header works for changes that name a tool by reference, on the Claude API, Amazon Bedrock, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed), and Claude Models on Google Cloud (Google managed).
4447
from line 1663
16601663
16611664You can still set the top-level `system` field for instructions that should apply to the entire conversation. Reserve mid-conversation system messages for instructions that only become relevant later, or that you want to add without invalidating the cached prefix.
16621665
1663A `role: "system"` message can also carry `output_config.effort` to change the [effort](https://platform.claude.com/docs/en/build-with-claude/effort) level partway through a conversation, in beta. See [Per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta).
1666A `role: "system"` message can also carry `output_config.effort` to change the [effort](https://platform.claude.com/docs/en/build-with-claude/effort) level partway through a conversation, in beta. See [Per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort-per-message).
16641667
16651668<CodeGroup>
16661669 ```bash cURL
from line 1956
19531956
19541957This example enables [automatic caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#automatic-caching) with the top-level `cache_control` field. Prompt caching is opt-in: if a request has no `cache_control` field (automatic or an [explicit breakpoint](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#explicit-cache-breakpoints)), nothing is cached and every request pays the regular input token price for the full conversation. With caching enabled, appending the system message leaves the already-cached turns unchanged, so the request that carries the new instruction still reads them from cache instead of processing them again. Caching also requires the conversation to meet the [minimum cacheable prompt length](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#cache-limitations); an example as short as this one falls below it, so `cache_creation_input_tokens` and `cache_read_input_tokens` stay at 0 until the conversation grows.
19551958
1956A mid-conversation system message that carries content (`text`, `tool_addition`, or `tool_removal` blocks) must immediately follow a `user` turn (or an `assistant` turn ending in a server tool result), and must either be the last entry in `messages` or be immediately followed by an `assistant` turn. A `user` message that carries `tool_result` blocks counts: in an agentic loop you can place the system message right after the tool results, before Claude’s next turn. Any other position for a message that carries content, including between an `assistant` `tool_use` block and the `tool_result` that answers it, returns a 400 error. A message with empty `content` that only sets [`output_config.effort`](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta) is accepted anywhere in `messages`. Consecutive `system` messages are judged together, so an effort-only message next to one that carries content follows the rule for content.
1959A mid-conversation system message that carries content (`text`, `tool_addition`, or `tool_removal` blocks) must immediately follow a `user` turn (or an `assistant` turn ending in a server tool result), and must either be the last entry in `messages` or be immediately followed by an `assistant` turn. A `user` message that carries `tool_result` blocks counts: in an agentic loop you can place the system message right after the tool results, before Claude’s next turn. Any other position for a message that carries content, including between an `assistant` `tool_use` block and the `tool_result` that answers it, returns a 400 error. A message with empty `content` that only sets [`output_config.effort`](https://platform.claude.com/docs/en/build-with-claude/effort-per-message) is accepted anywhere in `messages`. Consecutive `system` messages are judged together, so an effort-only message next to one that carries content follows the rule for content.
19571960
19581961### Placement after tool results
19591962
from line 2362
23592362## Limitations
23602363
23612364* **Not for the first message.** A `system` message that carries content cannot be the first entry in `messages`. Use the top-level `system` field for instructions that apply from the very start.
2362* **Placement is constrained.** A `system` message that carries content (`text`, `tool_addition`, or `tool_removal` blocks) must immediately follow a `user` turn (including a `user` turn that carries `tool_result` blocks) or an `assistant` turn ending in a server tool result, and must precede an `assistant` turn or end the array. It cannot sit between a `tool_use` block and its `tool_result`. Placing it elsewhere returns a 400 error. One exception: `tool_addition` and `tool_removal` blocks are not accepted immediately after a [paused](https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons#pause-turn) `assistant` turn (one ending in a server tool result), though `text` blocks are; resume the paused turn first, then send the tool change in the next `system` message. A message with empty `content` that only sets [`output_config.effort`](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta) renders nothing at its position and is accepted anywhere in `messages`, including first or between an `assistant` turn and a `user` turn. Consecutive `system` messages are judged together, so adding a text-carrying message next to an effort-only one makes the whole group follow the content rule.
2365* **Placement is constrained.** A `system` message that carries content (`text`, `tool_addition`, or `tool_removal` blocks) must immediately follow a `user` turn (including a `user` turn that carries `tool_result` blocks) or an `assistant` turn ending in a server tool result, and must precede an `assistant` turn or end the array. It cannot sit between a `tool_use` block and its `tool_result`. Placing it elsewhere returns a 400 error. One exception: `tool_addition` and `tool_removal` blocks are not accepted immediately after a [paused](https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons#pause-turn) `assistant` turn (one ending in a server tool result), though `text` blocks are; resume the paused turn first, then send the tool change in the next `system` message. A message with empty `content` that only sets [`output_config.effort`](https://platform.claude.com/docs/en/build-with-claude/effort-per-message) renders nothing at its position and is accepted anywhere in `messages`, including first or between an `assistant` turn and a `user` turn. Consecutive `system` messages are judged together, so adding a text-carrying message next to an effort-only one makes the whole group follow the content rule.
23632366* **Turn-scoped messages are text-only and re-sent verbatim.** A `clear_at: "next_user_message"` message carries no `tool_addition`, `tool_removal`, `output_config`, or `cache_control`, and once cleared it must stay in `messages` byte-for-byte on later requests. See [Turn-scoped system messages](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#turn-scoped-system-messages).
23642367* **Not a place for untrusted content.** Claude treats system content as operator instructions and follows it. Do not place text from outside the conversation, such as raw tool output, retrieved documents, or web content, directly in a system message; doing so gives that text operator-level authority. Keep that data in `tool_result` blocks and continue to follow [Mitigate jailbreaks and prompt injections](https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks).
23652368
from line 2401
23982401* Availability: Available
23992402* Usage: Append a message with `role` `"system"` to `messages` at the point where the instruction starts to apply.
24002403
2401| Status | Cloud platforms | Models |
2402| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
2403| Available | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed), [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed) | [Claude Fable 5.2](https://platform.claude.com/docs/en/models/fable-5-2/overview), [Claude Mythos 5.2](https://platform.claude.com/docs/en/models/mythos-5-2/overview), [Claude Fable 5.1](https://platform.claude.com/docs/en/models/fable-5-1/overview), [Claude Mythos 5.1](https://platform.claude.com/docs/en/models/mythos-5-1/overview), [Claude Fable 5](https://platform.claude.com/docs/en/models/fable-5/overview), [Claude Mythos 5](https://platform.claude.com/docs/en/models/mythos-5/overview), Claude Mythos Preview, [Claude Opus 5.5](https://platform.claude.com/docs/en/models/opus-5-5/overview), [Claude Opus 5](https://platform.claude.com/docs/en/models/opus-5/overview), [Claude Sonnet 5.5](https://platform.claude.com/docs/en/models/sonnet-5-5/overview), [Claude Haiku 5.5](https://platform.claude.com/docs/en/models/haiku-5-5/overview), [Claude Opus 4.8](https://platform.claude.com/docs/en/models/opus-4-8/overview) |
2404| Status | Cloud platforms | Models |
2405| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
2406| Available | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed) | [Claude Fable 5.2](https://platform.claude.com/docs/en/models/fable-5-2/overview), [Claude Mythos 5.2](https://platform.claude.com/docs/en/models/mythos-5-2/overview), [Claude Fable 5.1](https://platform.claude.com/docs/en/models/fable-5-1/overview), [Claude Mythos 5.1](https://platform.claude.com/docs/en/models/mythos-5-1/overview), [Claude Fable 5](https://platform.claude.com/docs/en/models/fable-5/overview), [Claude Mythos 5](https://platform.claude.com/docs/en/models/mythos-5/overview), Claude Mythos Preview, [Claude Opus 5.5](https://platform.claude.com/docs/en/models/opus-5-5/overview), [Claude Opus 5](https://platform.claude.com/docs/en/models/opus-5/overview), [Claude Sonnet 5.5](https://platform.claude.com/docs/en/models/sonnet-5-5/overview), [Claude Haiku 5.5](https://platform.claude.com/docs/en/models/haiku-5-5/overview), [Claude Opus 4.8](https://platform.claude.com/docs/en/models/opus-4-8/overview) |
2407| Available<sup>1</sup> | [Amazon Bedrock (bedrock-runtime)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy) | [Claude Fable 5.2](https://platform.claude.com/docs/en/models/fable-5-2/overview), [Claude Mythos 5.2](https://platform.claude.com/docs/en/models/mythos-5-2/overview), [Claude Fable 5.1](https://platform.claude.com/docs/en/models/fable-5-1/overview), [Claude Fable 5](https://platform.claude.com/docs/en/models/fable-5/overview), [Claude Opus 5.5](https://platform.claude.com/docs/en/models/opus-5-5/overview), [Claude Opus 5](https://platform.claude.com/docs/en/models/opus-5/overview), [Claude Sonnet 5.5](https://platform.claude.com/docs/en/models/sonnet-5-5/overview), [Claude Haiku 5.5](https://platform.claude.com/docs/en/models/haiku-5-5/overview), [Claude Opus 4.8](https://platform.claude.com/docs/en/models/opus-4-8/overview) |
2408| Available | [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock) | [Claude Fable 5.1](https://platform.claude.com/docs/en/models/fable-5-1/overview), [Claude Mythos 5.1](https://platform.claude.com/docs/en/models/mythos-5-1/overview), [Claude Fable 5](https://platform.claude.com/docs/en/models/fable-5/overview), [Claude Mythos 5](https://platform.claude.com/docs/en/models/mythos-5/overview), [Claude Opus 5.5](https://platform.claude.com/docs/en/models/opus-5-5/overview), [Claude Opus 5](https://platform.claude.com/docs/en/models/opus-5/overview), [Claude Sonnet 5.5](https://platform.claude.com/docs/en/models/sonnet-5-5/overview), [Claude Haiku 5.5](https://platform.claude.com/docs/en/models/haiku-5-5/overview), [Claude Opus 4.8](https://platform.claude.com/docs/en/models/opus-4-8/overview) |
2409
24101. Through InvokeModel only (not Converse).
24042411
24052412#### [Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview)
24062413
build-with-claude/multilingual-support Changed · +5 / -5 lines
from line 26
2626 - claude-sonnet-4-5-20250929
2727 supportedPlatforms:
2828 Claude API: stable
29 Claude Platform on AWS: stable
3029 Amazon Bedrock: stable
31 Amazon Bedrock (InvokeModel): stable
30 Amazon Bedrock (bedrock-runtime): stable
31 Claude Platform on AWS: stable
3232 Claude Models on Google Cloud (Google managed): stable
3333 Microsoft Foundry: stable
3434---
from line 254
254254
255255* Availability: Always on
256256
257| Status | Cloud platforms |
258| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
259| Available | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), [Amazon Bedrock (InvokeModel)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed), [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry) |
257| Status | Cloud platforms |
258| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
259| Available | Claude API, [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), [Amazon Bedrock (bedrock-runtime)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy), [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed), [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry) |
260260
261261#### [Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview)
262262
build-with-claude/overview Changed · +5 / -5 lines
from line 27
2727| [Browser use tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/browser-use-tool) | Lets Claude navigate, read, and interact with webpages in your own browser environment. |
2828| [Citations](https://platform.claude.com/docs/en/build-with-claude/citations) | Claude’s answers about your documents cite the exact passages that support each claim. |
2929| [Classifier refusals](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback) | Safety classifiers on some models can decline a request; the decline comes back as a normal response, not an error. |
30| ↳ [Client-side fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#client-side-fallback) | A middleware in the Claude SDKs that retries a refused request on the fallback models you list. |
30| ↳ [Client-side fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#client-side-fallback) | A middleware in the Anthropic SDKs that retries a refused request on the fallback models you list. |
3131| ↳ [Fallback credit](https://platform.claude.com/docs/en/build-with-claude/fallback-credit) | Bills a retry of a refused request on another model as if the conversation had been on that model from the start, so you do not pay the prompt-cache write twice. |
3232| ↳ [Server-side fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#server-side-fallback) | The API retries a refused request on a fallback model within the same call and returns one response. |
3333| [Computer use tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool) | Gives Claude screenshot, mouse, and keyboard control of a desktop environment. |
from line 34
3434| [Custom tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools) | Tools you define with a name, description and input schema. Claude asks to call them; your code runs them and returns the result. |
3535| [Data residency](https://platform.claude.com/docs/en/manage-claude/data-residency) | Controls for where model inference runs (inference geo) and where data is stored at rest (workspace geo). |
3636| [Effort](https://platform.claude.com/docs/en/build-with-claude/effort) | A setting that controls how many tokens Claude spends on a response, trading thoroughness for token efficiency. |
37| ↳ [Per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta) | Changing the effort level for later turns of a conversation with a per-message `output_config`, which keeps the prompt cache. |
37| ↳ [Per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort-per-message) | Changing the effort level for later turns of a conversation with a per-message `output_config`, which keeps the prompt cache. |
3838| [Fast mode](https://platform.claude.com/docs/en/build-with-claude/fast-mode) | Up to 2.5 times more output tokens per second from supported models, at premium pricing. |
3939| [Files API](https://platform.claude.com/docs/en/build-with-claude/files) | Upload a file once and refer to it by `file_id` in later requests, and download files that skills or the code execution tool create. |
4040| [MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector) | Connect Claude to remote MCP servers so it can call their tools, without running your own MCP client. |
from line 44
4444| ↳ [Mid-conversation tool changes](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#mid-conversation-tool-changes) | Offer or withdraw tools partway through a conversation without changing the tools array, so the cached prefix stays valid. |
4545| ↳ [Turn-scoped system messages](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#turn-scoped-system-messages) | A mid-conversation system message that applies only until the next user message, then stays in the history but renders nothing and costs no input tokens. |
4646| [Multilingual support](https://platform.claude.com/docs/en/build-with-claude/multilingual-support) | Claude works in many languages, with strong performance relative to English. |
47| [OpenTelemetry](https://platform.claude.com/docs/en/manage-claude/opentelemetry) | Traces your Messages API requests, tool uses, and Managed Agents sessions with OpenTelemetry spans from the Claude SDK and the Claude API. |
47| [OpenTelemetry](https://platform.claude.com/docs/en/manage-claude/opentelemetry) | Traces your Messages API requests, tool uses, and Managed Agents sessions with OpenTelemetry spans from the Anthropic SDK and the Claude API. |
4848| ↳ [API tracing](https://platform.claude.com/docs/en/manage-claude/opentelemetry/api) | OpenTelemetry spans that the Claude API sends to your observability platform for each model request and tool use that it runs. |
49| ↳ [SDK tracing](https://platform.claude.com/docs/en/manage-claude/opentelemetry/sdk) | OpenTelemetry spans that the Claude SDK emits in your application for each request it sends and each tool that its tool runner runs. |
49| ↳ [SDK tracing](https://platform.claude.com/docs/en/manage-claude/opentelemetry/sdk) | OpenTelemetry spans that the Anthropic SDK emits in your application for each request it sends and each tool that its tool runner runs. |
5050| [Parallel tool use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/parallel-tool-use) | Claude can call several tools in one response. |
5151| [PDF support](https://platform.claude.com/docs/en/build-with-claude/pdf-support) | Send PDFs to Claude so it can read the text, pictures, charts and tables in them. |
5252| [Programmatic tool calling](https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling) | Lets Claude call your tools from code in the code execution container, instead of one model round trip for each call. |
from line 56
5656| ↳ [Automatic caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#automatic-caching) | Prompt caching with one top-level `cache_control` field: the cache breakpoint goes on the last cacheable block and moves forward as the conversation grows. |
5757| ↳ [Cache diagnostics](https://platform.claude.com/docs/en/build-with-claude/cache-diagnostics) | Compares a request with your previous one and reports where the prompt prefix changed, to explain cache misses. |
5858| ↳ [Explicit cache breakpoints](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#explicit-cache-breakpoints) | Prompt caching with `cache_control` on individual content blocks, to choose exactly what is cached. |
59| [SDK middleware](https://platform.claude.com/docs/en/cli-sdks-libraries/middleware) | A hook in the Claude SDKs that runs your code before each request is sent and after its response is received. |
59| [SDK middleware](https://platform.claude.com/docs/en/cli-sdks-libraries/middleware) | A hook in the Anthropic SDKs that runs your code before each request is sent and after its response is received. |
6060| [Search results](https://platform.claude.com/docs/en/build-with-claude/search-results) | Content blocks that hold your own search results, with a source and title, so Claude can cite them the same way it cites web search results. |
6161| [Service tiers](https://platform.claude.com/docs/en/api/service-tiers) | Lets a request use your organization’s Priority Tier capacity. |
6262| [Session budgets](https://platform.claude.com/docs/en/managed-agents/budgets) | A hard spending limit in US dollars on one session, measured at public list prices. |
build-with-claude/pdf-support Changed · +4 / -4 lines
from line 29
2929 - claude-sonnet-4-5-20250929
3030 supportedPlatforms:
3131 Claude API: stable
32 Claude Platform on AWS: stable
33 Claude Models on Google Cloud (Anthropic managed): stable
3432 Amazon Bedrock:
3533 availability: stable
3634 note: Base64 sources only.
37 Amazon Bedrock (InvokeModel):
35 Amazon Bedrock (bedrock-runtime):
3836 availability: stable
3937 note: Base64 sources only.
38 Claude Platform on AWS: stable
39 Claude Models on Google Cloud (Anthropic managed): stable
4040 Claude Models on Google Cloud (Google managed):
4141 availability: stable
4242 note: Base64 sources only.
from line 1995
19951995| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
19961996| Available | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed) |
19971997| Available<sup>1</sup> | [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry) |
1998| Available<sup>2</sup> | [Amazon Bedrock (InvokeModel)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy) |
1998| Available<sup>2</sup> | [Amazon Bedrock (bedrock-runtime)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy) |
19991999| Available<sup>2</sup> | [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed) |
20002000
200120011. `file_id` sources need a Hosted on Anthropic deployment.
build-with-claude/preserved-thinking Changed · +75 / -55 lines
from line 1
11---
22title: Preserved thinking
33url: https://platform.claude.com/docs/en/build-with-claude/preserved-thinking
4description: On the latest Claude models, preserved thinking determines whether the model can use a thinking block you send back from an earlier turn.
4description: On Claude models that run the prefix check, preserved thinking determines whether the model can use a thinking block you send back from an earlier turn.
55featureMetadata:
66 status: stable
77 supportedModels:
from line 14
1414 - claude-haiku-5-5
1515 supportedPlatforms:
1616 Claude API: stable
17 Amazon Bedrock: stable
18 Amazon Bedrock (bedrock-runtime): stable
1719 Claude Platform on AWS: stable
1820 Claude Models on Google Cloud (Anthropic managed): stable
19 Amazon Bedrock: stable
2021 Claude Models on Google Cloud (Google managed): stable
2122 Microsoft Foundry: stable
2223---
from line 42
4142
4243On the Claude API, if a request fails the prefix check and leaves [`prefix_mismatch_behavior`](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#mismatch-behavior) unset, whether it gets an error depends on the model and the account:
4344
44| Model | Account created | Account created |
45| ----------------- | --------------------------- | ----------------------------------------- |
46| Name | On or after August 31, 2026 | Before August 31, 2026 |
47| Claude Fable 5.2 | 400 error | 400 error |
48| Claude Mythos 5.2 | 400 error | 400 error |
49| Claude Fable 5.1 | 400 error | No error (failing blocks reach the model) |
50| Claude Mythos 5.1 | 400 error | 400 error |
51| Claude Opus 5.5 | 400 error | No error (failing blocks reach the model) |
52| Claude Sonnet 5.5 | 400 error | No error (failing blocks reach the model) |
53| Claude Haiku 5.5 | 400 error | No error (failing blocks reach the model) |
45| Model | Account created | Account created |
46| ----------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
47| Name | On or after August 31, 2026 | Before August 31, 2026 |
48| Claude Fable 5.2 | Enforced (400 error) | Enforced (400 error) |
49| Claude Mythos 5.2 | Enforced (400 error) | Enforced (400 error) |
50| Claude Fable 5.1 | Enforced (400 error) | [Enforcement varies by account](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#enforcement-details) |
51| Claude Mythos 5.1 | Enforced (400 error) | Enforced (400 error) |
52| Claude Opus 5.5 | Enforced (400 error) | [Enforcement varies by account](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#enforcement-details) |
53| Claude Sonnet 5.5 | Enforced (400 error) | [Enforcement varies by account](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#enforcement-details) |
54| Claude Haiku 5.5 | Enforced (400 error) | [Enforcement varies by account](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#enforcement-details) |
5455
55The cutoff is 00:00 UTC on August 31, 2026. In the Message Batches API, an item that leaves the field unset doesn’t get the 400 error. For this and for how to tell which column your account is in, see [What else happens when `prefix_mismatch_behavior` is unset](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#enforcement-details).
56The dates in the table are at 00:00 UTC.
5657
58Where enforcement varies by account, a request that fails the prefix check can get either a 400 error or no error. When no error is returned, the failing blocks reach the model. To find out which behavior your account gets, [test your account](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#enforcement-details). To get the same result on every account, make your integration append-only or set `prefix_mismatch_behavior`. Otherwise, your code must handle both behaviors.
59
60In the Message Batches API, an item that leaves the field unset doesn’t get the 400 error. For this and for how to tell which outcome your account gets, see [What else happens when `prefix_mismatch_behavior` is unset](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#enforcement-details).
61
5762### What to check in your integration
5863
5964If your code builds or rewrites requests itself, check it if, between two requests in one conversation, it does any of the following:
from line 77
7277| Uses the MCP connector with an unpinned tool list that changes between requests, which affects thinking blocks from the models named in [What counts as an edit](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#what-counts-as-an-edit) | On the Claude API, [pin the server’s tool list](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector#pin-mcp-tool-list). |
7378| Rewrites someone else’s requests as a library, proxy, or gateway between their history and the API | Follow [Libraries, proxies, and gateways](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#libraries-proxies-gateways). |
7479
75A run with no errors on your own API key doesn’t prove that your code keeps the prefix intact. When a request leaves `prefix_mismatch_behavior` unset, failing blocks reach the model without an error wherever the table in [When `prefix_mismatch_behavior` is unset](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#enforcement) shows no error. People who run your tool with their own API keys can get a 400 error even when you don’t. To see the error from your account, set `prefix_mismatch_behavior` to `"error"` on your test requests, as [Check whether your code edits the prefix](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#how-to-tell-whether-your-integration-is-impacted) shows.
80A run with no errors on your own API key doesn’t prove that your code keeps the prefix intact. When a request to Claude Fable 5.1, Claude Opus 5.5, Claude Sonnet 5.5, or Claude Haiku 5.5 leaves `prefix_mismatch_behavior` unset, failing blocks can reach the model without an error, [depending on the account](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#enforcement). People who run your tool with their own API keys can get a 400 error even when you don’t. To see the error from your account, set `prefix_mismatch_behavior` to `"error"` on your test requests, as [Check whether your code edits the prefix](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#how-to-tell-whether-your-integration-is-impacted) shows.
7681
7782Also check your integration if it sends Claude Sonnet 5.5, Claude Haiku 5.5, Claude Fable 5.2, or Claude Mythos 5.2 thinking blocks from one account in a request made by a different account. See [Thinking blocks stay with the account that produced them](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#account-bound-thinking).
7883
from line 89
8489* The set of `tools`
8590* Every `message` before the block
8691
87With server-side [compaction](https://platform.claude.com/docs/en/build-with-claude/compaction), the checked prefix starts at the most recent compaction block.
92With [compaction at a token threshold](https://platform.claude.com/docs/en/build-with-claude/compaction-threshold), the API checks `messages` only from the most recent compaction block. It still checks `system` and `tools`.
8893
8994Request parameters outside those three fields, such as `effort`, `max_tokens`, `output_config`, `tool_choice`, and `metadata`, aren’t part of the prefix check, and neither are `cache_control` markers. [What counts as an edit](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#what-counts-as-an-edit) has the full list.
9095
from line 102
97102On the Claude API, the prefix check always runs on these models. Set `thinking.block_binding.prefix_mismatch_behavior` to choose what happens to a block that fails it. The field and the `input_transformations` array require the `thinking-binding-controls-2026-08-01` [beta header](https://platform.claude.com/docs/en/api/beta-headers). [Set the mismatch behavior and read `input_transformations`](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#preserved-thinking-controls) shows the request in each SDK.
98103
99104* **`"error"`:** The API rejects the request with a 400 `invalid_request_error` that names the first failing block.
100* **`"drop_block"`:** The API drops each failing block and every thinking block after it, and the request succeeds. Dropped blocks aren’t billed. The model answers that turn without using reasoning from dropped blocks, and the prompt cache restarts at the edit. The response lists each dropped block in `input_transformations` (on the `message_start` event when streaming) with `reason: "prefix_binding_mismatch"`. It’s a stopgap with an [output-token cost](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#drop-block-cost).
105* **`"drop_block"`:** The API drops each failing block, and the request succeeds. Dropped blocks aren’t billed. The model answers that turn without using reasoning from dropped blocks, and the prompt cache restarts at the edit. The response lists each dropped block in `input_transformations` (on the `message_start` event when streaming) with `reason: "prefix_binding_mismatch"`. It’s a stopgap with an [output-token cost](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#drop-block-cost).
101106
102107#### What else happens when `prefix_mismatch_behavior` is unset
103108
104The table in [When `prefix_mismatch_behavior` is unset](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#enforcement) gives the outcome for each model and account.
109The table in [When `prefix_mismatch_behavior` is unset](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#enforcement) lists the outcomes for each model and account.
105110
106111A failing block that reaches the model is read and billed like any other input. With the beta header, the response lists each one in `input_transformations` as `thinking_mismatch_allowed`.
107112
108In the Message Batches API, an item that leaves the field unset doesn’t fail: where the table shows a 400 error, the API drops the failing blocks instead. An item that sets the field to `"error"` and sends a failing block resolves as `errored`.
113In the Message Batches API, an item that leaves the field unset doesn’t fail: where the same request outside a batch would get a 400 error, the API drops the failing blocks instead. An item that sets the field to `"error"` and sends a failing block resolves as `errored`.
109114
110To find out which column your account is in, take a Claude Fable 5.1 conversation that contains a thinking block and change something before that block. Send it to Claude Fable 5.1 without the beta header or the `block_binding` field. A 400 error that names the header means your requests get the outcome in the “on or after August 31, 2026” column. A 200 response means they get the outcome in the “before August 31, 2026” column. To confirm a 200 result, send the same request again with the beta header and without `block_binding`: the response lists every thinking block after your edit in `input_transformations` as `thinking_mismatch_allowed`.
115To find out which outcome your account gets, take a Claude Fable 5.1 conversation that contains a thinking block and change something before that block. Send it to Claude Fable 5.1 without the beta header or the `block_binding` field. A 400 error that names the header means that your account gets the error. A 200 response means that it gets no error. To confirm a 200 result, send the same request again with the beta header and without `block_binding`: the response lists every thinking block after your edit in `input_transformations` as `thinking_mismatch_allowed`.
111116
112117#### The 400 error
113118
from line 183
178183 ```
179184
180185 ```bash CLI
181 ant beta:messages create --beta thinking-binding-controls-2026-08-01 \
182 --format yaml <<'YAML'
186 ant beta:messages create --beta thinking-binding-controls-2026-08-01 <<'YAML'
183187 model: claude-fable-5-1
184188 max_tokens: 16000
185189 thinking:
from line 349
345349
346350 ```php PHP
347351 use Anthropic\Beta\AnthropicBeta;
352 use Anthropic\Beta\Messages\BetaTextBlock;
348353 use Anthropic\Beta\Messages\BetaThinkingBlockBinding;
349354 use Anthropic\Beta\Messages\BetaThinkingConfigAdaptive;
350355 use Anthropic\Beta\Messages\BetaThinkingPrefixMismatchBehavior;
351356 use Anthropic\Client;
357 use Anthropic\Messages\Model;
352358
353359 $client = new Client();
354360
355361 $response = $client->beta->messages->create(
356 model: 'claude-fable-5-1',
362 model: Model::CLAUDE_FABLE_5_1,
357363 maxTokens: 16000,
358364 thinking: BetaThinkingConfigAdaptive::with(
359365 blockBinding: BetaThinkingBlockBinding::with(
from line 373
367373 );
368374
369375 foreach ($response->content as $block) {
370 if ($block->type === 'text') {
376 if ($block instanceof BetaTextBlock) {
371377 echo $block->text, PHP_EOL;
372378 }
373379 }
from line 398
392398 )
393399
394400 response.content.each do |block|
395 puts block.text if block.type == :text
401 puts block.text if block.is_a?(Anthropic::Beta::BetaTextBlock)
396402 end
397403
398404 puts "Input transformations: #{response.input_transformations&.length || 0}"
from line 413
407413Under the beta header, every response from a thinking-capable model carries `input_transformations`. Each entry names one thinking block by its `path` (for example `messages.1.content.0`) and gives a `reason`. There are two entry types:
408414
409415* **`thinking_dropped`:** The API drops the block before the model reads it, and the block isn’t billed. The `reason` is `prefix_binding_mismatch` or `model_binding_mismatch` (see [Switching models mid-conversation](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models)). The `reason` can also be `organization_binding_mismatch`, which means the block came from another account (see [Thinking blocks stay with the account that produced them](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#account-bound-thinking)).
410* **`thinking_mismatch_allowed`:** The block fails the prefix check, but the API lets it through for this request, so the block reaches the model unchanged and is billed. The `reason` is always `prefix_binding_mismatch`. This entry appears only on requests that leave `prefix_mismatch_behavior` unset, where the table in [When `prefix_mismatch_behavior` is unset](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#enforcement) shows no error. A request that sets the field never gets this entry.
416* **`thinking_mismatch_allowed`:** The block fails the prefix check, but the API lets it through for this request, so the block reaches the model unchanged and is billed. The `reason` is always `prefix_binding_mismatch`. This entry appears only on requests that leave `prefix_mismatch_behavior` unset, on the models and accounts where [failing blocks reach the model](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#enforcement). A request that sets the field never gets this entry.
411417
412418The array is empty when no block was dropped and none failed the prefix check. Ignore entries whose `type` or `reason` you don’t recognize, because later checks add values.
413419
from line 421
415421
416422### What counts as an edit
417423
418Each row compares a request with the one before it. “Later thinking blocks” means the blocks already in the history that come after the changed content:
424Each row is a change made after a thinking block was produced. “Later thinking blocks” means the blocks already in the history that come after the changed content:
419425
420426| Change between requests | Later thinking blocks |
421427| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
from line 432
426432| Change `model` | Valid for blocks that the new model can read; the API drops the others without an error (see [Switching models mid-conversation](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models)) |
427433| Add, move, or remove `cache_control` markers | Valid |
428434| A rotating signed URL that returns the same bytes | Valid |
429| Server-side compaction or context editing removes or replaces content | Valid (the check compares what you sent, not the server’s edited copy) |
435| [Compaction at a token threshold](https://platform.claude.com/docs/en/build-with-claude/compaction-threshold) or context editing removes or replaces content | Valid (the check compares what you sent, not the server’s edited copy) |
430436| A cleared [turn-scoped system message](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#per-turn-reminders) left in place | Valid |
431437| Edit, reorder, or delete any earlier `user`, `assistant`, or `system` message | Invalid, except when the signed block from [on-demand compaction](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand) replaces the messages it summarizes, under the [conditions for kept thinking](https://platform.claude.com/docs/en/build-with-claude/compaction-thinking-blocks#conditions-for-kept-thinking-to-stay-valid) |
432438| Re-render the context you put in the first user message with a changed value | Invalid for every thinking block |
from line 439
433439| Clear or shorten an earlier `tool_result`, re-encode an earlier image, or change an earlier `tool_use` input | Invalid for every later thinking block |
434440| Add a text block to an earlier user turn, or remove one you added last time | Invalid |
435441| Change the top-level `system` string or blocks | Invalid |
436| Add, remove, rename, or edit a tool in `tools` | Invalid |
442| Add, remove, rename, or edit a tool in `tools` | Invalid, except for a deferred tool that nothing has referenced |
437443| Remove a `thinking` block from the middle of the history and keep later ones | Invalid for every later thinking block |
438444| Put back a `thinking` block you removed on an earlier request | Invalid for thinking blocks produced while it was gone |
439445| An image or document URL that returns different bytes on the next request | Invalid |
from line 456
450456
451457<CodeGroup exclude="shell:cURL, shell:CLI">
452458 <CodeGroupItem language="cURL">
453 This workflow needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
459 This workflow needs more logic than a single shell command. Use the [Anthropic SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
454460 </CodeGroupItem>
455461
456462 <CodeGroupItem language="CLI">
457 This workflow needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
463 This workflow needs more logic than a single shell command. Use the [Anthropic SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
458464 </CodeGroupItem>
459465
460466 ```python Python
from line 642
636642
637643 ```php PHP
638644 use Anthropic\Beta\AnthropicBeta;
645 use Anthropic\Beta\Messages\BetaThinkingBlock;
639646 use Anthropic\Beta\Messages\BetaThinkingBlockBinding;
640647 use Anthropic\Beta\Messages\BetaThinkingConfigAdaptive;
641648 use Anthropic\Beta\Messages\BetaThinkingPrefixMismatchBehavior;
642649 use Anthropic\Client;
650 use Anthropic\Messages\Model;
643651
644652 $client = new Client();
645653
from line 661
653661 foreach ($userTurns as $userTurn) {
654662 $messages[] = ['role' => 'user', 'content' => $userTurn];
655663 $response = $client->beta->messages->create(
656 model: 'claude-fable-5-1',
664 model: Model::CLAUDE_FABLE_5_1,
657665 maxTokens: 16000,
658666 thinking: BetaThinkingConfigAdaptive::with(
659667 blockBinding: BetaThinkingBlockBinding::with(
from line 672
664672 betas: [AnthropicBeta::THINKING_BINDING_CONTROLS_2026_08_01],
665673 );
666674 $messages[] = ['role' => 'assistant', 'content' => $response->content];
667 $thinkingBlocks = array_filter($response->content, fn ($block) => $block->type === 'thinking');
675 $thinkingBlocks = array_filter($response->content, fn ($block) => $block instanceof BetaThinkingBlock);
668676 $dropped = $response->inputTransformations ?? [];
669677 echo 'thinking blocks: ', count($thinkingBlocks), ', dropped: ', count($dropped), PHP_EOL;
670678 }
from line 734
726734* **`reason: "model_binding_mismatch"`:** The conversation moved to a model that can’t read the earlier model’s blocks. This isn’t a prefix edit. See [Switching models mid-conversation](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models).
727735* **`reason: "organization_binding_mismatch"`:** The block came from another account. See [Thinking blocks stay with the account that produced them](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#account-bound-thinking).
728736
729To see a failure on purpose, send a third turn from the earlier example and add a `system` prompt to that request only, so that it differs from the first two requests, which had none. With `"drop_block"`, the dropped count is no longer 0: the response has one entry for each thinking block in the history, each with `reason: "prefix_binding_mismatch"`. With `"error"`, the request returns the 400 error described in [What the API does with an invalid block](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#mismatch-behavior), and its last sentence names the `system` prompt. If the count is still 0, there was nothing to check: confirm that the model is claude-fable-5-1, claude-fable-5-2, or claude-mythos-5-2, that the request sets `block_binding`, that the history you sent contains `thinking` blocks, and that the first two requests had no `system` prompt.
737To see a failure on purpose, send a third turn from the earlier example and add a `system` prompt to that request only, so that it differs from the first two requests, which had none. With `"drop_block"`, the dropped count is no longer 0: the response has one entry for each thinking block in the history, each with `reason: "prefix_binding_mismatch"`. With `"error"`, the request returns the 400 error described in [What the API does with an invalid block](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#mismatch-behavior), and its last sentence names the `system` prompt. If the count is still 0, there was nothing to check: confirm that the model runs the [prefix check](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#prefix-check), that the request sets `block_binding`, that the history you sent contains `thinking` blocks, and that the first two requests had no `system` prompt.
730738
731739Two plain turns rarely show the problem. Run a session through each of the following, with `"error"` set so that a regression fails your CI:
732740
from line 745
737745* A switch to another model and back
738746* A save, a restart, and a resume on a later date
739747
740Where the table in [When `prefix_mismatch_behavior` is unset](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#enforcement) shows no error, you can also watch production traffic: send the beta header, leave `block_binding` out, and log `input_transformations`. Sending the header alone doesn’t change what the model receives. Every thinking block that comes after the content you edited fails the check and gets its own `thinking_mismatch_allowed` entry, with the same `path` and `reason` fields as a `thinking_dropped` entry. Blocks before the edit pass. An edit to `system` or `tools` comes before every block, so every thinking block in the request fails the check. One entry looks like this:
748If [failing blocks reach the model](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#enforcement) for your requests, you can also watch production traffic: send the beta header, leave `block_binding` out, and log `input_transformations`. Sending the header alone doesn’t change what the model receives. Every thinking block already in the history after the content you edited fails the check and gets its own `thinking_mismatch_allowed` entry, with the same `path` and `reason` fields as a `thinking_dropped` entry. Blocks before the edit pass. An edit to `system` or `tools` comes before every block, so every thinking block already in the history fails the check. One entry looks like this:
741749
742750```json
743751{
from line 759
751759}
752760```
753761
754Run the following example from an [account created before August 31, 2026](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#enforcement), because on an account created on or after that date, the API rejects its third request with a 400 error. Keep the example on Claude Fable 5.1: on Claude Fable 5.2 and Claude Mythos 5.2, the third request gets the 400 error on every account. It sends the header without `block_binding` and extends the earlier session with a third request that adds a system prompt, which changes the prefix on purpose. After each turn it prints the number of `thinking` blocks and flagged blocks:
762Run the following example on Claude Fable 5.1 from an account where [failing blocks reach the model](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#enforcement). On any other account, the API rejects its third request with a 400 error. On Claude Fable 5.2 and Claude Mythos 5.2, the third request gets the 400 error on every account. The example sends the header without `block_binding` and extends the earlier session with a third request that adds a system prompt, which changes the prefix on purpose. After each turn it prints the number of `thinking` blocks and flagged blocks:
755763
756764<CodeGroup exclude="shell:cURL, shell:CLI">
757765 <CodeGroupItem language="cURL">
758 This workflow needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
766 This workflow needs more logic than a single shell command. Use the [Anthropic SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
759767 </CodeGroupItem>
760768
761769 <CodeGroupItem language="CLI">
762 This workflow needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
770 This workflow needs more logic than a single shell command. Use the [Anthropic SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
763771 </CodeGroupItem>
764772
765773 ```python Python
from line 882
874882
875883 // messages grows across turns: each assistant turn goes back exactly as returned
876884 messages := []anthropic.BetaMessageParam{}
877 for i, userTurn := range userTurns {
885 for turnIndex, userTurn := range userTurns {
878886 messages = append(messages, anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock(userTurn)))
879887 // Only the last request adds a system prompt, which changes the prefix on purpose
880888 var system []anthropic.BetaTextBlockParam
881 if i == len(userTurns)-1 {
889 if turnIndex == len(userTurns)-1 {
882890 system = []anthropic.BetaTextBlockParam{{Text: "Answer briefly."}}
883891 }
884892 response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
from line 965
957965
958966 ```php PHP
959967 use Anthropic\Beta\AnthropicBeta;
968 use Anthropic\Beta\Messages\BetaThinkingBlock;
960969 use Anthropic\Beta\Messages\BetaThinkingConfigAdaptive;
961970 use Anthropic\Beta\Messages\BetaThinkingMismatchAllowedInputTransformation;
962971 use Anthropic\Client;
972 use Anthropic\Messages\Model;
963973
964974 $client = new Client();
965975
from line 984
974984 foreach ($userTurns as $turnIndex => $userTurn) {
975985 $messages[] = ['role' => 'user', 'content' => $userTurn];
976986 $response = $client->beta->messages->create(
977 model: 'claude-fable-5-1',
987 model: Model::CLAUDE_FABLE_5_1,
978988 maxTokens: 16000,
979989 thinking: BetaThinkingConfigAdaptive::with(),
980990 // Only the last request adds a system prompt, which changes the prefix on purpose
from line 993
983993 betas: [AnthropicBeta::THINKING_BINDING_CONTROLS_2026_08_01],
984994 );
985995 $messages[] = ['role' => 'assistant', 'content' => $response->content];
986 $thinkingBlocks = array_filter($response->content, fn ($block) => $block->type === 'thinking');
996 $thinkingBlocks = array_filter($response->content, fn ($block) => $block instanceof BetaThinkingBlock);
987997 $flagged = array_filter(
988998 $response->inputTransformations ?? [],
989999 fn ($transformation) => $transformation instanceof BetaThinkingMismatchAllowedInputTransformation,
from line 1043
10331043
10341044The third response flags every thinking block from the earlier turns, one for each turn in this run, because the new system prompt comes before all of them. The model still read them.
10351045
1036Handle these entries as you would `prefix_binding_mismatch` drops. The edit is before the first block listed: diff `system`, `tools`, and `messages` up to that block’s `path` against the previous request to find it, then replace it with the matching pattern in [Make changes without editing the prefix](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#replace-prefix-edits). If the request sets `prefix_mismatch_behavior`, or if the table in [When `prefix_mismatch_behavior` is unset](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#enforcement) shows a 400 error for your model and account, the API instead rejects the request or drops the failing blocks. The entries are a lower bound on what `"drop_block"` would remove. With `"drop_block"`, a failing block also takes the rest of that turn’s thinking blocks with it, and removing one block can make the next one fail too. When the API lets failing blocks through, it evaluates each block on its own and lists a block only if that block fails.
1046Handle these entries as you would `prefix_binding_mismatch` drops. The edit is before the first block listed. To find it, diff `system`, `tools`, and `messages` up to that block’s `path` against the conversation as it stood when Claude produced that block. Then replace the edit with the matching pattern in [Make changes without editing the prefix](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#replace-prefix-edits). If the request sets `prefix_mismatch_behavior`, or if [your model and account get the 400 error](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#enforcement), the API instead rejects the request or drops the failing blocks. The entries are a lower bound on what `"drop_block"` would remove. With `"drop_block"`, a failing block also takes the rest of that turn’s consecutive thinking blocks with it, and removing one block can make the next one fail too. When the API lets failing blocks through, it evaluates each block on its own and lists a block only if that block fails.
10371047
10381048## Make changes without editing the prefix
10391049
from line 1230
12201230
12211231If the API connects to the MCP server for you through the [MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector), also send `mcp-client-2026-09-15`. It covers everything `mcp-client-2025-11-20` does, so send it instead of that one. The block’s `definition` can then be an [`mcp_toolset` for a server listed in `mcp_servers`](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#add-an-mcp-server-mid-conversation-beta). When the API has to fetch a server’s tool list, the response starts with an `mcp_tool_listing` block for that server. Send it back unchanged with the rest of the assistant turn, and keep sending `mcp-client-2026-09-15` on every later request that carries it. The block pins the toolset to that list, so the API doesn’t contact the server again for it. These MCP connector features are available on the Claude API.
12221232
1223With only the `mid-conversation-tool-changes-2026-07-01` header, you can append a tool you learn about mid-session to `tools` with `defer_loading: true`, then offer it with a `tool_addition` block. That’s safe because the prefix check ignores a deferred tool until a `tool_addition` block references it. Adding a tool without `defer_loading: true` changes the prefix and invalidates earlier thinking.
1233With only the `mid-conversation-tool-changes-2026-07-01` header, you can append a tool you learn about mid-session to `tools` with `defer_loading: true`, then offer it with a `tool_addition` block. That’s safe because the prefix check ignores a deferred tool until something in the conversation references it. Adding a tool without `defer_loading: true` changes the prefix and invalidates earlier thinking.
12241234
12251235The `role: "system"` messages that carry these blocks join the prefix for later thinking. Leave them in place on later requests.
12261236
12271237### Change effort with a per-message `output_config`
12281238
1229Changing top-level `output_config.effort` between requests doesn’t invalidate thinking, because effort isn’t part of the prefix. Changing top-level effort does restart the prompt cache. Where the model and platform support [per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta), use it instead: append a `role: "system"` message with empty `content` and the new level. It needs the beta header `mid-conversation-output-config-2026-07-01`. On Claude Haiku 5.5, per-message effort needs adaptive thinking.
1239Changing top-level `output_config.effort` between requests doesn’t invalidate thinking, because effort isn’t part of the prefix. Changing top-level effort does restart the prompt cache. Where the model and platform support [per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort-per-message), use it instead: append a `role: "system"` message with empty `content` and the new level. It needs the beta header `mid-conversation-output-config-2026-07-01`. On Claude Sonnet 5.5 and Claude Haiku 5.5, a per-message effort change needs adaptive thinking.
12301240
12311241```json
12321242{ "role": "system", "content": [], "output_config": { "effort": "low" } }
from line 1246
12361246
12371247### Trim context on the server
12381248
1239Another common prefix edit is client-side trimming: dropping or summarizing the oldest turns and keeping the recent ones verbatim. The kept turns’ thinking blocks were produced while the removed history was still in place, so they fail the check. The server-side equivalents don’t count as edits, because the check compares the conversation as you sent it:
1249Another common prefix edit is client-side trimming: dropping or summarizing the oldest turns and keeping the recent ones verbatim. The kept turns’ thinking blocks were produced while the removed history was still in place, so they fail the check. The server-side equivalents avoid that, because the check compares the conversation as you sent it:
12401250
12411251* [On-demand compaction](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand) (beta) returns the summary from a separate request, which can [run in the background](https://platform.claude.com/docs/en/build-with-claude/compaction-background), and you send the returned block in place of the messages it summarizes. The check accepts that swap, so the turns you keep can stay valid with their thinking, under the [conditions for kept thinking](https://platform.claude.com/docs/en/build-with-claude/compaction-thinking-blocks#conditions-for-kept-thinking-to-stay-valid). [Request a summary](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand#request-a-summary) shows the request and names the beta header it needs.
1242* [Compaction at a token threshold](https://platform.claude.com/docs/en/build-with-claude/compaction-threshold) summarizes older turns into a compaction block when the context approaches a threshold you set, and the checked prefix restarts from that block. Its [`instructions` parameter](https://platform.claude.com/docs/en/build-with-claude/compaction-threshold#custom-summarization-instructions) takes your own summarization prompt, such as “preserve every ticker, position size, and stated assumption.”
1252* [Compaction at a token threshold](https://platform.claude.com/docs/en/build-with-claude/compaction-threshold) summarizes older turns into a compaction block when the context approaches a threshold you set, and the check on `messages` restarts from that block. Its [`instructions` parameter](https://platform.claude.com/docs/en/build-with-claude/compaction-threshold#custom-summarization-instructions) takes your own summarization prompt, such as “preserve every ticker, position size, and stated assumption.”
12431253* [Context editing](https://platform.claude.com/docs/en/build-with-claude/context-editing) clears old tool results or old thinking blocks by rule, oldest first. The strategies are `clear_tool_uses_20250919` and `clear_thinking_20251015`.
12441254
12451255### Compact on the client
from line 1442
14321442 use Anthropic\Beta\Messages\BetaThinkingConfigAdaptive;
14331443 use Anthropic\Beta\Messages\BetaThinkingPrefixMismatchBehavior;
14341444 use Anthropic\Client;
1445 use Anthropic\Messages\Model;
14351446
14361447 $client = new Client();
14371448
14381449 // $compactedMessages: the summary message, then the kept turns as returned
14391450 $response = $client->beta->messages->create(
1440 model: 'claude-fable-5-1',
1451 model: Model::CLAUDE_FABLE_5_1,
14411452 maxTokens: 16000,
14421453 thinking: BetaThinkingConfigAdaptive::with(
14431454 blockBinding: BetaThinkingBlockBinding::with(
from line 1467
14561467
14571468 # compacted_messages: the summary message, then the kept turns as returned
14581469 response = client.beta.messages.create(
1459 model: "claude-fable-5-1",
1470 model: Anthropic::Model::CLAUDE_FABLE_5_1,
14601471 max_tokens: 16_000,
14611472 thinking: {
14621473 type: "adaptive",
from line 1554
15431554
15441555#### Earlier models
15451556
1546A conversation that moves from Claude Sonnet 5 or an earlier Opus, Sonnet, or Haiku model to Claude Opus 5, Claude Opus 5.5, Claude Sonnet 5.5, Claude Haiku 5.5, or any Claude Fable or Claude Mythos model keeps its reasoning. The reverse doesn’t hold: these earlier models can’t read thinking blocks from those models. Claude Opus 5, Claude Fable 5, and Claude Mythos 5 can’t read thinking blocks from Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5, or Claude Haiku 5.5.
1557Claude Sonnet 5 and earlier Opus, Sonnet, and Haiku models are the earlier models in this section. A conversation that moves from one of them to Claude Opus 5, Claude Opus 5.5, Claude Sonnet 5.5, Claude Haiku 5.5, or any Claude Fable or Claude Mythos model keeps its reasoning. The reverse doesn’t hold: the earlier models can’t read thinking blocks from those models. Claude Opus 5, Claude Fable 5, and Claude Mythos 5 can’t read thinking blocks from these models:
15471558
1559* Claude Fable 5.2 and Claude Mythos 5.2
1560* Claude Fable 5.1 and Claude Mythos 5.1
1561* Claude Opus 5.5
1562* Claude Sonnet 5.5
1563* Claude Haiku 5.5
1564
1565Claude Opus 5 also can’t read thinking blocks from Claude Fable 5 or Claude Mythos 5.
1566
15481567### See which blocks were dropped
15491568
15501569With the `thinking-binding-controls-2026-08-01` [beta header](https://platform.claude.com/docs/en/api/beta-headers), the response lists each dropped block in a top-level `input_transformations` array with `reason: "model_binding_mismatch"`:
from line 1594
15751594
15761595<AccordionGroup>
15771596 <Accordion title="Can I test preserved thinking from an account created before August 31, 2026?">
1578 Yes. Send the `thinking-binding-controls-2026-08-01` beta header and set `thinking.block_binding.prefix_mismatch_behavior`. The setting applies to that request on any account: `"error"` rejects an edited history with a 400 error, and `"drop_block"` lets the request through and lists what was dropped in `input_transformations`. See [Check whether your code edits the prefix](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#how-to-tell-whether-your-integration-is-impacted). Without that setting, what an account created before that date gets varies by model: see the table in [When `prefix_mismatch_behavior` is unset](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#enforcement).
1597 Yes. Send the `thinking-binding-controls-2026-08-01` beta header and set `thinking.block_binding.prefix_mismatch_behavior`. The setting applies to that request on any account: `"error"` rejects an edited history with a 400 error, and `"drop_block"` lets the request through and lists what was dropped in `input_transformations`. See [Check whether your code edits the prefix](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#how-to-tell-whether-your-integration-is-impacted). Without that setting, the outcome depends on the model and the account: see the table in [When `prefix_mismatch_behavior` is unset](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#enforcement).
15791598 </Accordion>
15801599
15811600 <Accordion title="If anything before a thinking block changes, even one tool description, is the conversation unusable?">
from line 1612
15931612 <Accordion title="I compact by summarizing older turns and keeping recent turns verbatim. Does that still work?">
15941613 Yes, if the API writes the summary. [On-demand compaction](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand) (beta header `compact-2026-09-04`) summarizes the older turns into a signed block that you send in place of them. The recent turns keep their thinking under the [conditions for kept thinking](https://platform.claude.com/docs/en/build-with-claude/compaction-thinking-blocks#conditions-for-kept-thinking-to-stay-valid).
15951614
1596 If you write the summary yourself, the kept turns’ thinking fails the check, because those blocks were produced against the history you replaced. Strip `thinking` and `redacted_thinking` blocks from the turns you carry across and keep their `text` and `tool_use` blocks, or send `prefix_mismatch_behavior: "drop_block"` and let the API drop them. Simple compaction leaves no thinking behind to fail and is the recommended approach: one summary message plus the next user turn, with no earlier turns replayed. Server-side [compaction](https://platform.claude.com/docs/en/build-with-claude/compaction) and [context editing](https://platform.claude.com/docs/en/build-with-claude/context-editing) don’t count as edits. See [Compact on the client](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#custom-compaction-on-the-client).
1615 If you write the summary yourself, the kept turns’ thinking fails the check, because those blocks were produced against the history you replaced. Strip `thinking` and `redacted_thinking` blocks from the turns you carry across and keep their `text` and `tool_use` blocks, or send `prefix_mismatch_behavior: "drop_block"` and let the API drop them. Simple compaction leaves no thinking behind to fail and is the recommended approach: one summary message plus the next user turn, with no earlier turns replayed. [Compaction at a token threshold](https://platform.claude.com/docs/en/build-with-claude/compaction-threshold) and [context editing](https://platform.claude.com/docs/en/build-with-claude/context-editing) avoid that failure, because the check compares the conversation as you sent it. See [Compact on the client](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#custom-compaction-on-the-client).
15971616 </Accordion>
15981617
15991618 <Accordion title="How do I handle instruction files such as AGENTS.md or CLAUDE.md that change mid-session?">
from line 1620
16011620 </Accordion>
16021621
16031622 <Accordion title="A saved session fails on every request. How do I get it working again?">
1604 The stored history has an edit in it, so sending it back as it is fails every time, even after you fix the code that made the edit. To continue the session, send the beta header with `prefix_mismatch_behavior: "drop_block"` on every later request. Alternatively, strip the block the error names and every later `thinking` and `redacted_thinking` block, then retry once. If you can’t send `block_binding` (on Claude Sonnet 5.5 and Claude Haiku 5.5, it works only with `thinking: {"type": "adaptive"}`), strip the blocks. Thinking the model produces after that stays valid as long as nothing before it changes again. Then fix the code that made the edit so that new sessions don’t hit it. See [Handle the error in code](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#handle-the-error-in-code).
1623 If the stored history has an edit in it, sending it back as it is fails every time, even after you fix the code that made the edit. To continue the session, send the beta header with `prefix_mismatch_behavior: "drop_block"` on every later request. Alternatively, strip the block the error names and every later `thinking` and `redacted_thinking` block, leave them out of later requests, and retry. If you can’t send `block_binding` (on Claude Sonnet 5.5 and Claude Haiku 5.5, it works only with `thinking: {"type": "adaptive"}`), strip the blocks. Thinking the model produces after that stays valid as long as nothing before it changes again. Then fix the code that made the edit so that new sessions don’t hit it. See [Handle the error in code](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#handle-the-error-in-code).
16051624 </Accordion>
16061625
16071626 <Accordion title="My harness can route a turn to a non-Claude model. Do those turns invalidate Claude’s earlier thinking?">
from line 1665
16461665| Status | Cloud platforms | Models |
16471666| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
16481667| Available | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed), [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry) | [Claude Fable 5.2](https://platform.claude.com/docs/en/models/fable-5-2/overview), [Claude Mythos 5.2](https://platform.claude.com/docs/en/models/mythos-5-2/overview), [Claude Fable 5.1](https://platform.claude.com/docs/en/models/fable-5-1/overview), [Claude Mythos 5.1](https://platform.claude.com/docs/en/models/mythos-5-1/overview), [Claude Opus 5.5](https://platform.claude.com/docs/en/models/opus-5-5/overview), [Claude Sonnet 5.5](https://platform.claude.com/docs/en/models/sonnet-5-5/overview), [Claude Haiku 5.5](https://platform.claude.com/docs/en/models/haiku-5-5/overview) |
1649| Available | [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock) | [Claude Fable 5.2](https://platform.claude.com/docs/en/models/fable-5-2/overview), [Claude Mythos 5.2](https://platform.claude.com/docs/en/models/mythos-5-2/overview) |
1668| Available | [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock) | [Claude Fable 5.1](https://platform.claude.com/docs/en/models/fable-5-1/overview), [Claude Opus 5.5](https://platform.claude.com/docs/en/models/opus-5-5/overview), [Claude Sonnet 5.5](https://platform.claude.com/docs/en/models/sonnet-5-5/overview), [Claude Haiku 5.5](https://platform.claude.com/docs/en/models/haiku-5-5/overview) |
1669| Available | [Amazon Bedrock (bedrock-runtime)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy) | [Claude Fable 5.2](https://platform.claude.com/docs/en/models/fable-5-2/overview), [Claude Mythos 5.2](https://platform.claude.com/docs/en/models/mythos-5-2/overview) |
16501670| Available | [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed) | [Claude Fable 5.2](https://platform.claude.com/docs/en/models/fable-5-2/overview), [Claude Mythos 5.2](https://platform.claude.com/docs/en/models/mythos-5-2/overview) |
16511671
16521672#### [Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview)
build-with-claude/prompt-caching Changed · +250 / -96 lines
from line 28
2828 - claude-sonnet-4-5-20250929
2929 supportedPlatforms:
3030 Claude API: stable
31 Amazon Bedrock: stable
32 Amazon Bedrock (bedrock-runtime): stable
3133 Claude Platform on AWS: stable
3234 Claude Models on Google Cloud (Anthropic managed): stable
33 Amazon Bedrock: stable
34 Amazon Bedrock (InvokeModel): stable
3535 Claude Models on Google Cloud (Google managed): stable
3636 Microsoft Foundry: stable
3737---
from line 241
241241The lifetime is measured from the start of the request that writes or reads the cache entry, not from the end of its response. Time spent generating a response counts against the lifetime: if a response takes 4 minutes to stream, a follow-up request that reuses the same cached prefix must start within about 1 minute of that response completing.
242242
243243<Note>
244 If you find that 5 minutes is too short, Anthropic also offers a 1-hour cache duration [at additional cost](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pricing).
244 If you find that 5 minutes is too short, Anthropic also offers a 1-hour cache duration at additional cost (see [Pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pricing)).
245245
246246 For more information, see [1-hour cache duration](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#1-hour-cache-duration).
247247</Note>
from line 546
546546* If the last block is not eligible as an automatic cache breakpoint target, the system silently walks backward to find the nearest eligible block. If none is found, caching is skipped.
547547
548548<Note>
549 Automatic caching is available on every platform except the legacy [Amazon Bedrock (Opus 4.6 and earlier)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy) integration. On that integration, the API returns a 400 error for a top-level `cache_control` field, so use [explicit cache breakpoints](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#explicit-cache-breakpoints) instead.
549 Automatic caching is available on every platform except [Amazon Bedrock (`bedrock-runtime`)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy). There, the API returns a 400 error for a top-level `cache_control` field, so use [explicit cache breakpoints](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#explicit-cache-breakpoints) instead.
550550</Note>
551551
552552***
from line 628
628628* 1,024 tokens for Claude Opus 4.8, Claude Sonnet 5, Claude Sonnet 4.6, Claude Sonnet 4.5 ([deprecated](https://platform.claude.com/docs/en/about-claude/model-deprecations)), Claude Opus 4.1 ([retired, except on Claude Models on Google Cloud (Google managed) and Bedrock](https://platform.claude.com/docs/en/about-claude/model-deprecations)), Claude Opus 4 ([retired, except on Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/about-claude/model-deprecations)), and Claude Sonnet 4 ([retired, except on Claude Models on Google Cloud (Google managed) and Bedrock](https://platform.claude.com/docs/en/about-claude/model-deprecations))
629629* 4,096 tokens for Claude Haiku 4.5
630630
631These minimums apply on every platform where each model is available.
631These minimums apply on each of these platforms where the model is available.
632632
633633Shorter prompts cannot be cached, even if marked with `cache_control`. Any requests to cache fewer than this number of tokens are processed without caching, and no error is returned. To check whether a prompt was cached, look at the [response usage fields](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#tracking-cache-performance): if both `cache_creation_input_tokens` and `cache_read_input_tokens` are 0, the prompt was not cached (likely because it did not meet the minimum length requirement).
634634
from line 635
635635If your prompt falls just short of the minimum for your model and platform, expanding the cached content to reach the threshold is often worthwhile. Cache reads cost significantly less than uncached input tokens, so reaching the minimum can reduce costs for frequently reused prompts.
636636
637637<Note>
638 [Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock) is an AWS-operated platform. On Bedrock, see the [Bedrock prompt caching documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html) for the per-model minimums, failure behavior, and usage-field names that apply.
638 [Amazon Bedrock (`bedrock-mantle`)](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock) is an AWS-operated platform. On Amazon Bedrock, see the [Bedrock prompt caching documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html) for the per-model minimums, failure behavior, and usage-field names that apply.
639639</Note>
640640
641641For concurrent requests, note that a cache entry only becomes available after the first response starts. If you need cache hits for parallel requests, wait for the first response before sending subsequent requests.
642642
643Currently, `ephemeral` is the only supported cache type, which by default has a 5-minute lifetime.
643`ephemeral` is the only supported cache type, which by default has a 5-minute lifetime.
644644
645645### What can be cached
646646
from line 674
674674
675675The following table shows which parts of the cache are invalidated by different types of changes. ✘ indicates that the cache is invalidated, whereas ✓ indicates that the cache remains valid.
676676
677| What changes | Tools cache | System cache | Messages cache | Impact |
678| ----------------------------------------------------- | -------------- | -------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
679| **Tool definitions** | ✘ | ✘ | ✘ | Modifying tool definitions (names, descriptions, parameters) invalidates the entire cache |
680| **Web search toggle** | ✓ | ✘ | ✘ | Enabling/disabling web search modifies the system prompt |
681| **Citations toggle** | ✓ | ✘ | ✘ | Enabling/disabling citations modifies the system prompt |
682| **Speed setting** | ✓ | ✘ | ✘ | Switching between [`speed: "fast"` and standard speed](https://platform.claude.com/docs/en/build-with-claude/fast-mode) invalidates system and message caches |
683| **Tool choice** | ✓ | ✓ | ✘ | Changes to the `tool_choice` parameter only affect message blocks |
684| **Images** | ✓ | ✓ | ✘ | Adding/removing images anywhere in the prompt affects message blocks |
685| **Thinking parameters** | Model-specific | Model-specific | ✘ | The thinking configuration (mode, and `budget_tokens` in extended mode) is rendered into the prompt, so changing it always invalidates message blocks; tool and system caches are also invalidated on models that render the configuration ahead of them. See [Thinking and prompt caching](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-and-prompt-caching). |
686| **Effort setting** | Model-specific | Model-specific | ✘ | Changing the [`output_config.effort`](https://platform.claude.com/docs/en/build-with-claude/effort) value always invalidates message blocks, with the same model-specific effect on tool and system caches as thinking parameters. Setting effort explicitly to the model’s default is equivalent to omitting it and does not invalidate. On models that support [per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort#change-effort-mid-conversation-beta), an effort change carried in a `role: "system"` message inside `messages` leaves the cached prefix intact. |
687| **Non-tool results passed to requests with thinking** | ✓ | ✓ | Model-specific | On Opus 4.5+, Sonnet 4.6+, and Haiku 5.5, thinking blocks are preserved by default, so the cache remains valid (✓). On earlier Opus/Sonnet models and Haiku models through Claude Haiku 4.5, all previously-cached thinking blocks are stripped from context, and any messages that follow those thinking blocks are removed from the cache (✘). For more details, see [Caching with thinking blocks](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#caching-with-thinking-blocks). |
688| **Dropped thinking blocks** | ✓ | ✓ | ✘ | When the API drops a thinking block that isn’t [preserved](https://platform.claude.com/docs/en/build-with-claude/thinking#preserved-thinking) on that request, the cached prefix changes from that block’s position onward on that request. Blocks the receiving model can read, passed back unchanged, keep the cache intact. |
677| What changes | Tools cache | System cache | Messages cache | Impact |
678| ----------------------------------------------------- | -------------- | -------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
679| **Tool definitions** | ✘ | ✘ | ✘ | Modifying tool definitions (names, descriptions, parameters) invalidates the entire cache |
680| **Web search toggle** | ✓ | ✘ | ✘ | Enabling/disabling web search modifies the system prompt |
681| **Citations toggle** | ✓ | ✘ | ✘ | Enabling/disabling citations modifies the system prompt |
682| **Speed setting** | ✓ | ✘ | ✘ | Switching between [`speed: "fast"` and standard speed](https://platform.claude.com/docs/en/build-with-claude/fast-mode) invalidates system and message caches |
683| **Tool choice** | ✓ | ✓ | ✘ | Changes to the `tool_choice` parameter only affect message blocks |
684| **Images** | ✓ | ✓ | ✘ | Adding/removing images anywhere in the prompt affects message blocks |
685| **Thinking parameters** | Model-specific | Model-specific | ✘ | The thinking configuration (mode, and `budget_tokens` in extended mode) is rendered into the prompt, so changing it always invalidates message blocks; tool and system caches are also invalidated on models that render the configuration ahead of them. See [Thinking and prompt caching](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-and-prompt-caching). |
686| **Effort setting** | Model-specific | Model-specific | ✘ | Changing the [`output_config.effort`](https://platform.claude.com/docs/en/build-with-claude/effort) value always invalidates message blocks, with the same model-specific effect on tool and system caches as thinking parameters. Setting effort explicitly to the model’s default is equivalent to omitting it and does not invalidate. On models that support [per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort-per-message), an effort change carried in a `role: "system"` message inside `messages` leaves the cached prefix intact. |
687| **Non-tool results passed to requests with thinking** | ✓ | ✓ | Model-specific | On Opus 4.5+, Sonnet 4.6+, and Haiku 5.5, thinking blocks are preserved by default, so the cache remains valid (✓). On earlier Opus/Sonnet models and Haiku models through Claude Haiku 4.5, all previously-cached thinking blocks are stripped from context, and any messages that follow those thinking blocks are removed from the cache (✘). For more details, see [Caching with thinking blocks](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#caching-with-thinking-blocks). |
688| **Dropped thinking blocks** | ✓ | ✓ | ✘ | When the API drops a thinking block that isn’t [preserved](https://platform.claude.com/docs/en/build-with-claude/thinking#preserved-thinking) on that request, the cached prefix changes from that block’s position onward on that request. Blocks the receiving model can read, passed back unchanged, keep the cache intact. |
689689
690690On models that support [mid-conversation tool changes](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#mid-conversation-tool-changes), the `inline-tools-2026-09-15` beta header lets you add a tool, or change a tool’s definition, partway through a conversation without editing `tools`. Send the definition in a `tool_addition` block in a mid-conversation system message and leave `tools` exactly as you first sent it. The cached prefix still matches, so only the appended message is processed as new input. The one exception is a `tools` array with no non-deferred tool, where the first tool defined this way costs one full cache miss on that request. See [Define tools in a message](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#define-tools-in-a-message-beta).
691691
692692<Note>
693 On Claude Fable 5.2, [Claude Mythos 5.2](https://platform.claude.com/docs/en/models/mythos-5-2/overview), Claude Fable 5.1, [Claude Mythos 5.1](https://platform.claude.com/docs/en/models/mythos-5-1/overview), Claude Fable 5, [Claude Mythos 5](https://platform.claude.com/docs/en/models/mythos-5/overview), Claude Opus 5.5, Claude Opus 4.8, Claude Opus 5, Claude Sonnet 5.5, and Claude Haiku 5.5, you can add a new system instruction partway through a conversation without invalidating the system or message caches. Append a `{"role": "system"}` message to `messages` instead of editing the top-level `system` field, so the cached prefix stays unchanged. This feature is not available on Claude Sonnet 5. Use the top-level `system` field instead. See [Mid-conversation system messages and tool changes](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages).
693 On Claude Fable 5.2, [Claude Mythos 5.2](https://platform.claude.com/docs/en/models/mythos-5-2/overview), Claude Fable 5.1, [Claude Mythos 5.1](https://platform.claude.com/docs/en/models/mythos-5-1/overview), Claude Fable 5, [Claude Mythos 5](https://platform.claude.com/docs/en/models/mythos-5/overview), Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Sonnet 5.5, and Claude Haiku 5.5, you can add a new system instruction partway through a conversation without invalidating the system or message caches. Append a `{"role": "system"}` message to `messages` instead of editing the top-level `system` field, so the cached prefix stays unchanged. This feature is not available on Claude Sonnet 5. Use the top-level `system` field instead. See [Mid-conversation system messages and tool changes](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages).
694694</Note>
695695
696696### Tracking cache performance
from line 831
831831
832832## 1-hour cache duration
833833
834If you find that 5 minutes is too short, Anthropic also offers a 1-hour cache duration [at additional cost](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pricing).
834If you find that 5 minutes is too short, Anthropic also offers a 1-hour cache duration at additional cost (see [Pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pricing)).
835835
836836<Note>
837 The 1-hour cache duration is available on the Claude API, [Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), [Amazon Bedrock (Opus 4.6 and earlier)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy), [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed), and [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry).
837 The 1-hour cache duration is available on the Claude API, [Amazon Bedrock (`bedrock-mantle`)](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), [Amazon Bedrock (`bedrock-runtime`)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy), [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed), and [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry).
838838</Note>
839839
840840To use the extended cache, include `ttl` in the `cache_control` definition like this:
from line 2493
24932493 system=[
24942494 {
24952495 "type": "text",
2496 "text": "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base",
2496 "text": """You are a helpful research assistant with access to a document knowledge base.
2497
2498 # Instructions
2499 - Always search for relevant documents before answering
2500 - Provide citations for your sources
2501 - Be objective and accurate in your responses
2502 - If multiple documents contain relevant information, synthesize them
2503 - Acknowledge when information is not available in the knowledge base""",
24972504 "cache_control": {"type": "ephemeral"},
24982505 },
24992506 {
25002507 "type": "text",
2501 "text": "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]",
2508 "text": """# Knowledge Base Context
2509
2510 Here are the relevant documents for this conversation:
2511
2512 ## Document 1: Solar System Overview
2513 The solar system consists of the Sun and all objects that orbit it...
2514
2515 ## Document 2: Planetary Characteristics
2516 Each planet has unique features. Mercury is the smallest planet...
2517
2518 ## Document 3: Mars Exploration
2519 Mars has been a target of exploration for decades...
2520
2521 [Additional documents...]""",
25022522 "cache_control": {"type": "ephemeral"},
25032523 },
25042524 ],
from line 2612
25922612 system: [
25932613 {
25942614 type: "text",
2595 text: "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base",
2615 text: `You are a helpful research assistant with access to a document knowledge base.
2616
2617 # Instructions
2618 - Always search for relevant documents before answering
2619 - Provide citations for your sources
2620 - Be objective and accurate in your responses
2621 - If multiple documents contain relevant information, synthesize them
2622 - Acknowledge when information is not available in the knowledge base`,
25962623 cache_control: { type: "ephemeral" }
25972624 },
25982625 {
25992626 type: "text",
2600 text: "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]",
2627 text: `# Knowledge Base Context
2628
2629 Here are the relevant documents for this conversation:
2630
2631 ## Document 1: Solar System Overview
2632 The solar system consists of the Sun and all objects that orbit it...
2633
2634 ## Document 2: Planetary Characteristics
2635 Each planet has unique features. Mercury is the smallest planet...
2636
2637 ## Document 3: Mars Exploration
2638 Mars has been a target of exploration for decades...
2639
2640 [Additional documents...]`,
26012641 cache_control: { type: "ephemeral" }
26022642 }
26032643 ],
from line 2736
26962736 {
26972737 new TextBlockParam()
26982738 {
2699 Text = "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base",
2739 Text = """
2740 You are a helpful research assistant with access to a document knowledge base.
2741
2742 # Instructions
2743 - Always search for relevant documents before answering
2744 - Provide citations for your sources
2745 - Be objective and accurate in your responses
2746 - If multiple documents contain relevant information, synthesize them
2747 - Acknowledge when information is not available in the knowledge base
2748 """,
27002749 CacheControl = new CacheControlEphemeral(),
27012750 },
27022751 new TextBlockParam()
27032752 {
2704 Text = "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]",
2753 Text = """
2754 # Knowledge Base Context
2755
2756 Here are the relevant documents for this conversation:
2757
2758 ## Document 1: Solar System Overview
2759 The solar system consists of the Sun and all objects that orbit it...
2760
2761 ## Document 2: Planetary Characteristics
2762 Each planet has unique features. Mercury is the smallest planet...
2763
2764 ## Document 3: Mars Exploration
2765 Mars has been a target of exploration for decades...
2766
2767 [Additional documents...]
2768 """,
27052769 CacheControl = new CacheControlEphemeral(),
27062770 },
27072771 }),
from line 2821
27572821 ```
27582822
27592823 ```go Go
2760 client := anthropic.NewClient()
2824 client := anthropic.NewClient()
27612825
2762 response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
2763 Model: anthropic.ModelClaudeOpus5_5,
2764 MaxTokens: 1024,
2765 Tools: []anthropic.ToolUnionParam{
2766 {OfTool: &anthropic.ToolParam{
2767 Name: "search_documents",
2768 Description: anthropic.String("Search through the knowledge base"),
2769 InputSchema: anthropic.ToolInputSchemaParam{
2770 Properties: map[string]any{
2771 "query": map[string]any{
2772 "type": "string",
2773 "description": "Search query",
2826 response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
2827 Model: anthropic.ModelClaudeOpus5_5,
2828 MaxTokens: 1024,
2829 Tools: []anthropic.ToolUnionParam{
2830 {OfTool: &anthropic.ToolParam{
2831 Name: "search_documents",
2832 Description: anthropic.String("Search through the knowledge base"),
2833 InputSchema: anthropic.ToolInputSchemaParam{
2834 Properties: map[string]any{
2835 "query": map[string]any{
2836 "type": "string",
2837 "description": "Search query",
2838 },
27742839 },
2840 Required: []string{"query"},
27752841 },
2776 Required: []string{"query"},
2777 },
2778 }},
2779 {OfTool: &anthropic.ToolParam{
2780 Name: "get_document",
2781 Description: anthropic.String("Retrieve a specific document by ID"),
2782 InputSchema: anthropic.ToolInputSchemaParam{
2783 Properties: map[string]any{
2784 "doc_id": map[string]any{
2785 "type": "string",
2786 "description": "Document ID",
2842 }},
2843 {OfTool: &anthropic.ToolParam{
2844 Name: "get_document",
2845 Description: anthropic.String("Retrieve a specific document by ID"),
2846 InputSchema: anthropic.ToolInputSchemaParam{
2847 Properties: map[string]any{
2848 "doc_id": map[string]any{
2849 "type": "string",
2850 "description": "Document ID",
2851 },
27872852 },
2853 Required: []string{"doc_id"},
27882854 },
2789 Required: []string{"doc_id"},
2855 CacheControl: anthropic.NewCacheControlEphemeralParam(),
2856 }},
2857 },
2858 System: []anthropic.TextBlockParam{
2859 {
2860 Text: `You are a helpful research assistant with access to a document knowledge base.
2861
2862 # Instructions
2863 - Always search for relevant documents before answering
2864 - Provide citations for your sources
2865 - Be objective and accurate in your responses
2866 - If multiple documents contain relevant information, synthesize them
2867 - Acknowledge when information is not available in the knowledge base`,
2868 CacheControl: anthropic.NewCacheControlEphemeralParam(),
27902869 },
2791 CacheControl: anthropic.NewCacheControlEphemeralParam(),
2792 }},
2793 },
2794 System: []anthropic.TextBlockParam{
2795 {
2796 Text: "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base",
2797 CacheControl: anthropic.NewCacheControlEphemeralParam(),
2870 {
2871 Text: `# Knowledge Base Context
2872
2873 Here are the relevant documents for this conversation:
2874
2875 ## Document 1: Solar System Overview
2876 The solar system consists of the Sun and all objects that orbit it...
2877
2878 ## Document 2: Planetary Characteristics
2879 Each planet has unique features. Mercury is the smallest planet...
2880
2881 ## Document 3: Mars Exploration
2882 Mars has been a target of exploration for decades...
2883
2884 [Additional documents...]`,
2885 CacheControl: anthropic.NewCacheControlEphemeralParam(),
2886 },
27982887 },
2799 {
2800 Text: "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]",
2801 CacheControl: anthropic.NewCacheControlEphemeralParam(),
2888 Messages: []anthropic.MessageParam{
2889 anthropic.NewUserMessage(anthropic.NewTextBlock("Can you search for information about Mars rovers?")),
2890 anthropic.NewAssistantMessage(anthropic.NewToolUseBlock(
2891 "tool_1",
2892 map[string]any{"query": "Mars rovers"},
2893 "search_documents",
2894 )),
2895 anthropic.NewUserMessage(anthropic.NewToolResultBlock(
2896 "tool_1",
2897 "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)",
2898 false,
2899 )),
2900 anthropic.NewAssistantMessage(anthropic.NewTextBlock("I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document.")),
2901 anthropic.NewUserMessage(anthropic.ContentBlockParamUnion{OfText: &anthropic.TextBlockParam{
2902 Text: "Yes, please tell me about the Perseverance rover specifically.",
2903 CacheControl: anthropic.NewCacheControlEphemeralParam(),
2904 }}),
28022905 },
2803 },
2804 Messages: []anthropic.MessageParam{
2805 anthropic.NewUserMessage(anthropic.NewTextBlock("Can you search for information about Mars rovers?")),
2806 anthropic.NewAssistantMessage(anthropic.NewToolUseBlock(
2807 "tool_1",
2808 map[string]any{"query": "Mars rovers"},
2809 "search_documents",
2810 )),
2811 anthropic.NewUserMessage(anthropic.NewToolResultBlock(
2812 "tool_1",
2813 "Found 3 relevant documents: Document 3 (Mars Exploration), Document 7 (Rover Technology), Document 9 (Mission History)",
2814 false,
2815 )),
2816 anthropic.NewAssistantMessage(anthropic.NewTextBlock("I found 3 relevant documents about Mars rovers. Let me get more details from the Mars Exploration document.")),
2817 anthropic.NewUserMessage(anthropic.ContentBlockParamUnion{OfText: &anthropic.TextBlockParam{
2818 Text: "Yes, please tell me about the Perseverance rover specifically.",
2819 CacheControl: anthropic.NewCacheControlEphemeralParam(),
2820 }}),
2821 },
2822 })
2823 if err != nil {
2824 log.Fatal(err)
2825 }
2826 fmt.Println(response.Usage.RawJSON())
2906 })
2907 if err != nil {
2908 log.Fatal(err)
2909 }
2910 fmt.Println(response.Usage.RawJSON())
28272911 ```
28282912
28292913 ```java Java
from line 2960
28762960 List.of(
28772961 TextBlockParam.builder()
28782962 .text(
2879 "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base"
2963 """
2964 You are a helpful research assistant with access to a document knowledge base.
2965
2966 # Instructions
2967 - Always search for relevant documents before answering
2968 - Provide citations for your sources
2969 - Be objective and accurate in your responses
2970 - If multiple documents contain relevant information, synthesize them
2971 - Acknowledge when information is not available in the knowledge base"""
28802972 )
28812973 .cacheControl(CacheControlEphemeral.builder().build())
28822974 .build(),
28832975 TextBlockParam.builder()
28842976 .text(
2885 "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]"
2977 """
2978 # Knowledge Base Context
2979
2980 Here are the relevant documents for this conversation:
2981
2982 ## Document 1: Solar System Overview
2983 The solar system consists of the Sun and all objects that orbit it...
2984
2985 ## Document 2: Planetary Characteristics
2986 Each planet has unique features. Mercury is the smallest planet...
2987
2988 ## Document 3: Mars Exploration
2989 Mars has been a target of exploration for decades...
2990
2991 [Additional documents...]"""
28862992 )
28872993 .cacheControl(CacheControlEphemeral.builder().build())
28882994 .build()
from line 3102
29963102 system: [
29973103 [
29983104 'type' => 'text',
2999 'text' => "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base",
3105 'text' => <<<'TEXT'
3106 You are a helpful research assistant with access to a document knowledge base.
3107
3108 # Instructions
3109 - Always search for relevant documents before answering
3110 - Provide citations for your sources
3111 - Be objective and accurate in your responses
3112 - If multiple documents contain relevant information, synthesize them
3113 - Acknowledge when information is not available in the knowledge base
3114 TEXT,
30003115 'cache_control' => ['type' => 'ephemeral']
30013116 ],
30023117 [
30033118 'type' => 'text',
3004 'text' => "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]",
3119 'text' => <<<'TEXT'
3120 # Knowledge Base Context
3121
3122 Here are the relevant documents for this conversation:
3123
3124 ## Document 1: Solar System Overview
3125 The solar system consists of the Sun and all objects that orbit it...
3126
3127 ## Document 2: Planetary Characteristics
3128 Each planet has unique features. Mercury is the smallest planet...
3129
3130 ## Document 3: Mars Exploration
3131 Mars has been a target of exploration for decades...
3132
3133 [Additional documents...]
3134 TEXT,
30053135 'cache_control' => ['type' => 'ephemeral']
30063136 ]
30073137 ],
from line 3211
30813211 system_: [
30823212 {
30833213 type: "text",
3084 text: "You are a helpful research assistant with access to a document knowledge base.\n\n# Instructions\n- Always search for relevant documents before answering\n- Provide citations for your sources\n- Be objective and accurate in your responses\n- If multiple documents contain relevant information, synthesize them\n- Acknowledge when information is not available in the knowledge base",
3214 text: <<~TEXT.chomp,
3215 You are a helpful research assistant with access to a document knowledge base.
3216
3217 # Instructions
3218 - Always search for relevant documents before answering
3219 - Provide citations for your sources
3220 - Be objective and accurate in your responses
3221 - If multiple documents contain relevant information, synthesize them
3222 - Acknowledge when information is not available in the knowledge base
3223 TEXT
30853224 cache_control: { type: "ephemeral" }
30863225 },
30873226 {
30883227 type: "text",
3089 text: "# Knowledge Base Context\n\nHere are the relevant documents for this conversation:\n\n## Document 1: Solar System Overview\nThe solar system consists of the Sun and all objects that orbit it...\n\n## Document 2: Planetary Characteristics\nEach planet has unique features. Mercury is the smallest planet...\n\n## Document 3: Mars Exploration\nMars has been a target of exploration for decades...\n\n[Additional documents...]",
3228 text: <<~TEXT.chomp,
3229 # Knowledge Base Context
3230
3231 Here are the relevant documents for this conversation:
3232
3233 ## Document 1: Solar System Overview
3234 The solar system consists of the Sun and all objects that orbit it...
3235
3236 ## Document 2: Planetary Characteristics
3237 Each planet has unique features. Mercury is the smallest planet...
3238
3239 ## Document 3: Mars Exploration
3240 Mars has been a target of exploration for decades...
3241
3242 [Additional documents...]
3243 TEXT
30903244 cache_control: { type: "ephemeral" }
30913245 }
30923246 ],
from line 3432
32783432 </Accordion>
32793433
32803434 <Accordion title="Can I manually clear the cache?">
3281 Currently, there’s no way to manually clear the cache. Cached prefixes automatically expire after a minimum of 5 minutes of inactivity.
3435 There’s no way to manually clear the cache. Cached prefixes automatically expire after a minimum of 5 minutes of inactivity.
32823436 </Accordion>
32833437
32843438 <Accordion title="How can I track the effectiveness of my caching strategy?">