api-20261029T233709Z / documentation capture

about-claude/models/optimizing-for-cost-and-intelligence Changed · +32 / -35 lines

from line 64

6464Anthropic priced the DeepResearch Bench II[7](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs) runs with and without the cache discount:

6565

6666<Frame>

67 ![Chart, DeepResearch Bench II: caching cuts Fable 5.1 from $37.94 USD to $6.89 USD per task; Sonnet 5, $3.20 USD to $1.18 USD](https://platform.claude.com/docs/images/cost-intel/caching-repriced.svg)

67 ![Chart, DeepResearch Bench II: caching cuts Fable 5.1 from $40.58 USD to $5.64 USD a task; Sonnet 5.5, $5.13 USD to $1.05 USD](https://platform.claude.com/docs/images/cost-intel/caching-repriced.svg)

6868</Frame>

6969

70The cache’s default lifetime is 5 minutes and an agent loop’s turns are seconds apart, so the discount applies to most tokens on every turn. The caching chart’s runs read 84% to 90% of their input tokens from the cache.

70The cache’s default lifetime is 5 minutes and an agent loop’s turns are seconds apart, so the discount applies to most tokens on every turn. The caching chart’s runs read 89% to 93% of their input tokens from the cache.

7171

7272Pricing other runs’ recorded token counts the same way, each model at its default effort, gives the average token cost per task without caching:

7373

from line 272

272272* Run-wide, the prune and context editing cache about equally well. If you use context editing, [clear in a few large batches](https://platform.claude.com/docs/en/build-with-claude/context-editing#context-editing-and-prompt-caching).

273273

274274<Note>

275 On Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5, rewriting an earlier tool result [invalidates every thinking block after it](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#prefix-check), so use compaction instead. The prune was measured on an earlier model without [preserved thinking](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking); on these models, [context editing](https://platform.claude.com/docs/en/build-with-claude/context-editing) and [compaction](https://platform.claude.com/docs/en/build-with-claude/compaction) run on the server and don’t invalidate thinking blocks. [Send assistant turns back exactly as returned](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#append-assistant-turns-exactly-as-returned): dropping their thinking blocks costs output tokens on every turn, because Claude [re-creates the reasoning](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#drop-block-cost).

275 On Claude 5.1 and later models, rewriting an earlier tool result [invalidates every thinking block after it](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#prefix-check), so use compaction instead. The prune was measured on an earlier model without [preserved thinking](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking); on these models, [context editing](https://platform.claude.com/docs/en/build-with-claude/context-editing) and [compaction](https://platform.claude.com/docs/en/build-with-claude/compaction) run on the server and don’t invalidate thinking blocks. [Send assistant turns back exactly as returned](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#append-assistant-turns-exactly-as-returned): dropping their thinking blocks costs output tokens on every turn, because Claude [re-creates the reasoning](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#drop-block-cost).

276276</Note>

277277

278278The prune, adapted from the triage agent’s code:

from line 412

412412* Start with Claude Opus 5.5 at its default effort: on the SWE-bench Pro subset it matched Claude Fable 5.1 at its default, inside run-to-run noise, for about a fifth of the cost per solved task. Opus 5.5 and Fable 5.1 both largely saturate the SWE-bench Pro subset. Use Claude Fable 5.1 for demanding reasoning and long-horizon agentic work, or when your evals on Claude Opus 5.5 at higher effort still fall short.

413413* At the other end, Claude Haiku 5.5 suits high-volume and latency-sensitive work with checkable outputs.

414414* Price every candidate in cost per completed task on your own traffic, including Claude Opus 5.5 at its default effort and the frontier model at reduced effort. Each of Claude Opus 5.5’s token prices, cache reads included, is twice Claude Sonnet 5.5’s, but on the SWE-bench Pro subset Opus 5.5 at `low` solved about the same share of tasks as Sonnet 5.5 at its default, inside run-to-run noise, for about 7% more per solved task.

415* The ranking flips by workload, and no price list tells you which way, so measure it on your own workload. On long research loops, Claude Fable 5.1 can do more work, not less, and so cost more per task (DeepResearch Bench II[7](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs)).

415* Measure what a more expensive model buys on your own workload. On the 45 DeepResearch Bench II[7](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs) tasks scored for every model, at default effort, Claude Opus 5.5 scored 2.6 points above Claude Sonnet 5.5 for 1.5 times the cost per task, and Claude Fable 5.1 scored 6.0 points above Claude Sonnet 5.5 for 5.8 times. On all 50 tasks, with four biology tasks that only Claude Sonnet 5.5 answered counted as failures, neither is measurably ahead of Claude Sonnet 5.5.

416416* Price the tail of your workload, not the median: compare models on the hardest tenth of your tasks, not the typical one.

417417

418418The bill is decided by the tasks the cheaper model fails, because a failed task still bills its tokens, then the retry, then whatever the failure costs downstream. The tail is also where the money goes even when nothing fails. On a 20-problem WideSearch[1](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs) run, two problems carried 43% of the spend:

from line 431

431431 ![Charts: on SWE-bench Pro, Opus 5.5 and Sonnet 5.5 cut cost per solved task most; on Terminal-Bench 3, Opus drops to $28 USD](https://platform.claude.com/docs/images/cost-intel/upgrade-ladder-sonnet-5-5.svg)

432432</Frame>

433433

435| ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | --------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |

440| DeepResearch Bench II[7](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs) | Claude Fable 5 to Claude Fable 5.1 | `high` | 2 to 3 more points on the 21 tasks where no attempt was cut short | 46% more per task on all 50 tasks |

444| Claude Managed Agents task set[25](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs) | Claude Haiku 4.5 to Claude Haiku 5.5 | As served; `medium` on Claude Haiku 5.5 | From 62% to 93% of attempts passed, one run per model | From $0.041 USD to about $0.010 USD in token cost per attempt; about 84% less per passed attempt |

435| ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | --------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------ |

442| Claude Managed Agents task set[25](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs) | Claude Haiku 4.5 to Claude Haiku 5.5 | As served; `medium` on Claude Haiku 5.5 | From 62% to 93% of attempts passed, one run per model | From $0.041 USD to about $0.010 USD in token cost per attempt; about 84% less per passed attempt |

445443

446444**When it pays.**

447445

from line 446

448446* The size of the saving depends on the work. From Claude Opus 5 to Claude Opus 5.5, it is 78% per solved task on the SWE-bench Pro subset and 40% on typical workloads ([Introducing Claude Opus 5.5](https://www.anthropic.com/news/claude-opus-5-5)). From Claude Sonnet 5 to Claude Sonnet 5.5, it is 87% on the same subset and up to 30% for most work ([Introducing Claude Sonnet 5.5](https://www.anthropic.com/news/claude-sonnet-5-5)).

449447* Where older models already solve most tasks, the cost of each attempt decides the saving: on the SWE-bench Pro subset, Claude Opus 5.5 scores about the same as Claude Opus 5 for 78% less per solved task.

450448* Where older models mostly fail, the pass rate decides the saving: on Terminal-Bench 3[20](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs), the upgrade from Claude Opus 4.8 to Claude Opus 5 raises tasks solved from 15% to 41% and costs 56% less per solved task.

451* Measure the upgrade on your own workload before assuming it saves. The saving is not guaranteed: on DeepResearch Bench II[7](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs), Claude Fable 5.1 costs more per task than Claude Fable 5 because the new model does more work per task there, although the input and output prices are the same and the cache read is 4x cheaper.

452449* Compare on cost per solved task, not per token: the same text costs about 30% more tokens on Claude 4.7 and later models, so a per-token comparison makes the newer models look more expensive by construction.

453450

454451### Tune effort

455452

456Sweep effort on your own workload before you add a second model. Lower effort costs less and is often faster, and how much accuracy it gives up depends on the task: on long-horizon coding, effort bought accuracy, and on research tasks it bought a lot in one measurement and nothing in another. The [`effort`](https://platform.claude.com/docs/en/build-with-claude/effort) parameter governs how much thinking, tool calling, and self-verification the model does; `high` is the default on most models, and `medium` on Claude Opus 5.5 and Claude Haiku 5.5.

453Sweep effort on your own workload before you add a second model. Lower effort costs less and is often faster, and how much accuracy it gives up depends on the task: on long-horizon coding, effort bought accuracy, and on research tasks it bought a lot in one measurement and a little in another. The [`effort`](https://platform.claude.com/docs/en/build-with-claude/effort) parameter governs how much thinking, tool calling, and self-verification the model does; `high` is the default on most models, and `medium` on Claude Opus 5.5 and Claude Haiku 5.5.

457454

458455The following table lists Anthropic’s measurements on two benchmarks with current models; scores and costs are not comparable between the two benchmarks. Costs are per task, not per solved task as in [Compare models on cost per task](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#compare-models-on-cost-per-task). Each score pools two runs on SWE-bench Pro and three on DeepResearch Bench II, unless its cell says otherwise:

459456

from line 460

466| DeepResearch Bench II[7](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs) | Claude Fable 5.1 | `low` | Rubric score 66% | $4.48 USD |

463| DeepResearch Bench II[7](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs) | Claude Fable 5.1 | `low` | Rubric score 60.5% | $3.47 USD |

468466

469467The following chart plots accuracy against cost per task for Claude Opus 5.5 on the SWE-bench Pro[3](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs) subset:

470468

from line 473

475473The following chart plots rubric score against cost per task for Claude Fable 5.1 on DeepResearch Bench II[7](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs):

476474

477475<Frame>

478 ![Line chart, DeepResearch Bench II, rubric score against cost per task: on Fable 5.1 higher effort bought no score, only cost](https://platform.claude.com/docs/images/cost-intel/effort-limit-repriced.svg)

476 ![Line chart, DeepResearch Bench II, Fable 5.1: rubric score 60.5% at low effort, 60.5% at medium, 63.0% at high, as cost rises](https://platform.claude.com/docs/images/cost-intel/effort-limit-repriced.svg)

479477</Frame>

480478

481479**What to do.**

from line 481

483481* Sweep two or three effort levels on a sample of your own traffic, each in a separate session: changing top-level effort mid-session [invalidates the cache](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#cache-repeated-context) and distorts the comparison. The curve is the baseline any multi-model strategy must beat ([step 2 of measuring on your own workload](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#measure-on-your-own-workload)).

484482* On long-horizon coding, effort is a real tradeoff, which [re-running failures at higher effort](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#re-run-failures-at-higher-effort) turns back into a saving. At `medium`, Claude Sonnet 5.5 scored about 7 points lower than at its default, `high`, on the SWE-bench Pro[3](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs) subset for about 59% of the cost per task (2 runs each), and scored 62.7% compared with 77.8% on the internal agentic-coding benchmark[11](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs) (1 attempt per task).

485483* At `xhigh` and `max`, Claude Sonnet 5.5 can start its own rounds of review after it finishes a task, which takes more time and tokens. To keep that work on the task, add the prompt under “Thoroughness at `xhigh` and `max` effort” in [Prompting Claude Sonnet 5.5](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5#steer-initiative-and-scope) to your system prompt.

486* On research tasks, measure the model you ship. Claude Fable 5.1 scored nearly the same from `low` to `high` on DeepResearch Bench II; Claude Opus 5.5 scored 13.3 points lower at `low` than at `medium` on DRACO[21](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs). The two results come from different models on different benchmarks, so they show that the answer varies, not why.

484* On research tasks, measure the model you ship. Claude Fable 5.1 scored 2.5 points higher at `high` than at `low` on DeepResearch Bench II, for 1.6 times the cost, and no higher at `medium` than at `low`; Claude Opus 5.5 scored 13.3 points lower at `low` than at `medium` on DRACO[21](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs). The two results come from different models on different benchmarks, so they show that the answer varies, not why.

487485* At `low`, Claude Opus 5.5’s typical task took 84% less time than at `medium` on DRACO[21](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs), 30% less on HLE[22](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs), and 47% less on an internal set of physics problems[23](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs), and it scored 13.3, 3.4, and 14.0 points lower (3, 3, and 4 attempts per task).

488486* On an internal defect-search benchmark for work larger than one context window[8](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs), Claude Fable 5.1 took 15.2, 17.5, and 19.9 hours per run at `low`, `medium`, and `high` (3 runs each). To save time, also compare lower effort with the two changes in [Show the model elapsed time](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#show-the-model-elapsed-time): `low` effort saved more time, and the changes kept more of the score.

489487

from line 586

588586

589587An advisor can help only when the executor consults it.

590588

591In Anthropic’s measurements on current models, the one pairing whose executor consulted often, on a coding benchmark, scored 1.7 points higher than the executor alone at the same effort, at the edge of run-to-run noise, for about 2.1 times the cost. Where the executor rarely or never consulted, the pairing scored within run-to-run noise of the executor alone, or lower.

589In Anthropic’s measurements, the one pairing whose executor consulted often, on a coding benchmark, scored 1.7 points higher than the executor alone at the same effort, at the edge of run-to-run noise, for about 2.1 times the cost. Where the executor rarely or never consulted, the pairing scored within run-to-run noise of the executor alone, or lower.

592590

593591To turn it on, add the [advisor tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool), a beta feature, to your request. On Claude Managed Agents, [give the session an advisor](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#give-the-session-an-advisor). For Claude Code, see [escalating hard decisions with the advisor tool](https://code.claude.com/docs/en/advisor).

594592

from line 855

857855

859857| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

860| Prompt caching | Cost cut by a factor of 2.7 to 5.5 on a research agent, and by 83% to 86% on a small triage agent | None | Faster | [Cache repeated context](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#cache-repeated-context) |

858| Prompt caching | Cost cut by a factor of 4.8 to 7.2 on a research agent, and by 83% to 86% on a small triage agent | None | Faster | [Cache repeated context](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#cache-repeated-context) |

861859| 1-hour cache duration | With 1 turn in 10 after a pause, the 5-minute default cost 54% more; with 1 in 20, about the same | None | On earlier models, stayed warm after a pause[16](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs) | [Pick the cache duration](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#pick-the-cache-duration) |

862860| Input trimming | A further 21% to 26% off a small triage agent’s bill | With tool search, accuracy in the same range as without[27](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#refs) | Neutral | [Trim input and context tokens](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#trim-input-and-context-tokens) |

863861| Tool search | 45% with 500 tool definitions attached; 20% from deferring a GitHub MCP server’s toolset | None for tools the task never needs | Neutral | [Trim input and context tokens](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#trim-input-and-context-tokens) |

from line 863

866864| Prompt audit against the current model | 14% on both model upgrades tested | None; a gain on one | Faster (fewer tool rounds) | [Audit prompts against the current model](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#audit-prompts-against-the-current-model) |

867865| Upgrade the model | Usually less: up to 40% less on typical workloads, and up to 87% less per solved task on a coding benchmark | None; a gain on most | Neutral | [Upgrade the model](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#upgrade-the-model) |

868| Lower effort | On long coding tasks, `medium` cost about 30% to 52% less than `high`, and `low` about two thirds less | Up to 15 points lower, depending on the task; none on one research agent | Faster | [Tune effort](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#tune-effort) |

866| Lower effort | On long coding tasks, `medium` cost about 30% to 52% less than `high`, and `low` about two thirds less | Up to 15 points lower, depending on the task; 2.5 on one research agent | Faster | [Tune effort](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#tune-effort) |

869867| Re-run failures | About 40% less than running everything at `high`, at the same pass rate or slightly better | None | A second attempt on the tasks that fail | [Re-run failures at higher effort](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#re-run-failures-at-higher-effort) |

871869| Raising `max_tokens` | None: cost per solved task stayed about the same | A gain: up to 22 points more tasks solved on one coding benchmark; none on another | Neutral | [Set budgets and output caps](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#set-budgets-and-output-caps) |

from line 929

931929 * **Upgrade the model, cost per solved task:** Claude Opus 5 costs 21% more per solved task than Claude Opus 4.8 when those Claude Opus 5 runs are compared with one Claude Opus 4.8 run at its shipped defaults from the August 17 to 19 series, counted over the same 478 problems; the chart’s SWE-bench Pro panel shows neither Claude Opus 4.7 nor Claude Opus 4.8. In the same measurements, priced as a customer is billed, Claude Opus 5 solves 12 more points of tasks than Claude Opus 4.8 at that 21% more per solved task, Claude Opus 4.8 solves the same share of tasks as Claude Opus 4.7 for 14% less per solved task, and Claude Opus 5 at `low` effort beats Claude Opus 4.8’s default on this benchmark for about 30% of its cost per solved task.

932930 * **Upgrade the model, prices:** Claude Sonnet 5’s saving over Claude Sonnet 4.6 in Upgrade the model comes from its lower per-token price, which more than offsets the extra tokens it uses per task. Claude Sonnet 5.5 charges the same as Claude Sonnet 5 for everything but cache reads, which cost half as much. Claude Opus 5.5’s token prices are lower than Claude Opus 5’s, most of all for cache reads. Like Claude Sonnet 5, the frontier tier gained through price: most of Claude Fable 5.1’s saving is the lower cache-read price.

933931 * **Cost without caching, priced from recorded token counts:** Anthropic re-priced the recorded token counts of the Claude Opus 5.5 and Claude Sonnet 5.5 runs, over the 478 problems, for the caching factors in [Why caching comes first](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#why-caching-comes-first).

934 * **The factors, by model:** Each factor is the token cost with every input token at the input price, output tokens unchanged, divided by the cost priced as a customer’s organization is metered: for Claude Opus 5.5, 3.3 at `medium`, 2.4 at `low`, 3.8 at `high`, and 5.4 at `xhigh` (one run); for Claude Sonnet 5.5, with cache reads at $0.10 USD per million tokens, 3.1 at `high` and 2.4 at `medium`, or 2.8 at `high` at the launch price of $0.20 USD. Unlike the caching chart’s runs, these incurred no web-search fees, and a task’s first request is priced as a cache write.

932 * **The factors, by model:** Each factor is the token cost with every input token at the input price, output tokens unchanged, divided by the cost priced as a customer’s organization is metered: for Claude Opus 5.5, 3.3 at `medium`, 2.4 at `low`, 3.8 at `high`, and 5.4 at `xhigh` (one run); for Claude Sonnet 5.5, with cache reads at $0.10 USD per million tokens, 3.1 at `high` and 2.4 at `medium`, or 2.8 at `high` at the launch price of $0.20 USD. A task’s first request is priced as a cache write.

935933

9369344. **BrowseComp:** Wei et al., “BrowseComp: A Simple Yet Challenging Benchmark for Browsing Agents,” OpenAI, 2025. Effort figures use a 500-problem cut, one to three runs per setting, run August 3, 2026, with the default point pooling two runs from July 26 to 27, 2026. The measurement of routine work with a long cost tail in [Orchestrator strategy](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#orchestrator-strategy-delegate-bulk-work) uses 10 problems that the model reliably solved on its own when the protocol was fixed, from a 26-problem slice, 50 delegated runs (5 per problem; August 1 to 2, 2026) and 70 runs of the model alone (50 from August 2 to 3, 2026; 20 archived from July 12 to 13 and August 1, 2026), $6.45 USD compared with $11.99 USD per run in expectation; delegated figures carry a measurement band of about 20%. The 10 problems are those on which the delegated configuration, a Claude Fable 5 orchestrator with one Claude Sonnet 5 worker, was right in all 5 runs and Claude Fable 5 alone in both archived runs; the delegated runs are those same runs, and only Claude Fable 5 alone was run again on the ten. Over its 70 runs, archived and new, Claude Fable 5 alone was right in 68. On those problems the delegated configuration cost about half as much as Claude Fable 5 alone on average (the $6.45 USD and $11.99 USD given earlier) and about a third as much at the 90th percentile ($12 USD compared with $33 USD per run), and its most expensive run cost $42 USD compared with $84 USD; that $84 USD run was also wrong. On the full, harder BrowseComp set, Claude Fable 5 alone reached the accuracy of the orchestrator configuration measured on that set at 22% to 30% lower cost.

937935

from line 939

941939

9429407. **DeepResearch Bench II:** Li et al., “DeepResearch Bench II: Diagnosing Deep Research Agents via Rubrics from Expert Report,” arXiv:2601.08536, 2026.

943941

944 * **What was measured:** Its 132 research tasks across 22 domains are graded against expert-derived binary rubrics. Measured on a 50-task subset stratified across all themes, one attempt per task, 3 runs per setting, on [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) with the platform’s own web search and fetch tools (August 26 to 27, 2026).

945 * **How scored:** Scored on the 33 tasks no configuration refused, with attempts the production safety classifiers cut short removed. Claude Opus 4.6 judges under the benchmark’s rubric protocol; the original uses a different judge, and an Anthropic judge may favor the house style.

946 * **Scores:** Scores are each model’s mean on the 33-task basis with its own pre-empted tasks removed; on the 21 of the 33 tasks where no configuration had an attempt cut short, Claude Fable 5.1 holds a 2-to-3-point lead over Claude Fable 5 at every effort level and both models are flat across effort.

947 * **How priced:** Costs are priced as a customer’s organization is metered: each request’s prior prompt as a cache read and its new tokens as a 5-minute cache write, a session’s first request keeping the cache read it got, from the runs’ own usage records, plus the platform’s web-search fees. Each cost per task is a 50-task run’s cost divided by 50, with the attempts that were cut short included, averaged over the three runs.

948 * **Results, Claude Fable 5:** Claude Fable 5 cost $2.30 USD per task at `low` and $4.71 USD at `high`, priced the same way; the percentages in [Upgrade the model](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#upgrade-the-model) come from unrounded costs.

949 * **Results, Claude Opus 5:** Claude Opus 5 at its default effort ran on the same surface and subset, three runs, on August 28, 2026: 68.8% on the raw 50 tasks, 70.8% on the 33-task basis, and 71.1% on the 21-task set, at $6.28 USD per task ($23.72 USD without caching); none of its attempts was cut short by the safety classifiers, under a safeguards deployment newer than the one the other models ran under.

950 * **Compare models:** The research comparison in [Compare models](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#compare-models-on-cost-per-task) rests on these figures: Claude Fable 5.1 at `low` scored 10 points above Claude Sonnet 5 on the 33-task basis (66% against 56%) at about four times the cost per task over all 50 tasks ($4.48 USD against $1.18 USD); Claude Opus 5 at its default, whose scores and cost are given earlier in this reference, scored above Claude Fable 5.1 at its default, which scored 65% on the 33-task basis and cost $6.89 USD per task over all 50 tasks, so on research, Claude Fable 5.1 earns its price only at `low`.

951 * **Caching chart:** The caching chart re-prices the same requests with every input token at the uncached rate.

942 * **What was measured:** Its 132 research tasks across 22 domains are graded against expert-derived binary rubrics. Measured October 22, 2026, on a 50-task subset drawn from all its themes, half in English and half in Chinese, one attempt per task, 3 runs per setting: Claude Sonnet 5.5 at `high`, Claude Opus 5.5 at `medium`, and Claude Fable 5.1 at `low`, `medium`, and `high`. Every setting ran on the Messages API with adaptive thinking and the production safety classifiers on.

943 * **Tools:** The agent used search and fetch tools that the evaluation harness hosts over an Anthropic web index with nothing dated after March 17, 2026, and had no shell. A search query over 120 characters was cut at the last whole word, and the agent was told so: 48% of searches on Claude Sonnet 5.5, and 26% to 31% in the other settings. About a quarter of fetches returned an error. Each task’s source article and the benchmark’s own paper and dataset were filtered out.

944 * **How scored:** Claude Opus 4.6 judges under the benchmark’s rubric protocol; the original uses a different judge, and an Anthropic judge may favor the house style. Scores are means over the 45 tasks that every setting answered and the judge fully graded. The other five: four biology tasks that the safety classifiers refused in every run of Claude Opus 5.5 and Claude Fable 5.1 and in none of Claude Sonnet 5.5’s, and one on which a safety check that Anthropic adds to its own evaluations stopped an attempt.

945 * **Scores:** On the 45 tasks, and on all 50, with a refused or stopped attempt counted as 0: Claude Sonnet 5.5, 56.9% and 57.0%; Claude Opus 5.5, 59.5% and 54.3%; Claude Fable 5.1, 60.5% and 55.1% at `low`, 60.5% and 54.9% at `medium`, and 63.0% and 57.4% at `high`. Task-by-task differences on the 45 tasks, taken before rounding, with 95% intervals: Claude Fable 5.1 at `high` over `low`, 2.5 points (1.3 to 3.6); Claude Opus 5.5 over Claude Sonnet 5.5, 2.6 (0.7 to 4.5); Claude Fable 5.1 at `high` over Claude Opus 5.5, 3.4 (2.0 to 4.9), and over Claude Sonnet 5.5, 6.0 (4.4 to 7.7); Claude Fable 5.1 at `medium` over `low`, 0.0 (-1.3 to 1.2). On all 50 tasks: Claude Opus 5.5 over Claude Sonnet 5.5, -2.7 (-8.3 to 2.9); Claude Fable 5.1 at `high` over Claude Sonnet 5.5, 0.4 (-5.3 to 6.2).

946 * **How priced:** Each cost per task is the model’s own tokens at list prices, from the attempts’ usage records, over all 50 tasks and every attempt, averaged over the three runs: $1.05 USD on Claude Sonnet 5.5, $1.52 USD on Claude Opus 5.5, and $3.47 USD, $4.44 USD, and $5.64 USD on Claude Fable 5.1. A refused attempt costs about a cent. On the 45 tasks alone the costs are $1.06 USD, $1.63 USD, $3.75 USD, $4.81 USD, and $6.10 USD. The cost ratios in [Compare models](https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#compare-models-on-cost-per-task), 1.5 and 5.8, are on those 45 tasks, like the scores beside them; over all 50 tasks they are 1.4 and 5.4. Costs cover model tokens only; the harness’s tools add no charges. The agent made 17 to 28 searches per task, refused attempts counted.

947 * **Caching chart:** The caching chart re-prices the same requests with every input token at the uncached rate. The evaluation harness set the cache breakpoints.

948 * **Comparability:** These scores are not comparable with the benchmark’s leaderboard.

952949

9539508. **Corpus defect sweep:** Anthropic-internal, for work larger than one context window: a 21.6-million-token corpus from 14 public Python package sources with 130 planted defects and deterministic grading; protocol fixed before the runs and internally reviewed; three runs per configuration. Every configuration ran on Claude Managed Agents. The charted team configuration is one in which the Claude Fable 5.1 orchestrator ran the whole sweep inside the platform at its documented limit of 25 concurrent Claude Sonnet 5 workers, run August 30, 2026; its three runs scored F1 0.764, 0.825, and 0.791 after the extras audit (raw 0.751, 0.821, and 0.781) for $225 USD, $234 USD, and $283 USD. The team configuration cost about half as much as Claude Fable 5.1 alone at `low`, `medium`, or `high` (47% to 55% less), scored 10 to 12 points below it, and took about 2.3 hours per run, compared with 15 to 20 hours. The team configuration read about 560 million cached tokens per run, nearly all of them at Claude Sonnet 5’s cache-read rate. That is about one and a half times the roughly 365 million that Claude Fable 5.1 read alone. Claude Fable 5.1 alone at `high` effort still holds peak accuracy, at about 2.2 times the team configuration’s cost, so delegation here buys most of the accuracy, not all of it. The configuration with Claude Sonnet 5 alone ran August 3 to 4, 2026; the configurations with Claude Fable 5.1 alone ran August 24 to 25, 2026, under the platform’s launch serving settings, three seeds per effort setting, on the same corpus build. The sandbox image carried installed copies of part of the corpus, and Claude Fable 5.1’s final assembly step compared against them in 7 of 9 runs; re-grading without those additions moved the affected seeds by up to 3 points. Absolute F1 is specific to this corpus build, not comparable across benchmarks; configuration comparisons are like for like.

954951

agents-and-tools/tool-use/advisor-tool Changed · +3 / -3 lines

from line 291

291291 ```

292292</CodeGroup>

293293

294The response `content` includes an `advisor_tool_result` block carrying the advisor’s guidance. With `claude-opus-5-5` as the advisor, as in this quick start, the block’s `content` field is an `advisor_redacted_result` variant (encrypted; the executor reads it server-side, but your client does not). To see the advice text directly in your response, use `claude-opus-4-8` as the advisor model instead, which returns the plaintext `advisor_result` variant. See [Result variants](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#result-variants) for both shapes side by side and which advisor models return which, and [Model compatibility](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#model-compatibility) for the full list of valid pairs.

294The response `content` includes an `advisor_tool_result` block carrying the advisor’s guidance. With the newest Opus model as the advisor, as in this quick start, the block’s `content` field is an `advisor_redacted_result` variant (encrypted; the executor reads it server-side, but your client does not). To see the advice text directly in your response, use `claude-opus-4-8` as the advisor model instead, which returns the plaintext `advisor_result` variant. See [Result variants](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#result-variants) for both shapes side by side and which advisor models return which, and [Model compatibility](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#model-compatibility) for the full list of valid pairs.

295295

296296## How it works

297297

from line 325

325325

326326### Successful advisor call

327327

328When the advisor is called, a `server_tool_use` block is followed by an `advisor_tool_result` block in the assistant’s content. The following example shows the plaintext `advisor_result` variant returned by a Claude Opus 4.8 advisor. The [Quick start](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#quick-start) uses Claude Opus 5.5, which returns the encrypted `advisor_redacted_result` variant instead; see [Result variants](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#result-variants) for both shapes side by side.

328When the advisor is called, a `server_tool_use` block is followed by an `advisor_tool_result` block in the assistant’s content. The following example shows the plaintext `advisor_result` variant returned by a Claude Opus 4.8 advisor. The [Quick start](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#quick-start) uses the newest Opus model, which returns the encrypted `advisor_redacted_result` variant instead; see [Result variants](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#result-variants) for both shapes side by side.

329329

330330```json

331331{

from line 437

437437

438438## Multi-turn conversations

439439

440Pass the full assistant content, including `advisor_tool_result` blocks, back to the API on subsequent turns. Round-trip the result blocks verbatim: with a Claude Opus 5.5 advisor the result block’s `content` is the encrypted `advisor_redacted_result` variant, and the server decrypts it and renders the advice into the executor’s prompt on the next turn (see [Result variants](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#result-variants)). The mechanics are identical for any advisor model.

440Pass the full assistant content, including `advisor_tool_result` blocks, back to the API on subsequent turns. Round-trip the result blocks verbatim: with the newest Opus model as the advisor, as in this example, the result block’s `content` is the encrypted `advisor_redacted_result` variant, and the server decrypts it and renders the advice into the executor’s prompt on the next turn (see [Result variants](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#result-variants)). The mechanics are identical for any advisor model.

441441

442442<CodeGroup exclude="shell">

443443 ```python Python

build-with-claude/compaction-threshold Changed · +4 / -4 lines

from line 1656

16561656* Keep the original messages in your list and let the API handle removing the compacted content

16571657* Manually drop the compacted messages and only include the compaction block onward

16581658

1659On Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5, thinking blocks from before a `compaction` block aren’t carried forward, so the summary is all the model has of that earlier work. If you write your own `instructions`, tell the model what the summary must retain; see [Tell the model what to preserve in compaction summaries](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1#tell-the-model-what-to-preserve-in-compaction-summaries).

1659On Claude 5.1 and later models, thinking blocks from before a `compaction` block aren’t carried forward, so the summary is all the model has of that earlier work. If you write your own `instructions`, tell the model what the summary must retain; see [Tell the model what to preserve in compaction summaries](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1#tell-the-model-what-to-preserve-in-compaction-summaries).

16601660

16611661### Streaming

16621662

from line 2513

25132513 messages.append({"role": "assistant", "content": response.content})

25142514

25152515 # Return the text content

2516 return next(block.text for block in response.content if block.type == "text")

2516 return next((block.text for block in response.content if block.type == "text"), "")

25172517

25182518

25192519 # Run a long conversation

from line 2771

27712771 ```

27722772</CodeGroup>

27732773

2774On 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.

2774On Claude 5.1 and later models, 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.

27752775

27762776Here’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:

27772777

from line 2857

28572857 messages.append({"role": "assistant", "content": response.content})

28582858

28592859 # Return the text content

2860 return next(block.text for block in response.content if block.type == "text")

2860 return next((block.text for block in response.content if block.type == "text"), "")

28612861

28622862

28632863 # Run a long conversation

build-with-claude/mid-conversation-system-messages Changed · +3 / -3 lines

from line 2020

20202020}

20212021```

20222022

2023The main use is a per-turn reminder in a tool loop. Each time you want the model to see the reminder, append it after the `tool_result` message. Leave every earlier copy where it is. The model sees only the copies that come after the last user message, so the reminder never piles up. Nothing earlier in `messages` changes, so the [prompt cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) keeps matching. On Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5, this also keeps later [thinking blocks valid](https://platform.claude.com/docs/en/build-with-claude/thinking#preserved-in-conversation). Deleting an earlier reminder would change the conversation before those blocks, so they would fail the prefix check. A cleared message stays in the array and leaves the conversation before those blocks unchanged.

2023The main use is a per-turn reminder in a tool loop. Each time you want the model to see the reminder, append it after the `tool_result` message. Leave every earlier copy where it is. The model sees only the copies that come after the last user message, so the reminder never piles up. Nothing earlier in `messages` changes, so the [prompt cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) keeps matching. On Claude 5.1 and later models, this also keeps later [thinking blocks valid](https://platform.claude.com/docs/en/build-with-claude/thinking#preserved-in-conversation). Deleting an earlier reminder would change the conversation before those blocks, so they would fail the prefix check. A cleared message stays in the array and leaves the conversation before those blocks unchanged.

20242024

20252025The following request is a later step of an agent loop. `messages[3]` rendered on the earlier request, when it was the last message in the array. Once `messages[5]` (a later user message) exists, `messages[3]` is cleared: the cleared message stays in the array, so the conversation before the thinking block in `messages[4]` is unchanged, but the model no longer receives its text. `messages[6]` and `messages[7]` both render, in order.

20262026

from line 2097

20972097

20982098Rules for turn-scoped messages:

20992099

2100* **Resend cleared messages verbatim.** A cleared message is still part of the conversation history. Rebuilding it from current state (a fresh token count, a timestamp), dropping it as redundant, or changing its `clear_at` value is an edit to an earlier message. On Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5, every thinking block produced after it fails the [prefix check](https://platform.claude.com/docs/en/build-with-claude/thinking#preserved-in-conversation).

2100* **Resend cleared messages verbatim.** A cleared message is still part of the conversation history. Rebuilding it from current state (a fresh token count, a timestamp), dropping it as redundant, or changing its `clear_at` value is an edit to an earlier message. On Claude 5.1 and later models, every thinking block produced after it fails the [prefix check](https://platform.claude.com/docs/en/build-with-claude/thinking#preserved-in-conversation).

21012101* **Text only.** `content` is one or more `text` blocks (or a string). `tool_addition` and `tool_removal` blocks return a 400 error on a turn-scoped message, and so does `output_config`. Use a separate `role: "system"` message without `clear_at` for those.

21022102* **No `cache_control` on its blocks.** A cleared message is never part of a cache key, so a breakpoint on it could never match. Put the breakpoint on the last block of the preceding user turn instead, as the example does. The top-level [automatic caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#automatic-caching) field skips turn-scoped messages when it picks a breakpoint. On the request that clears a message, the reusable cached prefix ends at the user turn before it, so only the one assistant turn between that message and the new user message is reprocessed.

21032103* **Placement rules still apply**, cleared or not. A turn-scoped message must follow a `user` turn (or an `assistant` turn ending in a server tool result) and precede an `assistant` turn or end the array, like any mid-conversation system message. One that ends the array always renders. One followed directly by another `user` message is a 400 error, not a cleared message: put all of a tool round’s results in one user message and the reminders after it.

from line 2353

23532353* **Append the system message after the breakpoint.** Because it comes after the cached prefix, it does not change the prefix hash and the cache still hits.

23542354* **A mid-conversation system message is itself cacheable.** Once it is in the conversation, it becomes part of the stable history. On the next turn you can move your cache breakpoint past it (or rely on [automatic caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#automatic-caching) to do so) and the system message is read from cache like any other turn.

23552355

2356Avoid editing or removing a mid-conversation system message that has already been sent. Like any other change to earlier messages, editing or removing it invalidates the cache from that point forward. On Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5, it also invalidates the [thinking blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#preserved-in-conversation) in every later assistant turn. For guidance that should apply to one turn only, use a [turn-scoped system message](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#turn-scoped-system-messages) and leave it in place. If the instruction needs to evolve, append a new system message rather than rewriting the old one. Consecutive system messages are accepted and treated as a single system section, which follows the same placement rule as a whole.

2356Avoid editing or removing a mid-conversation system message that has already been sent. Like any other change to earlier messages, editing or removing it invalidates the cache from that point forward. On Claude 5.1 and later models, it also invalidates the [thinking blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#preserved-in-conversation) in every later assistant turn. For guidance that should apply to one turn only, use a [turn-scoped system message](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#turn-scoped-system-messages) and leave it in place. If the instruction needs to evolve, append a new system message rather than rewriting the old one. Consecutive system messages are accepted and treated as a single system section, which follows the same placement rule as a whole.

23572357

23582358## Limitations

23592359

build-with-claude/preserved-thinking Changed · +4 / -4 lines

from line 34

3434

3535## Who the prefix check affects

3636

37The prefix check runs on Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5. Other models don’t run it. You don’t need to do anything if Claude Code, claude.ai, Claude Managed Agents, or the Claude Agent SDK builds your requests, or if your code keeps `system` and `tools` fixed for a session and only ever appends to `messages`. If you never send thinking blocks back, the check has nothing to test, and the model gets none of its earlier reasoning.

37The prefix check runs on Claude 5.1 and later models. Other models don’t run it. You don’t need to do anything if Claude Code, claude.ai, Claude Managed Agents, or the Claude Agent SDK builds your requests, or if your code keeps `system` and `tools` fixed for a session and only ever appends to `messages`. If you never send thinking blocks back, the check has nothing to test, and the model gets none of its earlier reasoning.

3838

3939Check your integration if, between two requests in one conversation, it does any of the following. Each item links to what to do instead:

4040

from line 64

6464* **A conversation that moves to Claude Fable 5.1 from an earlier model, or from Claude Opus 5.5 on the Claude API, keeps its reasoning.** The earlier model’s thinking blocks stay readable, so the model thinks as usual from the first turn after the switch.

6565* **A conversation that moves from Claude Fable 5.1 to any model other than Claude Mythos 5.1 loses Claude Fable 5.1’s reasoning for that request.** This occurs when a router sends a turn to a cheaper model, after a [classifier refusal fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback), or during a [server-side fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#server-side-fallback). The API removes the unreadable blocks before the prompt reaches the model. They aren’t billed and don’t count toward `input_tokens`.

6666

67Keep sending the full history on every request, thinking blocks included, and let the API drop what the current model can’t read. The API never edits your `messages` array, so the dropped blocks stay in your history. When the same history goes back to Claude Fable 5.1, its blocks are readable again, along with the earlier model’s thinking. The reasoning is permanently lost only if your client removes the blocks itself, for example a harness that strips thinking on a model switch or rebuilds the history from what each model used.

67Keep sending the full history on every request, thinking blocks included, and let the API drop what the current model can’t read. The API never edits your `messages` array, so the dropped blocks stay in your history. When the same history goes back to Claude Fable 5.1, its blocks are readable again. The reasoning is permanently lost only if your client removes the blocks itself, for example a harness that strips thinking on a model switch or rebuilds the history from what each model used.

6868

6969<Frame>

70 ![Animation: switching to Claude Opus skips Claude Fable 5.1's thinking for that turn; switching back, everything is read again](https://platform.claude.com/docs/images/preserved-thinking-model-switch.svg)

70 ![Animation: switching to Claude Opus skips Claude Fable 5.1's thinking for that turn; switching back, it is read again](https://platform.claude.com/docs/images/preserved-thinking-model-switch.svg)

7171</Frame>

7272

7373With 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 96

9696

9797## Keeping the prefix unchanged

9898

99On Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5, a thinking block stays valid only while everything you sent before it is unchanged on later requests. The checked prefix has three parts:

99On Claude 5.1 and later models, a thinking block stays valid only while everything you sent before it is unchanged on later requests. The checked prefix has three parts:

100100

101101* The top-level `system` prompt

102102* The set of `tools`

build-with-claude/prompt-engineering/prompting-claude-opus-5-5 Changed · +3 / -3 lines

from line 47

4747

4848## Prompts written for thinking disabled

4949

50Claude Opus 5 accepts `thinking: {"type": "disabled"}` at `high` effort or below; Claude Opus 5.5 doesn’t, and the [migration guide](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#migrating-from-claude-opus-5) covers the request change. If your Claude Opus 5 integration ran with thinking disabled, four changes go with it:

50Claude Opus 5 accepts `thinking: {"type": "disabled"}` at `high` effort or below. Claude Opus 5.5 returns a 400 error for it (see [Configuring thinking](https://platform.claude.com/docs/en/build-with-claude/thinking#configuring-thinking)). If your Claude Opus 5 integration ran with thinking disabled, four changes go with it:

5151

5252* **Start at `low` effort and measure.** At `low` the model keeps its thinking short. How often it skips thinking altogether depends on your prompts, so measure latency and quality on your own traffic and move to `medium` if quality drops. If time to first token still matters after that, a system prompt line such as “Answer directly without deliberating.” can reduce thinking further; measure quality when you add it, because less thinking can lower it.

5353* **Remove instructions that stood in for thinking.** If your prompt asked the model to write its reasoning in the response as a substitute for thinking, remove that instruction. Read the reasoning from [summarized thinking](https://platform.claude.com/docs/en/build-with-claude/thinking#summarized-thinking) blocks instead (`display: "summarized"`). A prompt that pushes the model to reproduce its reasoning in the response text might be declined with the `reasoning_extraction` [refusal category](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#refusal-response).

from line 82

8282* **Cybersecurity:** Finding vulnerabilities in source code is allowed. High-risk dual-use cybersecurity activities are not. If the cybersecurity classifier blocks your organization’s legitimate security work, apply to the [Cyber Verification Program](https://support.claude.com/en/articles/14604842).

8383* **Reasoning extraction:** Requests that push the model to reproduce its internal reasoning in the response text might be declined with the `reasoning_extraction` category. If your prompts ask the model to write its reasoning in the response, remove those instructions, set `display: "summarized"`, and read the summarized reasoning from the thinking blocks instead; see [Prompts written for thinking disabled](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#prompts-written-for-thinking-disabled). You can still ask for a short explanation of the answer or a summary of the actions taken; see [Keep reasoning in thinking blocks](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#keep-reasoning-in-thinking-blocks).

8484

85A classifier decline arrives as a normal response with `stop_reason: "refusal"` and a `stop_details` object naming the category. You can have the request retried automatically on a fallback model, except for `reasoning_extraction` declines, which server-side fallback returns to you instead of retrying; see [Refusals and fallback](https://platform.claude.com/docs/en/models/opus-5-5/whats-new-opus-5-5#refusals-and-fallback).

85A classifier decline arrives as a normal response with `stop_reason: "refusal"` and a `stop_details` object naming the category. You can have the request retried automatically on a fallback model, except for `reasoning_extraction` declines, which server-side fallback returns to you instead of retrying; see [Refusals and fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#server-side-fallback).

8686

8787## User-facing progress updates

8888

8989Between tool calls, Claude Opus 5.5 writes short user-facing progress updates: what it just found and what it’s doing next. Four levers control what your users see.

9090

91First, check that your client receives them. On Claude Opus 5.5 these notes come back as [progress-update `thinking` blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#progress-updates) rather than `text` blocks, and their text is empty at the default `thinking.display`. As a result, a client that renders only `text` blocks can look silent during a long agentic turn. Set `display: "updates"` (beta, `thinking-display-updates-2026-08-18` header) to receive a short summary of each note; see [Text between tool calls is returned in thinking blocks](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#text-between-tool-calls) for how to render them.

91First, check that your client receives them. On Claude Opus 5.5 these notes come back as [progress-update `thinking` blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#progress-updates) rather than `text` blocks, and their text is empty at the default `thinking.display`. As a result, a client that renders only `text` blocks can look silent during a long agentic turn. Set `display: "updates"` (beta, `thinking-display-updates-2026-08-18` header) to receive a short summary of each note; see [Progress updates between tool calls](https://platform.claude.com/docs/en/build-with-claude/thinking#progress-updates) for how to render them.

9292

9393Second, if the model might need to hand the user something verbatim partway through a long turn, such as a code snippet, give it a simple tool for sending the user a message and tell it to reserve the tool for that content. Declare the tool in `tools` from the first request of the session: adding it to `tools` later edits the conversation’s prefix and invalidates earlier thinking blocks (see [tool changes in Preserved thinking](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#tool-changes)).

9494

build-with-claude/thinking Changed · +5 / -5 lines

from line 37

3737

3838**API support**: Usage differs by product.

3939

40* **Messages API**: On by default. Turn it off with `thinking: {"type": "disabled"}`. Where it is off by default, set `thinking` to turn it on.

40* **Messages API**: On by default. `thinking: {"type": "disabled"}` turns it off on models that accept that value. Where it is off by default, set `thinking` to turn it on.

4141* **Managed Agents**: Always on. Managed Agents sets the thinking configuration; the agent definition has no `thinking` field.

4242

4343A model that answers in a single pass has to get everything right on the first try: no scratch work, no checking, no changing approach halfway through. For a proof, a tricky bug, or a long agentic task, the first approach is often not the best one.

from line 102

102102

103103In the table, “at `high` effort or below” means the request works at `low`, `medium`, and `high` effort and returns a 400 error at `xhigh` or `max`.

104104

105On Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Sonnet 5, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, and Claude Haiku 5.5, thinking is already on and needs no configuration. `display` defaults to `"omitted"` on these models, so the thinking text is hidden until you opt in. Opt in with `thinking: {"type": "adaptive", "display": "summarized"}`, as the following examples do.

105On Claude 5 and later models and Claude Mythos Preview, thinking is already on and needs no configuration. `display` defaults to `"omitted"` on these models, so the thinking text is hidden until you opt in. Opt in with `thinking: {"type": "adaptive", "display": "summarized"}`, as the following examples do.

106106

107107On Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, and Claude Sonnet 4.6, thinking is off until you set `thinking: {type: "adaptive"}`, which lets Claude determine when and how deeply to think based on the request. The same request, with the [model string](https://platform.claude.com/docs/en/models/overview) swapped, turns it on there. The following examples set `display: "summarized"` so the thinking text is visible, and use a large `max_tokens`:

108108

from line 1099

10991099

11001100The tradeoff is context usage: long conversations consume more context space on keep-all models, because retained thinking blocks count as input like any other conversation history (see [Thinking and the context window](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-and-the-context-window)). The behavior is automatic in both regimes. No code changes or beta headers are required, and you should keep passing complete, unmodified thinking blocks back as described in [Preserving thinking blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#preserving-thinking-blocks). To override the default in either direction, use [thinking block clearing](https://platform.claude.com/docs/en/build-with-claude/context-editing#thinking-block-clearing).

11011101

1102**Switching models mid-conversation.** Keep passing thinking blocks back unchanged when you switch models, for example after a [classifier refusal fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback). A thinking block is readable only by the model that produced it and certain other models, and the API ignores or drops the blocks the target model can’t read. On Claude Fable 5.1 and Claude Mythos 5.1 the direction matters: they read earlier models’ thinking blocks, and only the two of them read each other’s, so switching to them keeps the conversation’s reasoning and switching from them to any other model drops it (see [how dropped blocks are billed and reported](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models)). Claude Opus 5.5 reads Claude Opus 5’s thinking blocks and those of earlier Opus, Sonnet, and Haiku models, and, on the Claude API and Claude Models on Google Cloud (Google managed), of Claude Haiku 5.5, but not those of the Claude Fable and Claude Mythos models; on the Claude API, Claude Fable 5.1 and Claude Mythos 5.1 read Claude Opus 5.5’s blocks. A switch from Claude Opus 5.5 up to Claude Fable 5.1 on the Claude API keeps the earlier turns’ reasoning; a switch from Claude Fable 5.1 to Claude Opus 5.5 drops it. Claude Sonnet 5.5 reads thinking blocks from Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5, and earlier models, and, on the Claude API and Claude Models on Google Cloud (Google managed), from Claude Haiku 5.5, but not from Claude Opus 5, Claude Opus 5.5, or any Claude Fable or Claude Mythos model. On those two platforms, Claude Opus 5.5 reads Claude Sonnet 5.5’s blocks and no other model does: a switch from Claude Sonnet 5.5 up to Claude Opus 5.5 there keeps the earlier turns’ reasoning, and any other switch away from Claude Sonnet 5.5 drops it. Claude Haiku 5.5 reads thinking blocks from Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5, and earlier models, but not from Claude Opus 5, Claude Opus 5.5, Claude Sonnet 5.5, or any Claude Fable or Claude Mythos model. On the Claude API and Claude Models on Google Cloud (Google managed), Claude Opus 5.5 and Claude Sonnet 5.5 read Claude Haiku 5.5’s blocks and no other model does. Strip prior `thinking` and `redacted_thinking` blocks yourself only to save input tokens on models that ignore rather than drop them, and never when redeeming a [fallback credit](https://platform.claude.com/docs/en/build-with-claude/fallback-credit), which requires the body unchanged.

1102**Switching models mid-conversation.** Keep passing thinking blocks back unchanged when you switch models, for example after a [classifier refusal fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback). A thinking block is readable only by the model that produced it and certain other models, and the API ignores or drops the blocks the target model can’t read. On Claude Fable 5.1 and Claude Mythos 5.1 the direction matters: they read earlier models’ thinking blocks, and only the two of them read each other’s, so switching to them keeps the conversation’s reasoning and switching from them to any other model drops it (see [how dropped blocks are billed and reported](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models)). Claude Opus 5.5 reads Claude Opus 5’s thinking blocks and those of earlier Opus, Sonnet, and Haiku models, and, on the Claude API and Claude Models on Google Cloud (Google managed), of Claude Sonnet 5.5 and Claude Haiku 5.5, but not those of the Claude Fable and Claude Mythos models; on the Claude API, Claude Fable 5.1 and Claude Mythos 5.1 read Claude Opus 5.5’s blocks. A switch from Claude Opus 5.5 up to Claude Fable 5.1 on the Claude API keeps the earlier turns’ reasoning; a switch from Claude Fable 5.1 to Claude Opus 5.5 drops it. Claude Sonnet 5.5 reads thinking blocks from Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5, and earlier models, and, on the Claude API and Claude Models on Google Cloud (Google managed), from Claude Haiku 5.5, but not from Claude Opus 5, Claude Opus 5.5, or any Claude Fable or Claude Mythos model. On those two platforms, Claude Opus 5.5 reads Claude Sonnet 5.5’s blocks and no other model does: a switch from Claude Sonnet 5.5 up to Claude Opus 5.5 there keeps the earlier turns’ reasoning, and any other switch away from Claude Sonnet 5.5 drops it. Claude Haiku 5.5 reads thinking blocks from Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5, and earlier models, but not from Claude Opus 5, Claude Opus 5.5, Claude Sonnet 5.5, or any Claude Fable or Claude Mythos model. On the Claude API and Claude Models on Google Cloud (Google managed), Claude Opus 5.5 and Claude Sonnet 5.5 read Claude Haiku 5.5’s blocks and no other model does. Strip prior `thinking` and `redacted_thinking` blocks yourself only to save input tokens on models that ignore rather than drop them, and never when redeeming a [fallback credit](https://platform.claude.com/docs/en/build-with-claude/fallback-credit), which requires the body unchanged.

11031103

11041104## Preserved thinking

11051105

from line 1110

11101110

11111111Thinking blocks from Claude Sonnet 5.5 and Claude Haiku 5.5 are also tied to the account that produced them. See [Thinking blocks stay with the account that produced them](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#account-bound-thinking) for where this applies.

11121112

1113The prefix check runs on Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5. Make your integration append-only so that the thinking blocks you send back pass it. [What the API does with an invalid block](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#mismatch-behavior) covers what happens when one fails.

1113The prefix check runs on Claude 5.1 and later models. Make your integration append-only so that the thinking blocks you send back pass it. [What the API does with an invalid block](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#mismatch-behavior) covers what happens when one fails.

11141114

11151115To keep thinking valid, send every assistant turn back exactly as you received it and add new messages only at the end of `messages`. If your code builds the `messages` array itself, the Preserved thinking page covers:

11161116

from line 1290

12901290#### [Messages API](https://platform.claude.com/docs/en/build-with-claude/working-with-messages)

12911291

12921292* Availability: On by default

1293* Usage: Turn it off with `thinking: {"type": "disabled"}`. Where it is off by default, set `thinking` to turn it on.

1293* Usage: `thinking: {"type": "disabled"}` turns it off on models that accept that value. Where it is off by default, set `thinking` to turn it on.

12941294

12951295| Status | Cloud platforms |

12961296| --------- | ----------------------- |

manage-claude/analytics-api Changed · +1 / -5 lines

from line 21

2121The key types are not interchangeable: an Admin API key cannot call the Claude Enterprise Analytics API, and an Analytics API key cannot call the Admin API. The one exception is the [Usage and Cost Analytics API](https://platform.claude.com/docs/en/manage-claude/usage-cost-analytics-api), which Claude Enterprise organizations call with their Analytics API key. Both APIs appear under the [Admin API reference](https://platform.claude.com/docs/en/api/beta/organization), but they are separate APIs with separate key types. If your organization uses both the Claude Platform and Claude Enterprise, you can provision both keys and use each API for its own data.

2222

2323<Note>

24 Looking for token usage and cost data rather than product analytics? See the

25

26 [Usage and Cost Analytics API](https://platform.claude.com/docs/en/manage-claude/usage-cost-analytics-api)

27

28 , which serves both Claude Console and Claude Enterprise organizations.

24 Looking for token usage and cost data rather than product analytics? See the [Usage and Cost Analytics API](https://platform.claude.com/docs/en/manage-claude/usage-cost-analytics-api), which serves both Claude Console and Claude Enterprise organizations.

2925</Note>

3026

3127<Note>

manage-claude/cmek-coverage-claude-enterprise Changed · +15 / -16 lines

## Where CMEK does not apply: Claude Code telemetry

from line 4

44description: Look up which Claude Enterprise data your key encrypts, what turns off or changes, and what stays under Anthropic's key.

55---

66

7For Claude Platform, see [What CMEK covers on Claude Platform](https://platform.claude.com/docs/en/manage-claude/cmek-coverage-claude-platform). Beta and research preview features might not be covered by customer-managed encryption keys (CMEK) and can break in CMEK organizations.

7For Claude Platform, see [What CMEK covers on Claude Platform](https://platform.claude.com/docs/en/manage-claude/cmek-coverage-claude-platform).

88

99## Encrypted with your key

1010

from line 13

1313* Artifacts, including Claude Design, Claude Slides, and Claude Docs in conversations and the **Artifacts** tab.

1414* Claude Code on the CLI, including message content.

1515* Cowork in Claude Desktop.

16* Office agents.

16* Office agents, including Claude for Outlook (beta).

1717* Claude in Chrome.

1818* Claude Science, which is in beta.

1919* [Plugins API](https://platform.claude.com/docs/en/manage-claude/plugins-api#customer-managed-encryption-keys) (beta) plugin versions: each version’s description, release notes, components, and files. That page lists which requests still work while your key can’t be used.

from line 22

2222

2323## Turned off or changed

2424

25Beta and research preview features might not be covered by customer-managed encryption keys (CMEK) and can break in CMEK organizations.

26

2527This list is not exhaustive. Review it with your team before you set up CMEK.

2628

2729| Feature | What people see |

2830| ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

2931| Claude Code on the web | Off. New sessions can’t be started, even if an admin turns the product on. |

30| Claude in Slack | Off. Claude declines requests, even if an admin turns the product on. |

3132| Claude Code Desktop | Off until an admin turns it on. Available for local sessions once turned on under [claude.ai > Organization settings > Claude Code](https://claude.ai/admin-settings/claude-code). |

32| Artifacts | Changed. Artifacts, including Claude Design, Claude Slides, and Claude Docs in conversations and the **Artifacts** tab, cannot be turned on in organizations that also use ZDR. In organizations with HIPAA readiness, an Owner must first accept the terms for using them. |

33| Artifact publishing and sharing | Changed. Claude Code cannot [publish artifacts](https://code.claude.com/docs/en/artifacts#availability). However, artifacts made in chat or Cowork can be shared within your organization, but not publicly. |

34| Standalone Claude Design app | Not supported. See [Encrypted with Anthropic’s key](https://platform.claude.com/docs/en/manage-claude/cmek-coverage-claude-enterprise#encrypted-with-anthropics-key). |

35| Analytics: smart reports and contribution metrics | Off. Certain analytics are disabled, regardless of admin settings: Claude smart reports (under claude.ai/analytics/insights) and Claude Code contribution metrics from GitHub (beta, under claude.ai/analytics/claude-code). |

33| Artifacts | Changed. For organizations that use Claude Code ZDR: Artifacts, including Claude Design, Claude Slides, and Claude Docs in conversations and the **Artifacts** tab, cannot be turned on. |

34| Artifact publishing and sharing | Changed. Artifacts can be shared within your organization, but not publicly. |

3635| Analytics: skills and connectors | Changed. Admin analytics for skills and connectors, in the claude.ai analytics dashboard and through the [Claude Enterprise Analytics API](https://platform.claude.com/docs/en/manage-claude/analytics-api), don’t include usage in chat, and hide the names of custom skills, plugins, and connectors. |

37| Response ratings (thumbs up and thumbs down) | Off. Members can’t rate Claude’s responses. |

36| Response ratings: thumbs up and thumbs down | Off. Members can’t rate Claude’s responses. |

3837| [Skill and plugin security scanning](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/enterprise#skill-content-scanning) | Off. The setting can’t be turned on, and skills and plugins are installed without a scan. |

39| Claude Security and routines | Off. Beta and research preview features, turned off regardless of admin settings. |

38| Claude in Slack (beta) | Off. Claude declines requests, even if an admin turns the product on. |

39| Analytics: smart reports and contribution metrics | Off. Certain analytics are disabled, regardless of admin settings: Claude smart reports (under claude.ai/analytics/insights) and Claude Code contribution metrics from GitHub (beta, under claude.ai/analytics/claude-code). |

40| Claude Security (beta) and routines (research preview) | Off. Beta and research preview features, turned off regardless of admin settings. |

41| Standalone Claude Design app (being deprecated) | Not supported. See [Encrypted with Anthropic’s key](https://platform.claude.com/docs/en/manage-claude/cmek-coverage-claude-enterprise#encrypted-with-anthropics-key). |

4042

4143## Encrypted with Anthropic’s key

4244

from line 46

4446

4547| Data | Details |

4648| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

47| Existing data | Written before [your key takes effect](https://platform.claude.com/docs/en/manage-claude/cmek-how-it-works#when-your-key-takes-effect). |

48| Standalone Claude Design app | The standalone Claude Design app at claude.ai/design is not supported with CMEK, and its data might not be encrypted under your key. The standalone app is closing. Claude Design in conversations and the **Artifacts** tab is encrypted under your key, as listed under [Encrypted with your key](https://platform.claude.com/docs/en/manage-claude/cmek-coverage-claude-enterprise#encrypted-with-your-key). |

49| Existing data before key setup | Written before [your key takes effect](https://platform.claude.com/docs/en/manage-claude/cmek-how-it-works#when-your-key-takes-effect). |

50| Standalone Claude Design app (being deprecated) | The standalone Claude Design app at claude.ai/design is not supported with CMEK, and its data might not be encrypted under your key. The standalone app is closing. Claude Design in conversations and the **Artifacts** tab is encrypted under your key, as listed under [Encrypted with your key](https://platform.claude.com/docs/en/manage-claude/cmek-coverage-claude-enterprise#encrypted-with-your-key). |

4951| Personal preferences and Cowork Global instructions | [Personal preferences - Instructions for Claude section](https://claude.ai/new#settings/account) and Cowork Global instructions. These are set at the account level and shared across all of a user’s organizations. |

5052| Account data for users in your organization | Includes names, email addresses, and profile pictures. |

5153| Preserved records | Anthropic can preserve specific records [in three narrow cases](https://platform.claude.com/docs/en/manage-claude/cmek-data-retention#limited-preservation-outside-your-key). |

52

53## Where CMEK does not apply: Claude Code telemetry

54

55When Claude Code connects through an LLM gateway or proxy (a custom `ANTHROPIC_BASE_URL`), CMEK does not apply to Claude Code’s operational telemetry. To turn this telemetry off, set the `DISABLE_TELEMETRY` environment variable to `1`, as described under [Telemetry services](https://code.claude.com/docs/en/data-usage#telemetry-services) in the Claude Code documentation.

54| Claude Code telemetry | When Claude Code connects through an LLM gateway or proxy (a custom `ANTHROPIC_BASE_URL`), CMEK does not apply to Claude Code’s operational telemetry. To turn this telemetry off, set the `DISABLE_TELEMETRY` environment variable to `1`, as described under [Telemetry services](https://code.claude.com/docs/en/data-usage#telemetry-services) in the Claude Code documentation. |

5655

manage-claude/cmek-coverage-claude-platform Changed · +16 / -17 lines

## Where CMEK does not apply: Claude Code telemetry

from line 4

44description: Look up which Claude Platform data your key encrypts, what turns off or changes, and what stays under Anthropic's key.

55---

66

7For Claude Enterprise, see [What CMEK covers on Claude Enterprise](https://platform.claude.com/docs/en/manage-claude/cmek-coverage-claude-enterprise). Beta and research preview features that aren’t listed here might not be covered by customer-managed encryption keys (CMEK).

7For Claude Enterprise, see [What CMEK covers on Claude Enterprise](https://platform.claude.com/docs/en/manage-claude/cmek-coverage-claude-enterprise).

88

99## Encrypted with your key

1010

from line 13

1313* MCP and tool configuration.

1414* [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) (beta) data, including agent configurations, environments, webhooks, sessions and their events, [memory stores](https://platform.claude.com/docs/en/managed-agents/memory) (beta) and their memories and memory versions, and [dreams](https://platform.claude.com/docs/en/managed-agents/dreams) (research preview).

1515* Batch API and Skills API data stored at rest.

16* Tool data stored at rest by web search, web fetch, code execution, bash, text editor, MCP connector (beta), structured outputs, advisor tool (beta), computer use, browser use, and context management.

16* Tool data stored at rest by web search, web fetch, code execution, bash, text editor, MCP connector (beta), structured outputs, advisor tool (beta), computer use, browser use, and context management (beta).

1717* Backups and snapshots, which inherit the key.

1818

1919## Turned off or changed

2020

21Beta and research preview features that aren’t listed on this page might not be covered by customer-managed encryption keys (CMEK).

22

2123This list is not exhaustive. Review it with your team before you set up CMEK.

2224

2325| Feature | What changes |

from line 33

3133

3234The features that store this data stay available, but the data isn’t encrypted with your key. You can turn off some of these features in **Settings**.

3335

34| Data | Details |

35| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

36| Existing data | Written before [your key takes effect](https://platform.claude.com/docs/en/manage-claude/cmek-how-it-works#when-your-key-takes-effect). |

37| Data that isn’t at rest, and data with a TTL shorter than 24 hours | For example, cache. |

38| Activity Feed, audit logs, and telemetry network traffic such as OpenTelemetry | Kept under Anthropic’s key so that you can maintain compliance even if your key can’t be used. |

39| Claude Managed Agents [vault credential](https://platform.claude.com/docs/en/managed-agents/vaults) values, such as OAuth tokens and client secrets | Write-only and never returned in API responses. |

40| [User profiles](https://platform.claude.com/docs/en/manage-claude/user-profiles) | Profile fields such as `name` and `metadata`. Don’t store sensitive personal data in profile `metadata`. |

41| Claude Console feedback | Ratings and comments that members choose to send with the **Feedback** option. No setting turns it off. |

42| [OpenTelemetry destination](https://platform.claude.com/docs/en/manage-claude/opentelemetry/api#add-a-destination) request headers, such as the API key header of your observability platform | Write-only and never returned in API responses. |

43| Account data for users in your organization | Includes names, email addresses, and profile pictures. |

44| Preserved records | Anthropic can preserve specific records [in three narrow cases](https://platform.claude.com/docs/en/manage-claude/cmek-data-retention#limited-preservation-outside-your-key). |

45

46## Where CMEK does not apply: Claude Code telemetry

47

48When Claude Code connects through an LLM gateway or proxy (a custom `ANTHROPIC_BASE_URL`), CMEK does not apply to Claude Code’s operational telemetry. To turn this telemetry off, set the `DISABLE_TELEMETRY` environment variable to `1`, as described under [Telemetry services](https://code.claude.com/docs/en/data-usage#telemetry-services) in the Claude Code documentation.

36| Data | Details |

37| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

38| Existing data before key setup | Written before [your key takes effect](https://platform.claude.com/docs/en/manage-claude/cmek-how-it-works#when-your-key-takes-effect). |

39| Data that isn’t at rest, and data with a TTL shorter than 24 hours | For example, cache. |

40| Activity Feed, audit logs, and telemetry network traffic such as OpenTelemetry (beta) | Kept under Anthropic’s key so that you can maintain compliance even if your key can’t be used. |

41| Claude Managed Agents (beta) [vault credential](https://platform.claude.com/docs/en/managed-agents/vaults) values, such as OAuth tokens and client secrets | Write-only and never returned in API responses. |

42| [User profiles](https://platform.claude.com/docs/en/manage-claude/user-profiles) | Profile fields such as `name` and `metadata`. Don’t store sensitive personal data in profile `metadata`. |

43| Claude Console feedback | Ratings and comments that members choose to send with the **Feedback** option. No setting turns it off. |

44| [OpenTelemetry destination](https://platform.claude.com/docs/en/manage-claude/opentelemetry/api#add-a-destination) (beta) request headers, such as the API key header of your observability platform | Write-only and never returned in API responses. |

45| Account data for users in your organization | Includes names, email addresses, and profile pictures. |

46| Preserved records | Anthropic can preserve specific records [in three narrow cases](https://platform.claude.com/docs/en/manage-claude/cmek-data-retention#limited-preservation-outside-your-key). |

47| Claude Code telemetry | When Claude Code connects through an LLM gateway or proxy (a custom `ANTHROPIC_BASE_URL`), CMEK does not apply to Claude Code’s operational telemetry. To turn this telemetry off, set the `DISABLE_TELEMETRY` environment variable to `1`, as described under [Telemetry services](https://code.claude.com/docs/en/data-usage#telemetry-services) in the Claude Code documentation. |

4948

manage-claude/spend-limits-api Changed · +159 / -65 lines

from line 1185

11851185

11861186## Example workflows

11871187

1188Some of these workflows combine the Spend Limits API with the [Analytics APIs](https://platform.claude.com/docs/en/manage-claude/analytics-api) cost endpoints. The Analytics cost endpoints are designed for organization-wide spend reporting across a date range. `GET /spend_limits/effective` returns the cap that currently applies to each member. Start a sweep with Analytics to discover which members to look at, then read their current caps with `/effective`.

1188Some of these workflows combine the Spend Limits API with the cost endpoint of the [Usage and Cost Analytics API](https://platform.claude.com/docs/en/manage-claude/usage-cost-analytics-api). The cost endpoint is designed for organization-wide spend reporting across a date range. `GET /spend_limits/effective` returns the cap that currently applies to each member. Start a sweep with the cost endpoint to discover which members to look at, then read their current caps with `/effective`.

11891189

1190Spend Limits endpoints require the `spend_limits` scopes and Analytics cost endpoints require `read:analytics`; see [Analytics APIs](https://platform.claude.com/docs/en/manage-claude/analytics-api) for how to provision access. The examples use one Admin API key that has the scopes of every API they call. A primary owner [selects these scopes when creating the key](https://platform.claude.com/docs/en/manage-claude/admin-api-keys#choose-scopes-for-a-claude-enterprise-key). All monetary values on both are decimal strings in minor units (cents). Both APIs paginate with an opaque cursor. Set an explicit `limit` and page through `next_page` until it’s `null` to cover the whole organization.

1190Spend Limits endpoints require the `spend_limits` scopes and the cost endpoint requires `read:analytics`. The examples use one Admin API key that has the scopes of every API they call. A primary owner [selects these scopes when creating the key](https://platform.claude.com/docs/en/manage-claude/admin-api-keys#choose-scopes-for-a-claude-enterprise-key). All monetary values on both are decimal strings in minor units (cents). Both APIs paginate with an opaque cursor. Set an explicit `limit` and page through `next_page` until it’s `null` to cover the whole organization.

11911191

1192Two of these workflows read spend from `user_cost_report`, which remains supported. For new integrations, call the cost endpoint of the [Usage and Cost Analytics API](https://platform.claude.com/docs/en/manage-claude/usage-cost-analytics-api#migrate-from-enterprise-analytics-reports) with `group_by[]=actor&actor_types[]=user_actor` to get cost for each user.

1193

11941192### Automate the increase-request review flow

11951193

11961194Run a scheduled job that fetches pending requests, applies your organization’s approval policy, and resolves each one.

from line 1437

14391437

14401438Find members approaching their cap so you can raise it before they’re blocked.

14411439

14421. Pull each member’s month-to-date spend from the Analytics API (one row for each member, highest spend first by default):

14401. Pull each member’s month-to-date spend from the Usage and Cost Analytics API (one row for each member, highest spend first by default):

14431441

14441442 <CodeGroup>

14451443 ```bash cURL

1446 curl "https://api.anthropic.com/v1/organizations/analytics/user_cost_report?starting_at=2026-06-01T00:00:00Z&limit=1000" \

1447 -H "x-api-key: $ANTHROPIC_API_KEY" \

1448 -H "anthropic-version: 2023-06-01"

1444 curl -g "https://api.anthropic.com/v1/organizations/analytics/cost?\

1445 starting_at=2026-06-01T00:00:00Z&\

1446 group_by[]=actor&\

1447 actor_types[]=user_actor&\

1448 limit=1000" \

1449 -H "anthropic-version: 2023-06-01" \

1450 -H "anthropic-beta: analytics-usage-cost-2026-08-24" \

1451 -H "x-api-key: $ANTHROPIC_API_KEY"

14491452 ```

14501453

14511454 ```bash CLI

1452 ant beta:organization:analytics:user-cost-report list \

1455 ant beta:organization:analytics:cost list \

14531456 --starting-at 2026-06-01T00:00:00Z \

1457 --actor-type user_actor \

1458 --group-by actor \

14541459 --limit 1000

14551460 ```

14561461

from line 1462

14571462 ```python Python

14581463 client = anthropic.Anthropic()

14591464

1460 cost_rows = client.beta.organization.analytics.user_cost_report.list(

1461 starting_at="2026-06-01T00:00:00Z", limit=1000

1465 cost_rows = client.beta.organization.analytics.cost.list(

1466 starting_at="2026-06-01T00:00:00Z",

1467 actor_types=["user_actor"],

1468 group_by=["actor"],

1469 limit=1000,

14621470 )

14631471

14641472 for cost_row in cost_rows:

1465 print(f"{cost_row.actor.user_id}: {cost_row.amount}")

1473 actor = cost_row.group.actor

1474 if actor is not None and actor.type == "user_actor":

1475 print(f"{actor.user_id}: {cost_row.cost.amount}")

14661476 ```

14671477

14681478 ```typescript TypeScript

14691479 const client = new Anthropic();

14701480

1471 const costRows = await client.beta.organization.analytics.userCostReport.list({

1481 const costRows = await client.beta.organization.analytics.cost.list({

14721482 starting_at: "2026-06-01T00:00:00Z",

1483 actor_types: ["user_actor"],

1484 group_by: ["actor"],

14731485 limit: 1000

14741486 });

14751487

14761488 for await (const costRow of costRows) {

1477 console.log(`${costRow.actor.user_id}: ${costRow.amount}`);

1489 const { actor } = costRow.group;

1490 if (actor?.type === "user_actor") {

1491 console.log(`${actor.user_id}: ${costRow.cost.amount}`);

1492 }

14781493 }

14791494 ```

14801495

14811496 ```csharp C#

1497 using Anthropic.Models.Beta.Organization.Analytics;

1498 using Anthropic.Models.Beta.Organization.Analytics.Cost;

1499

14821500 AnthropicClient client = new();

14831501

1484 var page = await client.Beta.Organization.Analytics.UserCostReport.List(

1502 var page = await client.Beta.Organization.Analytics.Cost.List(

14851503 new()

14861504 {

14871505 StartingAt = DateTimeOffset.Parse("2026-06-01T00:00:00Z"),

1506 ActorTypes = [BetaAnalyticsActorType.UserActor],

1507 GroupBy = [BetaAnalyticsCostGroupBy.Actor],

14881508 Limit = 1000,

14891509 }

14901510 );

from line 1511

14911511

14921512 await foreach (var costRow in page.Paginate())

14931513 {

1494 Console.WriteLine($"{costRow.Actor.UserID}: {costRow.Amount}");

1514 if (costRow.Group.Actor is { } actor && actor.TryPickReportUser(out var user))

1515 {

1516 Console.WriteLine($"{user.UserID}: {costRow.Cost.Amount}");

1517 }

14951518 }

14961519 ```

14971520

from line 1521

14981521 ```go Go

14991522 client := anthropic.NewClient()

15001523

1501 costRows := client.Beta.Organization.Analytics.UserCostReport.ListAutoPaging(context.Background(), anthropic.BetaOrganizationAnalyticsUserCostReportListParams{

1524 costRows := client.Beta.Organization.Analytics.Cost.ListAutoPaging(context.Background(), anthropic.BetaOrganizationAnalyticsCostListParams{

15021525 StartingAt: time.Date(2026, time.June, 1, 0, 0, 0, 0, time.UTC),

1526 ActorTypes: []anthropic.BetaAnalyticsActorType{anthropic.BetaAnalyticsActorTypeUserActor},

1527 GroupBy: []anthropic.BetaAnalyticsCostGroupBy{anthropic.BetaAnalyticsCostGroupByActor},

15031528 Limit: anthropic.Int(1000),

15041529 })

15051530

15061531 for costRows.Next() {

15071532 costRow := costRows.Current()

1508 fmt.Printf("%s: %s\n", costRow.Actor.UserID, costRow.Amount)

1533 if user, ok := costRow.Group.Actor.AsAny().(anthropic.BetaAnalyticsReportUserActor); ok {

1534 fmt.Printf("%s: %s\n", user.UserID, costRow.Cost.Amount)

1535 }

15091536 }

15101537 if err := costRows.Err(); err != nil {

15111538 log.Fatal(err)

from line 1540

15131540 ```

15141541

15151542 ```java Java

1516 import com.anthropic.models.beta.organization.analytics.usercostreport.UserCostReportListParams;

1543 import com.anthropic.models.beta.organization.analytics.BetaAnalyticsActorType;

1544 import com.anthropic.models.beta.organization.analytics.cost.BetaAnalyticsCostGroupBy;

1545 import com.anthropic.models.beta.organization.analytics.cost.CostListParams;

15171546 import java.time.OffsetDateTime;

15181547

15191548 void main() {

15201549 AnthropicClient client = AnthropicOkHttpClient.fromEnv();

15211550

1522 var params = UserCostReportListParams.builder()

1551 var params = CostListParams.builder()

15231552 .startingAt(OffsetDateTime.parse("2026-06-01T00:00:00Z"))

1553 .addActorType(BetaAnalyticsActorType.USER_ACTOR)

1554 .addGroupBy(BetaAnalyticsCostGroupBy.ACTOR)

15241555 .limit(1000)

15251556 .build();

1526 var costRows = client.beta().organization().analytics().userCostReport().list(params);

1557 var costRows = client.beta().organization().analytics().cost().list(params);

15271558

15281559 for (var costRow : costRows.autoPager()) {

1529 IO.println(costRow.actor().userId() + ": " + costRow.amount());

1560 costRow.group().actor().flatMap(actor -> actor.user()).ifPresent(user ->

1561 IO.println(user.userId() + ": " + costRow.cost().amount())

1562 );

15301563 }

15311564 }

15321565 ```

15331566

15341567 ```php PHP

1568 use Anthropic\Beta\Organization\Analytics\AnalyticsReportUserActor;

1569 // ...

1570

15351571 $client = new Client();

15361572

1537 $costRows = $client->beta->organization->analytics->userCostReport->list(

1573 $costRows = $client->beta->organization->analytics->cost->list(

15381574 startingAt: new \DateTimeImmutable('2026-06-01T00:00:00Z'),

1575 actorTypes: ['user_actor'],

1576 groupBy: ['actor'],

15391577 limit: 1000,

15401578 );

15411579

15421580 foreach ($costRows->pagingEachItem() as $costRow) {

1543 echo "{$costRow->actor->userID}: {$costRow->amount}\n";

1581 $actor = $costRow->group->actor;

1582 if ($actor instanceof AnalyticsReportUserActor) {

1583 echo "{$actor->userID}: {$costRow->cost->amount}\n";

1584 }

15441585 }

15451586 ```

15461587

from line 1588

15471588 ```ruby Ruby

15481589 client = Anthropic::Client.new

15491590

1550 page = client.beta.organization.analytics.user_cost_report.list(

1591 page = client.beta.organization.analytics.cost.list(

15511592 starting_at: Time.utc(2026, 6, 1),

1593 actor_types: [:user_actor],

1594 group_by: [:actor],

15521595 limit: 1000

15531596 )

15541597

15551598 page.auto_paging_each do |cost_row|

1556 puts "#{cost_row.actor.user_id}: #{cost_row.amount}"

1599 actor = cost_row.group.actor

1600 if actor.is_a?(Anthropic::Models::Beta::Organization::BetaAnalyticsReportUserActor)

1601 puts "#{actor.user_id}: #{cost_row.cost.amount}"

1602 end

15571603 end

15581604 ```

15591605 </CodeGroup>

15601606

1561 Each row contains `actor.user_id`, `actor.email_address`, and `amount` (the member’s spend in cents). Page through `next_page` to cover the whole organization.

1607 Each row contains `group.actor.user_id`, `group.actor.email_address`, and `cost.amount` (the member’s spend in cents). Page through `next_page` to cover the whole organization.

15621608

156316092. For the top spenders (or everyone above a dollar threshold), fetch effective caps in batches:

15641610

from line 1763

17171763

17181764Surface members whose spend has jumped week over week.

17191765

17201. Pull per-member daily cost for the trailing 2 weeks from the Analytics API:

17661. Pull per-member daily cost for the trailing 2 weeks from the Usage and Cost Analytics API:

17211767

17221768 <CodeGroup>

17231769 ```bash cURL

1724 curl "https://api.anthropic.com/v1/organizations/analytics/user_cost_report?starting_at=2026-06-09T00:00:00Z&ending_at=2026-06-23T00:00:00Z&bucket_width=1d&limit=1000" \

1725 -H "x-api-key: $ANTHROPIC_API_KEY" \

1726 -H "anthropic-version: 2023-06-01"

1770 curl -g "https://api.anthropic.com/v1/organizations/analytics/cost?\

1771 starting_at=2026-06-09T00:00:00Z&\

1772 ending_at=2026-06-23T00:00:00Z&\

1773 time_bucket_width=1d&\

1774 group_by[]=actor&\

1775 actor_types[]=user_actor&\

1776 limit=1000" \

1777 -H "anthropic-version: 2023-06-01" \

1778 -H "anthropic-beta: analytics-usage-cost-2026-08-24" \

1779 -H "x-api-key: $ANTHROPIC_API_KEY"

17271780 ```

17281781

17291782 ```bash CLI

1730 ant beta:organization:analytics:user-cost-report list \

1783 ant beta:organization:analytics:cost list \

17311784 --starting-at 2026-06-09T00:00:00Z \

17321785 --ending-at 2026-06-23T00:00:00Z \

1733 --bucket-width 1d \

1786 --time-bucket-width 1d \

1787 --actor-type user_actor \

1788 --group-by actor \

17341789 --limit 1000

17351790 ```

17361791

from line 1792

17371792 ```python Python

17381793 client = anthropic.Anthropic()

17391794

1740 cost_rows = client.beta.organization.analytics.user_cost_report.list(

1795 cost_rows = client.beta.organization.analytics.cost.list(

17411796 starting_at="2026-06-09T00:00:00Z",

17421797 ending_at="2026-06-23T00:00:00Z",

1743 bucket_width="1d",

1798 time_bucket_width="1d",

1799 actor_types=["user_actor"],

1800 group_by=["actor"],

17441801 limit=1000,

17451802 )

17461803

17471804 for cost_row in cost_rows:

1748 print(f"{cost_row.actor.user_id} {cost_row.starting_at}: {cost_row.amount}")

1805 actor = cost_row.group.actor

1806 if actor is not None and actor.type == "user_actor":

1807 print(f"{actor.user_id} {cost_row.starting_at}: {cost_row.cost.amount}")

17491808 ```

17501809

17511810 ```typescript TypeScript

17521811 const client = new Anthropic();

17531812

1754 const costRows = await client.beta.organization.analytics.userCostReport.list({

1813 const costRows = await client.beta.organization.analytics.cost.list({

17551814 starting_at: "2026-06-09T00:00:00Z",

17561815 ending_at: "2026-06-23T00:00:00Z",

1757 bucket_width: "1d",

1816 time_bucket_width: "1d",

1817 actor_types: ["user_actor"],

1818 group_by: ["actor"],

17581819 limit: 1000

17591820 });

17601821

17611822 for await (const costRow of costRows) {

1762 console.log(`${costRow.actor.user_id} ${costRow.starting_at}: ${costRow.amount}`);

1823 const { actor } = costRow.group;

1824 if (actor?.type === "user_actor") {

1825 console.log(`${actor.user_id} ${costRow.starting_at}: ${costRow.cost.amount}`);

1826 }

17631827 }

17641828 ```

17651829

17661830 ```csharp C#

1767 using Anthropic.Models.Beta.Organization.Analytics.UserCostReport;

1831 using Anthropic.Models.Beta.Organization.Analytics;

1832 using Anthropic.Models.Beta.Organization.Analytics.Cost;

17681833

17691834 AnthropicClient client = new();

17701835

1771 var page = await client.Beta.Organization.Analytics.UserCostReport.List(

1836 var page = await client.Beta.Organization.Analytics.Cost.List(

17721837 new()

17731838 {

17741839 StartingAt = DateTimeOffset.Parse("2026-06-09T00:00:00Z"),

17751840 EndingAt = DateTimeOffset.Parse("2026-06-23T00:00:00Z"),

1776 BucketWidth = BucketWidth.Day,

1841 TimeBucketWidth = BetaAnalyticsTimeBucketWidth.Day,

1842 ActorTypes = [BetaAnalyticsActorType.UserActor],

1843 GroupBy = [BetaAnalyticsCostGroupBy.Actor],

17771844 Limit = 1000,

17781845 }

17791846 );

from line 1847

17801847

17811848 await foreach (var costRow in page.Paginate())

17821849 {

1783 Console.WriteLine($"{costRow.Actor.UserID} {costRow.StartingAt}: {costRow.Amount}");

1850 if (costRow.Group.Actor is { } actor && actor.TryPickReportUser(out var user))

1851 {

1852 Console.WriteLine($"{user.UserID} {costRow.StartingAt}: {costRow.Cost.Amount}");

1853 }

17841854 }

17851855 ```

17861856

from line 1857

17871857 ```go Go

17881858 client := anthropic.NewClient()

17891859

1790 costRows := client.Beta.Organization.Analytics.UserCostReport.ListAutoPaging(context.Background(), anthropic.BetaOrganizationAnalyticsUserCostReportListParams{

1791 StartingAt: time.Date(2026, time.June, 9, 0, 0, 0, 0, time.UTC),

1792 EndingAt: anthropic.Time(time.Date(2026, time.June, 23, 0, 0, 0, 0, time.UTC)),

1793 BucketWidth: anthropic.BetaOrganizationAnalyticsUserCostReportListParamsBucketWidthDay,

1794 Limit: anthropic.Int(1000),

1860 costRows := client.Beta.Organization.Analytics.Cost.ListAutoPaging(context.Background(), anthropic.BetaOrganizationAnalyticsCostListParams{

1861 StartingAt: time.Date(2026, time.June, 9, 0, 0, 0, 0, time.UTC),

1862 EndingAt: anthropic.Time(time.Date(2026, time.June, 23, 0, 0, 0, 0, time.UTC)),

1863 TimeBucketWidth: anthropic.BetaAnalyticsTimeBucketWidthDay,

1864 ActorTypes: []anthropic.BetaAnalyticsActorType{anthropic.BetaAnalyticsActorTypeUserActor},

1865 GroupBy: []anthropic.BetaAnalyticsCostGroupBy{anthropic.BetaAnalyticsCostGroupByActor},

1866 Limit: anthropic.Int(1000),

17951867 })

17961868

17971869 for costRows.Next() {

17981870 costRow := costRows.Current()

1799 fmt.Printf("%s %s: %s\n", costRow.Actor.UserID, costRow.StartingAt, costRow.Amount)

1871 if user, ok := costRow.Group.Actor.AsAny().(anthropic.BetaAnalyticsReportUserActor); ok {

1872 fmt.Printf("%s %s: %s\n", user.UserID, costRow.StartingAt.Format(time.RFC3339), costRow.Cost.Amount)

1873 }

18001874 }

18011875 if err := costRows.Err(); err != nil {

18021876 log.Fatal(err)

from line 1878

18041878 ```

18051879

18061880 ```java Java

1807 import com.anthropic.models.beta.organization.analytics.usercostreport.UserCostReportListParams;

1881 import com.anthropic.models.beta.organization.analytics.BetaAnalyticsActorType;

1882 import com.anthropic.models.beta.organization.analytics.BetaAnalyticsTimeBucketWidth;

1883 import com.anthropic.models.beta.organization.analytics.cost.BetaAnalyticsCostGroupBy;

1884 import com.anthropic.models.beta.organization.analytics.cost.CostListParams;

18081885 import java.time.OffsetDateTime;

18091886

18101887 void main() {

18111888 AnthropicClient client = AnthropicOkHttpClient.fromEnv();

18121889

1813 var params = UserCostReportListParams.builder()

1890 var params = CostListParams.builder()

18141891 .startingAt(OffsetDateTime.parse("2026-06-09T00:00:00Z"))

18151892 .endingAt(OffsetDateTime.parse("2026-06-23T00:00:00Z"))

1816 .bucketWidth(UserCostReportListParams.BucketWidth.DAY)

1893 .timeBucketWidth(BetaAnalyticsTimeBucketWidth.DAY)

1894 .addActorType(BetaAnalyticsActorType.USER_ACTOR)

1895 .addGroupBy(BetaAnalyticsCostGroupBy.ACTOR)

18171896 .limit(1000)

18181897 .build();

1819 var costRows = client.beta().organization().analytics().userCostReport().list(params);

1898 var costRows = client.beta().organization().analytics().cost().list(params);

18201899

18211900 for (var costRow : costRows.autoPager()) {

1822 IO.println(costRow.actor().userId() + " " + costRow.startingAt().orElseThrow() + ": " + costRow.amount());

1901 costRow.group().actor().flatMap(actor -> actor.user()).ifPresent(user ->

1902 IO.println(user.userId() + " " + costRow.startingAt() + ": " + costRow.cost().amount())

1903 );

18231904 }

18241905 }

18251906 ```

18261907

18271908 ```php PHP

1909 use Anthropic\Beta\Organization\Analytics\AnalyticsReportUserActor;

1910 // ...

1911

18281912 $client = new Client();

18291913

1830 $costRows = $client->beta->organization->analytics->userCostReport->list(

1914 $costRows = $client->beta->organization->analytics->cost->list(

18311915 startingAt: new \DateTimeImmutable('2026-06-09T00:00:00Z'),

18321916 endingAt: new \DateTimeImmutable('2026-06-23T00:00:00Z'),

1833 bucketWidth: '1d',

1917 timeBucketWidth: '1d',

1918 actorTypes: ['user_actor'],

1919 groupBy: ['actor'],

18341920 limit: 1000,

18351921 );

18361922

18371923 foreach ($costRows->pagingEachItem() as $costRow) {

1838 $startingAt = $costRow->startingAt?->format(\DateTimeInterface::ATOM);

1839 echo "{$costRow->actor->userID} {$startingAt}: {$costRow->amount}\n";

1924 $actor = $costRow->group->actor;

1925 if ($actor instanceof AnalyticsReportUserActor) {

1926 $startingAt = $costRow->startingAt->format(\DateTimeInterface::ATOM);

1927 echo "{$actor->userID} {$startingAt}: {$costRow->cost->amount}\n";

1928 }

18401929 }

18411930 ```

18421931

from line 1932

18431932 ```ruby Ruby

18441933 client = Anthropic::Client.new

18451934

1846 page = client.beta.organization.analytics.user_cost_report.list(

1935 page = client.beta.organization.analytics.cost.list(

18471936 starting_at: Time.utc(2026, 6, 9),

18481937 ending_at: Time.utc(2026, 6, 23),

1849 bucket_width: :"1d",

1938 time_bucket_width: :"1d",

1939 actor_types: [:user_actor],

1940 group_by: [:actor],

18501941 limit: 1000

18511942 )

18521943

18531944 page.auto_paging_each do |cost_row|

1854 puts "#{cost_row.actor.user_id} #{cost_row.starting_at}: #{cost_row.amount}"

1945 actor = cost_row.group.actor

1946 if actor.is_a?(Anthropic::Models::Beta::Organization::BetaAnalyticsReportUserActor)

1947 puts "#{actor.user_id} #{cost_row.starting_at}: #{cost_row.cost.amount}"

1948 end

18551949 end

18561950 ```

18571951 </CodeGroup>

18581952

1859 With `bucket_width` set, each member spans one row for each day with usage. Page through `next_page` to collect every member’s full series.

1953 With `time_bucket_width` set, each member spans one row for each day with usage. Page through `next_page` to collect every member’s full series.

18601954

18612. Group rows by `actor.user_id`. For each member, sum the most recent 7 days and the prior 7 days. Flag members whose recent week exceeds the prior week by your chosen multiple (for example, three). Recent-day cost is provisional and can be revised upward; for repeatable comparisons, set `ending_at` at or before a previously returned `data_refreshed_at` (see [Data availability and freshness](https://platform.claude.com/docs/en/manage-claude/analytics-api#data-availability-and-freshness)).

19552. Group rows by `group.actor.user_id`. For each member, sum the most recent 7 days and the prior 7 days. Flag members whose recent week exceeds the prior week by your chosen multiple (for example, three). Cost for recent days can still change. For repeatable comparisons, set `ending_at` at or before a `data_refreshed_at` you have already seen (see [Data freshness](https://platform.claude.com/docs/en/manage-claude/usage-cost-analytics-api#data-freshness)).

18621956

186319573. Act on flagged members: adjust the cap with `POST /v1/organizations/spend_limits`, or contact the member.

18641958

manage-claude/usage-cost-api Changed · +4 / -0 lines

### Why does the usage report show a service account that I didn’t create?

from line 324

324324

325325API usage from playground in the Claude Console (and from the legacy Anthropic Workbench before it) is not associated with an API key, so `api_key_id` is `null` even when grouping by that dimension.

326326

327### Why does the usage report show a service account that I didn’t create?

328

329Usage from some [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) sessions is reported under an Anthropic-managed service account (`svac_...`). It isn’t listed with the service accounts that you create. See [Find session usage across your organization](https://platform.claude.com/docs/en/managed-agents/session-observability#find-session-usage-across-your-organization).

330

327331### How is the default workspace represented?

328332

329333Usage and costs attributed to the default workspace have a `null` value for `workspace_id`.

managed-agents/session-observability Changed · +14 / -1 lines

### Find session usage across your organization

from line 38

3838

3939## Inspect a session in the Console

4040

41The session viewer is only accessible to Developers and Admins. To open it, go to the [Sessions](https://platform.claude.com/sessions) page (`platform.claude.com/sessions`) in the Claude Console. The list shows every session in the workspace with its status, agent, token usage, cost, and creation time. Select a session to open it.

41The session viewer is only accessible to Developers and Admins. To open it, go to the [Sessions](https://platform.claude.com/sessions) page (`platform.claude.com/sessions`) in the Claude Console. The list shows every session in the workspace with its status, agent, token usage, cost, creator, and creation time. Select a session to open it.

4242

4343The session viewer shows:

4444

from line 117

117117### Enforce a spend limit

118118

119119To enforce a spend limit, set a session budget rather than polling usage and stopping the session yourself. The platform prices the session’s consumption continuously, and pauses each thread before its next model request once the list cost reaches the cap. See [When a session reaches its budget](https://platform.claude.com/docs/en/managed-agents/budgets#when-a-session-reaches-its-budget) for what that looks like on the stream.

120

121### Find session usage across your organization

122

123Session usage counts toward your organization’s totals on the [Usage](https://platform.claude.com/usage) page (`platform.claude.com/usage`) and the [Cost](https://platform.claude.com/cost) page (`platform.claude.com/cost`) in the Claude Console. To see token usage by agent, set **Group by** to **Agent** on the **Usage** page.

124

125Session usage also appears in the [usage report](https://platform.claude.com/docs/en/api/beta/organization/usage_report/retrieve_messages) from the [Usage and Cost API](https://platform.claude.com/docs/en/manage-claude/usage-cost-api). To see which account it’s reported under, group the report by one of these fields:

126

127* **`account_id`:** The member who started the session. This covers sessions started in the Console or with a [personal key](https://platform.claude.com/docs/en/manage-claude/authentication#key-types) scoped to a single workspace.

128* **`service_account_id`:** An Anthropic-managed service account (`svac_...`). This covers sessions started with a workspace key or by a [deployment](https://platform.claude.com/docs/en/managed-agents/scheduled-deployments). For this usage, `api_key_id` and `account_id` are `null`.

129

130Anthropic creates one of these service accounts in each workspace where sessions run. It isn’t listed with the service accounts that you create, and the Admin API’s service account endpoints don’t return it. On the **Usage** page, the **Account** filter lists it by its ID. When you set **Group by** to **API key**, its usage is labeled **Managed Agents**.

131

132To see who started a session, check the **Created by** column on the [Sessions](https://platform.claude.com/sessions) page.

120133

121134## Debugging tips

122135

agents-and-tools/tool-use/computer-use-tool Changed · +1 / -1 lines

from line 1833

18331833

18341834* Place one `cache_control` breakpoint after the system prompt and tool definitions, and up to three more on the last `tool_result` block of each of the most recent turns, advancing them each turn. Within a [batch action](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool#batch-actions), markers on several blocks act as a single breakpoint, but each still counts toward the limit of four, so use at most one in any turn.

18351835* Prune old screenshots in *batches*, not one each turn. Dropping a screenshot every turn changes the prefix every turn and invalidates the cache. A reasonable default is to keep the last three screenshots and prune every 25 turns, so the prefix stays byte-identical between prune events; if your screenshots exceed the stricter limit, choose an interval that keeps each request at 20 or fewer images.

1836* On Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5, avoid pruning on the client: removing an earlier screenshot from a request [invalidates every later thinking block](https://platform.claude.com/docs/en/build-with-claude/thinking#preserved-in-conversation) in that request and in every later request. Resize screenshots to stay under the stricter limit instead and use server-side [tool result clearing](https://platform.claude.com/docs/en/build-with-claude/context-editing#tool-result-clearing) to drop old ones from the context. If you must prune, keep [`prefix_mismatch_behavior: "drop_block"`](https://platform.claude.com/docs/en/build-with-claude/thinking#preserved-thinking-controls) set from then on; after each prune, Claude continues without the thinking produced since the pruned screenshot, on that request and every later one. 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, keep the history append-only or strip every `thinking` and `redacted_thinking` block after the pruned screenshot.

1836* On Claude 5.1 and later models, avoid pruning on the client: removing an earlier screenshot from a request [invalidates every later thinking block](https://platform.claude.com/docs/en/build-with-claude/thinking#preserved-in-conversation) in that request and in every later request. Resize screenshots to stay under the stricter limit instead and use server-side [tool result clearing](https://platform.claude.com/docs/en/build-with-claude/context-editing#tool-result-clearing) to drop old ones from the context. If you must prune, keep [`prefix_mismatch_behavior: "drop_block"`](https://platform.claude.com/docs/en/build-with-claude/thinking#preserved-thinking-controls) set from then on; after each prune, Claude continues without the thinking produced since the pruned screenshot, on that request and every later one. 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, keep the history append-only or strip every `thinking` and `redacted_thinking` block after the pruned screenshot.

18371837

18381838### Diagnose click issues

18391839

api/errors Changed · +1 / -1 lines

from line 540

540540

541541### Thinking block bound to a different conversation

542542

543This 400 `invalid_request_error` usually means a thinking block you sent back failed the prefix check: something before the block changed after the block was produced, such as the `system` prompt, `tools`, or an earlier message. Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5 run this check. For requests that don’t set `prefix_mismatch_behavior`, [When `prefix_mismatch_behavior` is unset](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#enforcement) shows which ones get this error. The message starts with the position of the first failing block:

543This 400 `invalid_request_error` usually means a thinking block you sent back failed the prefix check: something before the block changed after the block was produced, such as the `system` prompt, `tools`, or an earlier message. Claude 5.1 and later models run this check. For requests that don’t set `prefix_mismatch_behavior`, [When `prefix_mismatch_behavior` is unset](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#enforcement) shows which ones get this error. The message starts with the position of the first failing block:

544544

545545```text wrap

546546messages.{i}.content.{j}: Invalid `signature` in `thinking` block. The block is bound to a different conversation. Remove the block, or set `thinking.block_binding.prefix_mismatch_behavior` to "drop_block".

api/versioning Changed · +2 / -2 lines

from line 47

4747 * The per-user [usage](https://platform.claude.com/docs/en/api/beta/organization/analytics/user_usage_report/list) and [cost](https://platform.claude.com/docs/en/api/beta/organization/analytics/user_cost_report/list) reports no longer have `actor.email`. Use `actor.email_address` instead.

4848 * The [activity summaries](https://platform.claude.com/docs/en/api/beta/organization/analytics/summaries/list) response no longer has `summaries`. Use `data` instead.

4949

50- `2023-06-01`

50* `2023-06-01`

5151

5252 * New format for [streaming](https://platform.claude.com/docs/en/build-with-claude/streaming) server-sent events (SSE):

5353

from line 57

5757

5858 * Removed legacy `exception` and `truncated` values in responses.

5959

60- `2023-01-01`: Initial release.

60* `2023-01-01`: Initial release.

6161

build-with-claude/context-editing Changed · +1 / -1 lines

from line 89

8989

9090Context editing is applied server-side before the prompt reaches Claude. Your client application maintains the full, unmodified conversation history. You do not need to sync your client state with the edited version. Continue managing your full conversation history locally as you normally would.

9191

92On Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5, server-side context management never invalidates thinking blocks. Client-side edits to earlier turns can invalidate the thinking blocks in every later assistant turn. See [Keeping the prefix unchanged](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#prefix-check).

92On Claude 5.1 and later models, server-side context management never invalidates thinking blocks. Client-side edits to earlier turns can invalidate the thinking blocks in every later assistant turn. See [Keeping the prefix unchanged](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#prefix-check).

9393

9494### Context editing and prompt caching

9595

build-with-claude/prompt-caching Changed · +2 / -2 lines

from line 612

612612**Cache breakpoints themselves don’t add any cost.** You are only charged for:

613613

614614* **Cache writes:** When new content is written to the cache (25% more than base input tokens for 5-minute TTL)

615* **Cache reads:** When cached content is used (10% of base input token price, or 2.5% on Claude Fable 5.1 and Claude Mythos 5.1, and 5% on Claude Opus 5.5 and Claude Sonnet 5.5)

615* **Cache reads:** When cached content is used (10% of base input token price, with [per-model exceptions](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pricing))

616616* **Regular input tokens:** For any uncached content

617617

618618Adding more `cache_control` breakpoints doesn’t increase your costs; you still pay the same amount based on what content is actually cached and read. The breakpoints give you control over what sections can be cached independently.

from line 689

689689| **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). |

690690| **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. |

691691| **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). |

692| **Dropped thinking blocks** | ✓ | ✓ | ✘ | When the API drops a Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5, or Claude Haiku 5.5 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. |

692| **Dropped thinking blocks** | ✓ | ✓ | ✘ | When the API drops a Claude 5.1 or later model’s 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. |

693693

694694On 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).

695695

build-with-claude/prompt-engineering/claude-prompting-best-practices Changed · +1 / -1 lines

from line 1127

11271127

112811286. **Tune anti-laziness prompting:** If your prompts previously encouraged the model to be more thorough or use tools more aggressively, reduce that guidance. Claude 4.6 models are more proactive and might overtrigger on instructions that were needed for previous models.

11291129

11307. **Pass thinking blocks back unchanged and keep history append-only:** Append each assistant turn exactly as the API returned it, thinking blocks included. On Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5, editing earlier messages, rebuilding `system` or `tools`, or summarizing older turns in place between requests [invalidates every later thinking block](https://platform.claude.com/docs/en/build-with-claude/thinking#preserved-in-conversation). Move those changes to mid-conversation system messages and server-side context management. See [Keep the conversation history append-only](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1#keep-the-conversation-history-append-only).

11307. **Pass thinking blocks back unchanged and keep history append-only:** Append each assistant turn exactly as the API returned it, thinking blocks included. On Claude 5.1 and later models, editing earlier messages, rebuilding `system` or `tools`, or summarizing older turns in place between requests [invalidates every later thinking block](https://platform.claude.com/docs/en/build-with-claude/thinking#preserved-in-conversation). Move those changes to mid-conversation system messages and server-side context management. See [Keep the conversation history append-only](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-1#keep-the-conversation-history-append-only).

11311131

11321132For detailed migration steps, see the [Migration guide](https://platform.claude.com/docs/en/about-claude/models/migration-guide).

11331133

build-with-claude/thinking-troubleshooting Changed · +1 / -1 lines

from line 152

152152

153153## A 400 error says a thinking block signature is invalid

154154

155A request that replays earlier thinking blocks to Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5, or Claude Haiku 5.5 can fail with a 400 `invalid_request_error` whose message reads:

155A request that replays earlier thinking blocks to a Claude 5.1 or later model can fail with a 400 `invalid_request_error` whose message reads:

156156

157157```text wrap

158158messages.{i}.content.{j}: Invalid `signature` in `thinking` block. The block is bound to a different conversation. Remove the block, or set `thinking.block_binding.prefix_mismatch_behavior` to "drop_block".

cli-sdks-libraries/cli/using Changed · +0 / -2 lines

from line 51

5151```yaml Output

5252type: model

5353id: claude-opus-5-5

54display_name: Claude Opus 5.5

55created_at: "2026-09-22T00:00:00Z"

5654...

5755```

5856

manage-claude/admin-api Changed · +1 / -2 lines

from line 17

1717* The workspace endpoints: create, get, list, update, and archive on `/v1/organizations/workspaces`.

1818* The external key endpoints, for [CMEK](https://platform.claude.com/docs/en/manage-claude/cmek-claude-platform-on-aws): register, get, list, update, and delete on `/v1/organizations/external_keys`. There is no validate endpoint, because keys are validated when attached to a workspace.

1919* The [telemetry destination endpoints](https://platform.claude.com/docs/en/api/claude-platform-on-aws-iam-actions#telemetry-destinations).

20

21- The [Usage and Cost Analytics API](https://platform.claude.com/docs/en/manage-claude/usage-cost-analytics-api) endpoints: `/v1/organizations/analytics/usage` and `/v1/organizations/analytics/cost`.

20* The [Usage and Cost Analytics API](https://platform.claude.com/docs/en/manage-claude/usage-cost-analytics-api) endpoints: `/v1/organizations/analytics/usage` and `/v1/organizations/analytics/cost`.

2221

2322Organization members, workspace members, invites, API keys, the legacy [Usage and Cost API](https://platform.claude.com/docs/en/manage-claude/usage-cost-api), and the rate limit reports aren’t available on Claude Platform on AWS.

2423

manage-claude/usage-cost-analytics-api Changed · +1 / -1 lines

from line 278

278278

279279The `actor` dimension is who a request is attributed to: a user, a service account, a federated cloud identity (an AWS or Google Cloud principal, for organizations that access Claude through their cloud platform), or, when none of those is behind the request, the API key itself. When you group by `actor`, each row’s `actor` is an object whose `type` says which kind it is. Usage that can’t be attributed to any identity has `actor: null`.

280280

281[Personal keys and service account keys](https://platform.claude.com/docs/en/manage-claude/authentication#key-types) act as the user or service account they’re linked to, so their requests show that identity as the `actor` and the key in `api_key_id`. Legacy workspace keys aren’t linked to an identity, so the key appears as both the `actor` and the `api_key_id`. The exception is the key Claude Code creates when a member signs in with their Claude Console account: it lives in the [Claude Code workspace](https://platform.claude.com/docs/en/manage-claude/workspaces#claude-code-workspace), and its usage is attributed to that member. Requests made without an API key, such as from the Claude Console or with a [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) token, have `api_key_id: null`; a federated workload’s `actor` is its service account. To include usage with no API key in an `api_key_ids[]` filter, add an empty entry: `api_key_ids[]=`.

281[Personal keys and service account keys](https://platform.claude.com/docs/en/manage-claude/authentication#key-types) act as the user or service account they’re linked to, so their requests show that identity as the `actor` and the key in `api_key_id`. Legacy workspace keys aren’t linked to an identity, so the key appears as both the `actor` and the `api_key_id`. The exception is a key that Claude Code creates for a member at sign-in: it lives in the [Claude Code workspace](https://platform.claude.com/docs/en/manage-claude/workspaces#claude-code-workspace), and its usage is attributed to that member. Requests made without an API key, such as from the Claude Console, from Claude Code after a [sign-in without an API key](https://code.claude.com/docs/en/authentication#sign-in-without-an-api-key), or with a [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) token, have `api_key_id: null`. After a sign-in without an API key, the `actor` is the member who signed in; a federated workload’s `actor` is its service account. To include usage with no API key in an `api_key_ids[]` filter, add an empty entry: `api_key_ids[]=`.

282282

283283The `api_key_ids[]` and `actor_ids[]` filters answer different questions. `api_key_ids[]=apikey_...` matches every request the key authenticated, whoever it is attributed to. `actor_ids[]=apikey_...` matches only requests attributed to the key itself.

284284

managed-agents/multiagent-orchestration Changed · +1 / -1 lines

from line 1244

12441244

12451245No `agent.tool_use` events are emitted for a consultation, and no `agent.thread_message_sent` event appears on the session’s event stream, because the consultation input is composed by the platform rather than sent by the agent. If you list the advisor thread’s own events, the advice also appears there as an `agent.thread_message_sent` event. The advice delivery (event 3) is not guaranteed to arrive before the advisor thread’s idle and terminated events, so don’t treat those as a signal that the advice has already been delivered.

12461246

1247Whether your client can read the advice is the advisor model’s policy. It mirrors the [result variants](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#result-variants) split on the Messages API advisor tool. An advisor model that returns plaintext results there delivers readable text here. One that returns redacted results delivers a `[{"type": "redacted"}]` placeholder on every client surface, while the agent still reads the full advice server-side. The preceding example uses the newest Opus model available to you as the advisor. Claude Opus 5.5 returns redacted results, so your client sees only the placeholder. To read the advice on the event stream, use an advisor that returns plaintext, such as Claude Opus 4.8. A model’s policy can change with no change to the API, so handle both `text` and `redacted` blocks. Some agent models pair only with redacted-result advisors; see the advisor tool’s [Model compatibility](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#model-compatibility) section. Advisor thinking is never surfaced. Clients cannot send `redacted` blocks themselves; an event containing one is rejected with a 400 validation error.

1247Whether your client can read the advice is the advisor model’s policy. It mirrors the [result variants](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#result-variants) split on the Messages API advisor tool. An advisor model that returns plaintext results there delivers readable text here. One that returns redacted results delivers a `[{"type": "redacted"}]` placeholder on every client surface, while the agent still reads the full advice server-side. The preceding example uses the newest Opus model available to you as the advisor. It returns redacted results, so your client sees only the placeholder. To read the advice on the event stream, use an advisor that returns plaintext, such as Claude Opus 4.8. A model’s policy can change with no change to the API, so handle both `text` and `redacted` blocks. Some agent models pair only with redacted-result advisors; see the advisor tool’s [Model compatibility](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#model-compatibility) section. Advisor thinking is never surfaced. Clients cannot send `redacted` blocks themselves; an event containing one is rejected with a 400 validation error.

12481248

12491249A failed or interrupted consultation never fails the agent’s turn: the agent continues after a generic notice that the consultation failed. A session-level `user.interrupt` during a consultation terminates the advisor thread with no advice delivered; a `user.interrupt` with the advisor thread’s `session_thread_id` (java: `sessionThreadId`; php: `sessionThreadID`; csharp, go: `SessionThreadID`) abandons only that consultation.

12501250

One read of Claude Developer Platformapi-20261029T233709Z

What this read moved