api-20260924T173729Z / page 2 of 4 / documentation capture

api/compliance/apps/sessions/local/messages Changed · +8 / -1 lines

from line 19

1919honored for 24 hours: a cursor older than that is rejected with an

2020explicit 400; restart the walk to read under the current boundary.

2121

22On a very large session, some pages are too large to read and return a

23400; retrying does not help. If the request used `order=desc`, read the

24session oldest first from its first page instead (omit `order` and

25`page`, then follow `next_page`). Rarely, an oldest-first page returns

26this 400 too; contact Anthropic support and quote the `request-id`

27response header.

28

2229### Path parameters

2330

2431- `local_session_id: string`

from line 40

3340

3441- `order: optional "asc" or "desc"`

3542

36 Sort direction. `asc` (oldest-first, default) or `desc`.

43 Sort direction. `asc` (oldest-first, default) or `desc`. On very large sessions some pages are too large to read and return a 400, far more often with `desc`; read those sessions with `asc`, starting again from the first page.

3744

3845 default: asc

3946

api/compliance/apps/sessions/local/messages/list Changed · +8 / -1 lines

from line 17

1717honored for 24 hours: a cursor older than that is rejected with an

1818explicit 400; restart the walk to read under the current boundary.

1919

20On a very large session, some pages are too large to read and return a

21400; retrying does not help. If the request used `order=desc`, read the

22session oldest first from its first page instead (omit `order` and

23`page`, then follow `next_page`). Rarely, an oldest-first page returns

24this 400 too; contact Anthropic support and quote the `request-id`

25response header.

26

2027## Path parameters

2128

2229- `local_session_id: string`

from line 38

3138

3239- `order: optional "asc" or "desc"`

3340

34 Sort direction. `asc` (oldest-first, default) or `desc`.

41 Sort direction. `asc` (oldest-first, default) or `desc`. On very large sessions some pages are too large to read and return a 400, far more often with `desc`; read those sessions with `asc`, starting again from the first page.

3542

3643 default: asc

3744

api/compliance/organizations/settings Changed · +6 / -2 lines

from line 95

9595

9696 default: boolean

9797

98 - `name: "access_transparency_enabled" or "ai_powered_artifacts_enabled" or "api_workbench_feedback_collection_enabled" or 58 more`

98 - `name: "access_transparency_enabled" or "ai_powered_artifacts_enabled" or "api_workbench_feedback_collection_enabled" or 59 more`

9999

100100 - `"access_transparency_enabled"`

101101

from line 199

199199

200200 - `"org_wide_skill_sharing_enabled"`

201201

202 - `"project_sharing_enabled"`

203

202204 - `"public_projects_enabled"`

203205

204206 - `"skill_sharing_enabled"`

from line 460

458460

459461 default: boolean

460462

461 - `name: "access_transparency_enabled" or "ai_powered_artifacts_enabled" or "api_workbench_feedback_collection_enabled" or 58 more`

463 - `name: "access_transparency_enabled" or "ai_powered_artifacts_enabled" or "api_workbench_feedback_collection_enabled" or 59 more`

462464

463465 - `"access_transparency_enabled"`

464466

from line 563

561563 - `"memory_enabled"`

562564

563565 - `"org_wide_skill_sharing_enabled"`

566

567 - `"project_sharing_enabled"`

564568

565569 - `"public_projects_enabled"`

566570

api/errors Changed · +3 / -3 lines

from line 36

3636 In rare cases, if your organization has a sharp increase in usage, you might see 429 errors because of acceleration limits on the API. To avoid hitting acceleration limits, ramp up your traffic gradually and maintain consistent usage patterns.

3737 </Warning>

3838

39The official SDKs automatically retry transient failures (such as connection errors, rate limits, and 5xx server errors) with exponential backoff, twice by default, honoring the `retry-after` header when present. Each SDK client accepts a maximum-retries option to configure or disable this behavior.

39The official SDKs automatically retry transient failures (such as connection errors, rate limits, and 5xx server errors) with exponential backoff, twice by default, honoring the `retry-after` header when present. The SDK client accepts `max_retries` (typescript, java, php: `maxRetries`; csharp: `MaxRetries`; go: `option.WithMaxRetries`) to configure or disable this behavior.

4040

4141When receiving a [streaming](https://platform.claude.com/docs/en/build-with-claude/streaming) response over server-sent events (SSE), an error can occur after the API returns a 200 response. In that case, error handling doesn't follow these standard mechanisms. See [Error events](https://platform.claude.com/docs/en/build-with-claude/streaming#error-events) for the shape of mid-stream errors.

4242

from line 72

7272

7373## SDK error types

7474

75The official SDKs raise typed exceptions for these errors instead of returning raw JSON, and the class names and namespaces differ by language. For example, a 404 surfaces as `anthropic.NotFoundError` in Python, `Anthropic::Errors::NotFoundError` in Ruby, `com.anthropic.errors.NotFoundException` in Java, and as a single `*anthropic.Error` value (branch on `StatusCode`) in Go. Catch the SDK's typed classes rather than string-matching error messages, handling the most specific classes first. Each SDK page documents its full exception hierarchy:

75The official SDKs raise typed exceptions for these errors instead of returning raw JSON, and the class names and namespaces differ by language. For example, a 404 surfaces as `anthropic.NotFoundError` (python; typescript: `Anthropic.NotFoundError`; ruby: `Anthropic::Errors::NotFoundError`; java: `com.anthropic.errors.NotFoundException`; csharp: `AnthropicNotFoundException`; php: `Anthropic\Core\Exceptions\NotFoundException`; go: `*anthropic.Error`). The Go SDK has one error type for every status, `*anthropic.Error`: branch on `StatusCode`. Catch the SDK's typed classes rather than string-matching error messages, handling the most specific classes first. Each SDK page documents its full exception hierarchy:

7676

7777* [Python](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/python#handling-errors) · [TypeScript](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/typescript#handling-errors) · [C#](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/csharp#error-handling) · [Go](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/go#error-handling) · [Java](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/java#error-handling) · [PHP](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/php#error-handling) · [Ruby](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/ruby#handling-errors)

7878

from line 82

8282

8383On [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), responses include two request IDs: the AWS request ID (`x-amzn-requestid`, primary, indexed in CloudTrail) and the Anthropic request ID (`request-id`, secondary). Use the AWS request ID for CloudTrail lookups and the Anthropic request ID for Anthropic support tickets.

8484

85The Python and TypeScript SDKs expose the request ID as a `_request_id` property on top-level response objects. The C#, Go, Java, and PHP SDKs expose it through their raw-response accessors, and the Ruby SDK through [middleware](https://platform.claude.com/docs/en/cli-sdks-libraries/middleware). The same mechanisms, along with `with_raw_response` in Python and `.withResponse()` in TypeScript, read any other [response header](https://platform.claude.com/docs/en/api/overview#response-headers) too, such as `anthropic-organization-id` and [`anthropic-workspace-id`](https://platform.claude.com/docs/en/manage-claude/workspaces#identify-the-workspace-behind-an-api-response). On Claude Platform on AWS, use the raw-response accessor to read the AWS request ID (`x-amzn-requestid`) as well:

85The Python and TypeScript SDKs expose the request ID as a `_request_id` property on top-level response objects. The C#, Go, Java, and PHP SDKs expose it through their raw-response accessors, and the Ruby SDK through [middleware](https://platform.claude.com/docs/en/cli-sdks-libraries/middleware). In every SDK except Ruby, use `with_raw_response` (typescript: `.withResponse()`; java: `.withRawResponse()`; csharp: `WithRawResponse`; go: `option.WithResponseInto`; php: `->raw`) to read any other [response header](https://platform.claude.com/docs/en/api/overview#response-headers), such as `anthropic-organization-id` and [`anthropic-workspace-id`](https://platform.claude.com/docs/en/manage-claude/workspaces#identify-the-workspace-behind-an-api-response). In Ruby, use the same middleware. On Claude Platform on AWS, use the raw-response accessor to read the AWS request ID (`x-amzn-requestid`) as well:

8686

8787<CodeGroup>

8888 ```bash cURL

api/messages Changed · +529 / -0 lines

### Cache Miss Messages Changed ### Cache Miss Model Changed ### Cache Miss Previous Message Not Found ### Cache Miss Reason ### Cache Miss System Changed ### Cache Miss Tools Changed ### Cache Miss Unavailable ### Diagnostics ### Diagnostics Param

This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.

from line 1199

11991199

12001200 - `string`

12011201

1202- `diagnostics: optional DiagnosticsParam or null`

1203

1204 Request-level diagnostics. Currently carries the previous response

1205 id for prompt-cache divergence reporting.

1206

1207 - `previous_message_id: optional string or null`

1208

1209 The `id` (`msg_...`) from this client's previous /v1/messages response. The server compares that request's prompt fingerprint against this one and returns `diagnostics.cache_miss_reason` when the prompt-cache prefix could not be reused. Pass `null` on the first turn to opt in without a prior message to compare.

1210

1211 maxLength: 256

1212

12021213- `inference_geo: optional string or null`

12031214

12041215 Specifies the geographic region for inference processing. If not specified, the workspace's `default_inference_geo` is used.

from line 3875

38643875

38653876 - `file_id: string`

38663877

3878 - `diagnostics: Diagnostics or null`

3879

3880 Request-level diagnostics: why the prompt cache could not fully reuse

3881 the prefix of the request named by `diagnostics.previous_message_id`.

3882

3883 - `cache_miss_reason: CacheMissReason or null`

3884

3885 Explains why the prompt cache could not fully reuse the prefix from the request identified by `diagnostics.previous_message_id`. `null` means diagnosis is still pending — the response was serialized before the background comparison completed.

3886

3887 - `CacheMissModelChanged object`

3888

3889 - `type: "model_changed"`

3890

3891 default: model_changed

3892

3893 - `cache_missed_input_tokens: number`

3894

3895 Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

3896

3897 - `CacheMissSystemChanged object`

3898

3899 - `type: "system_changed"`

3900

3901 default: system_changed

3902

3903 - `cache_missed_input_tokens: number`

3904

3905 Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

3906

3907 - `CacheMissToolsChanged object`

3908

3909 - `type: "tools_changed"`

3910

3911 default: tools_changed

3912

3913 - `cache_missed_input_tokens: number`

3914

3915 Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

3916

3917 - `CacheMissMessagesChanged object`

3918

3919 - `type: "messages_changed"`

3920

3921 default: messages_changed

3922

3923 - `cache_missed_input_tokens: number`

3924

3925 Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

3926

3927 - `CacheMissPreviousMessageNotFound object`

3928

3929 - `type: "previous_message_not_found"`

3930

3931 default: previous_message_not_found

3932

3933 - `CacheMissUnavailable object`

3934

3935 - `type: "unavailable"`

3936

3937 default: unavailable

3938

38673939 - `model: Model`

38683940

38693941 The model that will complete your prompt.

from line 4480

44084480 "type": "text"

44094481 }

44104482 ],

4483 "diagnostics": {

4484 "cache_miss_reason": {

4485 "cache_missed_input_tokens": 0,

4486 "type": "model_changed"

4487 }

4488 },

44114489 "model": "claude-opus-5",

44124490 "role": "assistant",

44134491 "stop_details": {

from line 8406

83288406

83298407 maxLength: 4096, minLength: 1, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$

83308408

8331 - `url: string`

8332

8333 The final post-redirect URL the download was served from.

8334

8335 maxLength: 4096, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$

8336

8337 - `error: optional string or null`

8338

8339 The failure or cancellation detail, when known.

8340

8341 pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$, maxLength: 4096

8342

8343### Browser State Change Download Completed

8344

8345- `BrowserStateChangeDownloadCompleted object`

8346

8347 A file download that finished during this call, reported with the

8348 same `download_id` as its `download_started` — or without a prior

8349 `download_started`, when the download finished during the call that

8350 started it (at most one state change per `download_id` per result).

8351

8352 - `type: "download_completed"`

8353

8354 - `download_id: string`

8355

8356 The caller-assigned identifier for this download, stable across the state changes reporting it.

8357

8358 maxLength: 4096, minLength: 1, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$

8359

8360 - `url: string`

8361

8362 The final post-redirect URL the download was served from.

8363

8364 maxLength: 4096, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$

8365

8366 - `path: optional string or null`

8367

8368 Where the executor saved the file, on the executor's filesystem. Only included when another tool in the same environment can read the file at that path.

8369

8370 pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$, maxLength: 4096

8371

8372 - `size_bytes: optional number or null`

8373

8374 The completed download's size.

8375

8376 minimum: 0

8377

8378### Browser State Change Download Failed

8379

8380- `BrowserStateChangeDownloadFailed object`

8381

8382 A file download that failed — or was cancelled — during this call.

8383

8384 - `type: "download_failed"`

8385

8386 - `download_id: string`

8387

8388 The caller-assigned identifier for this download, stable across the state changes reporting it.

8389

8390 maxLength: 4096, minLength: 1, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$

8391

8392 - `url: string`

8393

8394 The final post-redirect URL the download was served from.

8395

8396 maxLength: 4096, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$

8397

8398 - `error: optional string or null`

8399

8400 The failure or cancellation detail, when known.

8401

8402 pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$, maxLength: 4096

8403

8404### Browser State Change Download Started

8405

8406- `BrowserStateChangeDownloadStarted object`

8407

8408 A file download that started during this call.

8409

8410 - `type: "download_started"`

8411

8412 - `download_id: string`

8413

8414 The caller-assigned identifier for this download, stable across the state changes reporting it.

8415

8416 maxLength: 4096, minLength: 1, pattern: ^[^\x00-\x1f\x7f-\x9f\u2028\u2029]*$

8417

8418 - `url: string`

8419

8420 The final post

8409

api/messages/batches Changed · +255 / -0 lines

This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.

The two sides of this change are more than 400 edits apart, too far apart to line up, so this is the differ's own diff of it and the words inside a line are not marked.

from line 1218

12181218 maxLength: 64, minLength: 1

12191219

12201220 - `string`

1221

1222 - `diagnostics: optional DiagnosticsParam or null`

1223

1224 Request-level diagnostics. Currently carries the previous response

1225 id for prompt-cache divergence reporting.

1226

1227 - `previous_message_id: optional string or null`

1228

1229 The `id` (`msg_...`) from this client's previous /v1/messages response. The server compares that request's prompt fingerprint against this one and returns `diagnostics.cache_miss_reason` when the prompt-cache prefix could not be reused. Pass `null` on the first turn to opt in without a prior message to compare.

1230

1231 maxLength: 256

12211232

12221233 - `inference_geo: optional string or null`

12231234

from line 4681

46704681

46714682 - `file_id: string`

46724683

4684 - `diagnostics: Diagnostics or null`

4685

4686 Request-level diagnostics: why the prompt cache could not fully reuse

4687 the prefix of the request named by `diagnostics.previous_message_id`.

4688

4689 - `cache_miss_reason: CacheMissReason or null`

4690

4691 Explains why the prompt cache could not fully reuse the prefix from the request identified by `diagnostics.previous_message_id`. `null` means diagnosis is still pending — the response was serialized before the background comparison completed.

4692

4693 - `CacheMissModelChanged object`

4694

4695 - `type: "model_changed"`

4696

4697 default: model_changed

4698

4699 - `cache_missed_input_tokens: number`

4700

4701 Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

4702

4703 - `CacheMissSystemChanged object`

4704

4705 - `type: "system_changed"`

4706

4707 default: system_changed

4708

4709 - `cache_missed_input_tokens: number`

4710

4711 Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

4712

4713 - `CacheMissToolsChanged object`

4714

4715 - `type: "tools_changed"`

4716

4717 default: tools_changed

4718

4719 - `cache_missed_input_tokens: number`

4720

4721 Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

4722

4723 - `CacheMissMessagesChanged object`

4724

4725 - `type: "messages_changed"`

4726

4727 default: messages_changed

4728

4729 - `cache_missed_input_tokens: number`

4730

4731 Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

4732

4733 - `CacheMissPreviousMessageNotFound object`

4734

4735 - `type: "previous_message_not_found"`

4736

4737 default: previous_message_not_found

4738

4739 - `CacheMissUnavailable object`

4740

4741 - `type: "unavailable"`

4742

4743 default: unavailable

4744

46734745 - `model: Model`

46744746

46754747 The model that will complete your prompt.

from line 6187

61156187

61166188 - `file_id: string`

61176189

6190 - `diagnostics: Diagnostics or null`

6191

6192 Request-level diagnostics: why the prompt cache could not fully reuse

6193 the prefix of the request named by `diagnostics.previous_message_id`.

6194

6195 - `cache_miss_reason: CacheMissReason or null`

6196

6197 Explains why the prompt cache could not fully reuse the prefix from the request identified by `diagnostics.previous_message_id`. `null` means diagnosis is still pending — the response was serialized before the background comparison completed.

6198

6199 - `CacheMissModelChanged object`

6200

6201 - `type: "model_changed"`

6202

6203 default: model_changed

6204

6205 - `cache_missed_input_tokens: number`

6206

6207 Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

6208

6209 - `CacheMissSystemChanged object`

6210

6211 - `type: "system_changed"`

6212

6213 default: system_changed

6214

6215 - `cache_missed_input_tokens: number`

6216

6217 Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

6218

6219 - `CacheMissToolsChanged object`

6220

6221 - `type: "tools_changed"`

6222

6223 default: tools_changed

6224

6225 - `cache_missed_input_tokens: number`

6226

6227 Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

6228

6229 - `CacheMissMessagesChanged object`

6230

6231 - `type: "messages_changed"`

6232

6233 default: messages_changed

6234

6235 - `cache_missed_input_tokens: number`

6236

6237 Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

6238

6239 - `CacheMissPreviousMessageNotFound object`

6240

6241 - `type: "previous_message_not_found"`

6242

6243 default: previous_message_not_found

6244

6245 - `CacheMissUnavailable object`

6246

6247 - `type: "unavailable"`

6248

6249 default: unavailable

6250

61186251 - `model: Model`

61196252

61206253 The model that will complete your prompt.

from line 7465

73327465

73337466 - `file_id: string`

73347467

7468 - `diagnostics: Diagnostics or null`

7469

7470 Request-level diagnostics: why the prompt cache could not fully reuse

7471 the prefix of the request named by `diagnostics.previous_message_id`.

7472

7473 - `cache_miss_reason: CacheMissReason or null`

7474

7475 Explains why the prompt cache could not fully reuse the prefix from the request identified by `diagnostics.previous_message_id`. `null` means diagnosis is still pending — the response was serialized before the background comparison completed.

7476

7477 - `CacheMissModelChanged object`

7478

7479 - `type: "model_changed"`

7480

7481 default: model_changed

7482

7483 - `cache_missed_input_tokens: number`

7484

7485 Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

7486

7487 - `CacheMissSystemChanged object`

7488

7489 - `type: "system_changed"`

7490

7491 default: system_changed

7492

7493 - `cache_missed_input_tokens: number`

7494

7495 Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

7496

7497 - `CacheMissToolsChanged object`

7498

7499 - `type: "tools_changed"`

7500

7501 default: tools_changed

7502

7503 - `cache_missed_input_tokens: number`

7504

7505 Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

7506

7507 - `CacheMissMessagesChanged object`

7508

7509 - `type: "messages_changed"`

7510

7511 default: messages_changed

7512

7513 - `cache_missed_input_tokens: number`

7514

7515 Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

7516

7517 - `CacheMissPreviousMessageNotFound object`

7518

7519 - `type: "previous_message_not_found"`

7520

7521 default: previous_message_not_found

7522

7523 - `CacheMissUnavailable object`

7524

7525 - `type: "unavailable"`

7526

7527 default: unavailable

7528

73357529 - `model: Model`

73367530

73377531 The model that will complete your prompt.

from line 8695

85018695

85028696 - `file_id: string`

85038697

8698 - `diagnostics: Diagnostics or null`

8699

8700 Request-level diagnostics: why the prompt cache could not fully reuse

8701 the prefix of the request named by `diagnostics.previous_message_id`.

8702

8703 - `cache_miss_reason: CacheMissReason or null`

8704

8705 Explains why the prompt cache could not fully reuse the prefix from the request identified by `diagnostics.previous_message_id`. `null` means diagnosis is still pending — the response was serialized before the background comparison completed.

8706

8707 - `CacheMissModelChanged object`

8708

8709 - `type: "model_changed"`

8710

8711 default: model_changed

8712

8713 - `cache_missed_input_tokens: number`

8714

8715 Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

8716

8717 - `CacheMissSystemChanged object`

8718

8719 - `type: "system_changed"`

8720

8721 default: system_changed

8722

8723 - `cache_missed_input_tokens: number`

8724

8725 Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

8726

8727 - `CacheMissToolsChanged object`

8728

8729 - `type: "tools_changed"`

8730

8731 default: tools_changed

8732

8733 - `cache_missed_input_tokens: number`

8734

8735 Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

8736

8737 - `CacheMissMessagesChanged object`

8738

8739 - `type: "messages_changed"`

8740

8741 default: messages_changed

8742

8743 - `cache_missed_input_tokens: number`

8744

8745 Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

8746

8747 - `CacheMissPreviousMessageNotFound object`

8748

8749 - `type: "previous_message_not_found"`

8750

8751 default: previous_message_not_found

8752

8753 - `CacheMissUnavailable object`

8754

8755 - `type: "unavailable"`

8756

8757 default: unavailable

8758

85048759 - `model: Model`

85058760

85068761 The model that will complete your prompt.

85078762

api/messages/batches/create Changed · +11 / -0 lines

from line 1217

12171217

12181218 - `string`

12191219

1220 - `diagnostics: optional DiagnosticsParam or null`

1221

1222 Request-level diagnostics. Currently carries the previous response

1223 id for prompt-cache divergence reporting.

1224

1225 - `previous_message_id: optional string or null`

1226

1227 The `id` (`msg_...`) from this client's previous /v1/messages response. The server compares that request's prompt fingerprint against this one and returns `diagnostics.cache_miss_reason` when the prompt-cache prefix could not be reused. Pass `null` on the first turn to opt in without a prior message to compare.

1228

1229 maxLength: 256

1230

12201231 - `inference_geo: optional string or null`

12211232

12221233 Specifies the geographic region for inference processing. If not specified, the workspace's `default_inference_geo` is used.

api/messages/batches/results Changed · +61 / -0 lines

from line 822

822822

823823 - `file_id: string`

824824

825 - `diagnostics: Diagnostics or null`

826

827 Request-level diagnostics: why the prompt cache could not fully reuse

828 the prefix of the request named by `diagnostics.previous_message_id`.

829

830 - `cache_miss_reason: CacheMissReason or null`

831

832 Explains why the prompt cache could not fully reuse the prefix from the request identified by `diagnostics.previous_message_id`. `null` means diagnosis is still pending — the response was serialized before the background comparison completed.

833

834 - `CacheMissModelChanged object`

835

836 - `type: "model_changed"`

837

838 default: model_changed

839

840 - `cache_missed_input_tokens: number`

841

842 Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

843

844 - `CacheMissSystemChanged object`

845

846 - `type: "system_changed"`

847

848 default: system_changed

849

850 - `cache_missed_input_tokens: number`

851

852 Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

853

854 - `CacheMissToolsChanged object`

855

856 - `type: "tools_changed"`

857

858 default: tools_changed

859

860 - `cache_missed_input_tokens: number`

861

862 Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

863

864 - `CacheMissMessagesChanged object`

865

866 - `type: "messages_changed"`

867

868 default: messages_changed

869

870 - `cache_missed_input_tokens: number`

871

872 Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

873

874 - `CacheMissPreviousMessageNotFound object`

875

876 - `type: "previous_message_not_found"`

877

878 default: previous_message_not_found

879

880 - `CacheMissUnavailable object`

881

882 - `type: "unavailable"`

883

884 default: unavailable

885

825886 - `model: Model`

826887

827888 The model that will complete your prompt.

api/messages/create Changed · +78 / -0 lines

from line 1197

11971197

11981198 - `string`

11991199

1200- `diagnostics: optional DiagnosticsParam or null`

1201

1202 Request-level diagnostics. Currently carries the previous response

1203 id for prompt-cache divergence reporting.

1204

1205 - `previous_message_id: optional string or null`

1206

1207 The `id` (`msg_...`) from this client's previous /v1/messages response. The server compares that request's prompt fingerprint against this one and returns `diagnostics.cache_miss_reason` when the prompt-cache prefix could not be reused. Pass `null` on the first turn to opt in without a prior message to compare.

1208

1209 maxLength: 256

1210

12001211- `inference_geo: optional string or null`

12011212

12021213 Specifies the geographic region for inference processing. If not specified, the workspace's `default_inference_geo` is used.

from line 3873

38623873

38633874 - `file_id: string`

38643875

3876 - `diagnostics: Diagnostics or null`

3877

3878 Request-level diagnostics: why the prompt cache could not fully reuse

3879 the prefix of the request named by `diagnostics.previous_message_id`.

3880

3881 - `cache_miss_reason: CacheMissReason or null`

3882

3883 Explains why the prompt cache could not fully reuse the prefix from the request identified by `diagnostics.previous_message_id`. `null` means diagnosis is still pending — the response was serialized before the background comparison completed.

3884

3885 - `CacheMissModelChanged object`

3886

3887 - `type: "model_changed"`

3888

3889 default: model_changed

3890

3891 - `cache_missed_input_tokens: number`

3892

3893 Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

3894

3895 - `CacheMissSystemChanged object`

3896

3897 - `type: "system_changed"`

3898

3899 default: system_changed

3900

3901 - `cache_missed_input_tokens: number`

3902

3903 Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

3904

3905 - `CacheMissToolsChanged object`

3906

3907 - `type: "tools_changed"`

3908

3909 default: tools_changed

3910

3911 - `cache_missed_input_tokens: number`

3912

3913 Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

3914

3915 - `CacheMissMessagesChanged object`

3916

3917 - `type: "messages_changed"`

3918

3919 default: messages_changed

3920

3921 - `cache_missed_input_tokens: number`

3922

3923 Approximate number of input tokens that would have been read from cache had the prefix matched the previous request.

3924

3925 - `CacheMissPreviousMessageNotFound object`

3926

3927 - `type: "previous_message_not_found"`

3928

3929 default: previous_message_not_found

3930

3931 - `CacheMissUnavailable object`

3932

3933 - `type: "unavailable"`

3934

3935 default: unavailable

3936

38653937 - `model: Model`

38663938

38673939 The model that will complete your prompt.

from line 4478

44064478 "type": "text"

44074479 }

44084480 ],

4481 "diagnostics": {

4482 "cache_miss_reason": {

4483 "cache_missed_input_tokens": 0,

4484 "type": "model_changed"

4485 }

4486 },

44094487 "model": "claude-opus-5",

44104488 "role": "assistant",

44114489 "stop_details": {

api/models Changed · +16 / -12 lines

from line 33

3333

3434### Headers

3535

36- `"anthropic-workspace-id": optional string`

37

38 Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`).

39

40 Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace.

41

3642- `"anthropic-beta": optional array of AnthropicBeta`

3743

44 **Deprecated**: Deprecated. This parameter will be removed from this method in a future release. To use beta features, call the beta models methods (`client.beta.models`) instead.

45

3846 Optional header to specify the beta version(s) you want to use.

3947

4048 - `string`

from line 145

137145

138146 - `"mcp-client-2026-09-15"`

139147

140- `"anthropic-workspace-id": optional string`

141

142 Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`).

143

144 Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace.

145

146148### Returns

147149

148150- `data: array of ModelInfo`

from line 396

394396

395397### Headers

396398

399- `"anthropic-workspace-id": optional string`

400

401 Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`).

402

403 Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace.

404

397405- `"anthropic-beta": optional array of AnthropicBeta`

398406

407 **Deprecated**: Deprecated. This parameter will be removed from this method in a future release. To use beta features, call the beta models methods (`client.beta.models`) instead.

408

399409 Optional header to specify the beta version(s) you want to use.

400410

401411 - `string`

from line 507

497507 - `"inline-tools-2026-09-15"`

498508

499509 - `"mcp-client-2026-09-15"`

500

501- `"anthropic-workspace-id": optional string`

502

503 Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`).

504

505 Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace.

506510

507511### Returns

508512

api/models/list Changed · +8 / -6 lines

from line 31

3131

3232## Headers

3333

34- `"anthropic-workspace-id": optional string`

35

36 Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`).

37

38 Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace.

39

3440- `"anthropic-beta": optional array of AnthropicBeta`

3541

42 **Deprecated**: Deprecated. This parameter will be removed from this method in a future release. To use beta features, call the beta models methods (`client.beta.models`) instead.

43

3644 Optional header to specify the beta version(s) you want to use.

3745

3846 - `string`

from line 142

134142 - `"inline-tools-2026-09-15"`

135143

136144 - `"mcp-client-2026-09-15"`

137

138- `"anthropic-workspace-id": optional string`

139

140 Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`).

141

142 Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace.

143145

144146## Returns

145147

api/models/retrieve Changed · +8 / -6 lines

from line 19

1919

2020## Headers

2121

22- `"anthropic-workspace-id": optional string`

23

24 Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`).

25

26 Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace.

27

2228- `"anthropic-beta": optional array of AnthropicBeta`

2329

30 **Deprecated**: Deprecated. This parameter will be removed from this method in a future release. To use beta features, call the beta models methods (`client.beta.models`) instead.

31

2432 Optional header to specify the beta version(s) you want to use.

2533

2634 - `string`

from line 130

122130 - `"inline-tools-2026-09-15"`

123131

124132 - `"mcp-client-2026-09-15"`

125

126- `"anthropic-workspace-id": optional string`

127

128 Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`).

129

130 Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace.

131133

132134## Returns

133135

build-with-claude/cache-diagnostics Changed · +16 / -54 lines

from line 3

33url: https://platform.claude.com/docs/en/build-with-claude/cache-diagnostics

44description: Diagnose unexpected prompt cache misses by comparing consecutive requests and identifying exactly where the prompt prefix diverged.

55featureMetadata:

6 status: beta

7 betaHeader: cache-diagnosis-2026-04-07

6 status: ga

87 zdr:

98 eligibility: eligible

109 note: Excludes [Covered Models](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements).

1110 supportedPlatforms:

12 Claude API: beta

11 Claude API: ga

1312 Claude Platform on AWS: not available

1413 Amazon Bedrock: not available

1514 Google Cloud: not available

from line 21

2221

2322## How cache diagnostics works

2423

25When the beta header is present, the API stores a lightweight fingerprint of each request, keyed by the response `id`. On your next request, include that `id` as `diagnostics.previous_message_id`. The API rebuilds the fingerprint for the new request, compares it against the stored one, and attaches a `diagnostics` object to the response describing the first point of divergence.

24For each request that includes the `diagnostics` object, the API stores a lightweight fingerprint keyed by the response `id`. It stores nothing for requests that omit the object. On your next request, include the previous response's `id` as `diagnostics.previous_message_id`. The API rebuilds the fingerprint for the new request, compares it against the stored one, and attaches a `diagnostics` object to the response describing the first point of divergence.

2625

2726The comparison is about request structure, independent of whether the cache actually hit. See [Reading diagnostics alongside usage](https://platform.claude.com/docs/en/build-with-claude/cache-diagnostics#reading-diagnostics-alongside-usage) for how to combine the `diagnostics` result with `usage.cache_read_input_tokens`.

2827

from line 29

3029

3130## Basic usage

3231

33Send the beta header on every turn. On the first turn, pass `"previous_message_id": null` to opt in without a prior message to compare against. On subsequent turns, pass the `id` from the previous response.

32Include the `diagnostics` object on every turn. The object is the opt-in: the API stores a fingerprint only for requests that include it. On the first turn, pass `"previous_message_id": null` to opt in without a prior message to compare against. On subsequent turns, pass the `id` from the previous response. The `cache-diagnosis-2026-04-07` beta header is no longer required, and requests that still send it work as before.

3433

3534<CodeGroup>

3635 ```bash cURL

from line 37

3837 response=$(curl -sS --fail-with-body https://api.anthropic.com/v1/messages \

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

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

41 -H "anthropic-beta: cache-diagnosis-2026-04-07" \

4240 -H "content-type: application/json" \

4341 -d '{

4442 "model": "claude-opus-5-5",

from line 53

5553 curl -sS --fail-with-body https://api.anthropic.com/v1/messages \

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

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

58 -H "anthropic-beta: cache-diagnosis-2026-04-07" \

5956 -H "content-type: application/json" \

6057 -d @- <<EOF | jq '{id, diagnostics}' # diagnostics: null means no divergence was found

6158 {

from line 73

7673 ```bash CLI

7774 # Turn 1

7875 turn1=$(ant beta:messages create \

79 --beta cache-diagnosis-2026-04-07 \

8076 --transform '{id,usage,diagnostics}' <<'YAML'

8177 model: claude-opus-5-5

8278 max_tokens: 1024

from line 91

9591 # Turn 2: pass the id from turn 1 as previous_message_id

9692 message_id=$(jq -r '.id' <<<"$turn1")

9793 ant beta:messages create \

98 --beta cache-diagnosis-2026-04-07 \

9994 --transform '{id,usage,diagnostics}' <<YAML

10095 model: claude-opus-5-5

10196 max_tokens: 1024

from line 122

127122 system=SYSTEM,

128123 messages=[{"role": "user", "content": "Summarize section 1."}],

129124 diagnostics={"previous_message_id": None},

130 betas=["cache-diagnosis-2026-04-07"],

131125 )

132126

133127 # Turn 2: reference the previous response id

from line 136

142136 {"role": "user", "content": "Now summarize section 2."},

143137 ],

144138 diagnostics={"previous_message_id": r1.id},

145 betas=["cache-diagnosis-2026-04-07"],

146139 )

147140

148141 diagnostics = r2.diagnostics

from line 159

166159 cache_control: { type: "ephemeral" },

167160 system: SYSTEM,

168161 messages: [{ role: "user", content: "Summarize section 1." }],

169 diagnostics: { previous_message_id: null },

170 betas: ["cache-diagnosis-2026-04-07"]

162 diagnostics: { previous_message_id: null }

171163 });

172164

173165 // Turn 2: reference the previous response id

from line 173

181173 { role: "assistant", content: r1.content },

182174 { role: "user", content: "Now summarize section 2." }

183175 ],

184 diagnostics: { previous_message_id: r1.id },

185 betas: ["cache-diagnosis-2026-04-07"]

176 diagnostics: { previous_message_id: r1.id }

186177 });

187178

188179 if (r2.diagnostics === null) {

from line 202

211202 new() { Role = Role.User, Content = "Summarize section 1." },

212203 ],

213204 Diagnostics = new() { PreviousMessageID = null },

214 Betas = [AnthropicBeta.CacheDiagnosis2026_04_07],

215205 }

216206 );

217207

from line 223

233223 new() { Role = Role.User, Content = "Now summarize section 2." },

234224 ],

235225 Diagnostics = new() { PreviousMessageID = r1.ID },

236 Betas = [AnthropicBeta.CacheDiagnosis2026_04_07],

237226 }

238227 );

239228

from line 253

264253 Diagnostics: anthropic.BetaDiagnosticsParam{

265254 PreviousMessageID: param.Null[string](),

266255 },

267 Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaCacheDiagnosis2026_04_07},

268256 })

269257 if err != nil {

270258 panic(err)

from line 271

283271 Diagnostics: anthropic.BetaDiagnosticsParam{

284272 PreviousMessageID: anthropic.String(r1.ID),

285273 },

286 Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaCacheDiagnosis2026_04_07},

287274 })

288275 if err != nil {

289276 panic(err)

from line 300

313300 .addUserMessage("Summarize section 1.")

314301 // Pass null on the first turn to opt in without a prior message to compare.

315302 .diagnostics(BetaDiagnosticsParam.builder().previousMessageId((String) null).build())

316 .addBeta(AnthropicBeta.CACHE_DIAGNOSIS_2026_04_07)

317303 .build()

318304 );

319305

from line 313

327313 .addMessage(r1)

328314 .addUserMessage("Now summarize section 2.")

329315 .diagnostics(BetaDiagnosticsParam.builder().previousMessageId(r1.id()).build())

330 .addBeta(AnthropicBeta.CACHE_DIAGNOSIS_2026_04_07)

331316 .build()

332317 );

333318

from line 343

358343 ['role' => 'user', 'content' => 'Summarize section 1.'],

359344 ],

360345 diagnostics: (new BetaDiagnosticsParam)->withPreviousMessageID(null),

361 betas: [AnthropicBeta::CACHE_DIAGNOSIS_2026_04_07],

362346 );

363347

364348 $r2 = $client->beta->messages->create(

from line 356

372356 ['role' => 'user', 'content' => 'Now summarize section 2.'],

373357 ],

374358 diagnostics: (new BetaDiagnosticsParam)->withPreviousMessageID($r1->id),

375 betas: [AnthropicBeta::CACHE_DIAGNOSIS_2026_04_07],

376359 );

377360

378361 echo match (true) {

from line 378

395378 messages: [

396379 {role: "user", content: "Summarize section 1."}

397380 ],

398 diagnostics: {previous_message_id: nil},

399 betas: ["cache-diagnosis-2026-04-07"]

381 diagnostics: {previous_message_id: nil}

400382 )

401383

402384 r2 = client.beta.messages.create(

from line 391

409391 {role: "assistant", content: r1.content},

410392 {role: "user", content: "Now summarize section 2."}

411393 ],

412 diagnostics: {previous_message_id: r1.id},

413 betas: ["cache-diagnosis-2026-04-07"]

394 diagnostics: {previous_message_id: r1.id}

414395 )

415396

416397 case r2.diagnostics

from line 416

435416 curl -sS --fail-with-body https://api.anthropic.com/v1/messages \

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

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

438 -H "anthropic-beta: cache-diagnosis-2026-04-07" \

439419 -H "content-type: application/json" \

441421 {

from line 438

458438 # Turn 2: stream. With --stream the CLI emits each SSE event as one JSON object.

459439 # diagnostics arrives on the message_start event; pick it out with jq.

460440 ant beta:messages create \

461 --beta cache-diagnosis-2026-04-07 \

462441 --stream --format jsonl <<YAML |

463442 model: claude-opus-5-5

464443 max_tokens: 1024

from line 470

491470 {"role": "user", "content": "Now summarize section 2."},

492471 ],

493472 diagnostics={"previous_message_id": r1.id},

494 betas=["cache-diagnosis-2026-04-07"],

495473 ) as stream:

496474 for text in stream.text_stream:

497475 print(text, end="", flush=True)

from line 496

518496 { role: "assistant", content: r1.content },

519497 { role: "user", content: "Now summarize section 2." }

520498 ],

521 diagnostics: { previous_message_id: r1.id },

522 betas: ["cache-diagnosis-2026-04-07"]

499 diagnostics: { previous_message_id: r1.id }

523500 });

524501

525502 for await (const event of stream) {

from line 540

563540 new() { Role = Role.User, Content = "Now summarize section 2." },

564541 ],

565542 Diagnostics = new() { PreviousMessageID = r1.ID },

566 Betas = [AnthropicBeta.CacheDiagnosis2026_04_07],

567543 }

568544 );

569545

from line 580

604580 Diagnostics: anthropic.BetaDiagnosticsParam{

605581 PreviousMessageID: anthropic.String(r1.ID),

606582 },

607 Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaCacheDiagnosis2026_04_07},

608583 })

609584 defer stream.Close()

610585

from line 615

640615 .addMessage(r1)

641616 .addUserMessage("Now summarize section 2.")

642617 .diagnostics(BetaDiagnosticsParam.builder().previousMessageId(r1.id()).build())

643 .addBeta(AnthropicBeta.CACHE_DIAGNOSIS_2026_04_07)

644618 .build();

645619

646620 var accumulator = BetaMessageAccumulator.create();

from line 655

681655 ['role' => 'user', 'content' => 'Now summarize section 2.'],

682656 ],

683657 diagnostics: (new BetaDiagnosticsParam)->withPreviousMessageID($r1->id),

684 betas: [AnthropicBeta::CACHE_DIAGNOSIS_2026_04_07],

685658 );

686659

687660 $diagnostics = null;

from line 692

719692 {role: "assistant", content: r1.content},

720693 {role: "user", content: "Now summarize section 2."}

721694 ],

722 diagnostics: {previous_message_id: r1.id},

723 betas: ["cache-diagnosis-2026-04-07"]

695 diagnostics: {previous_message_id: r1.id}

724696 )

725697

726698 stream.each do |event|

from line 754

782754 system=SYSTEM,

783755 messages=messages,

784756 diagnostics={"previous_message_id": prev_id},

785 betas=["cache-diagnosis-2026-04-07"],

786757 )

787758

788759 if r.diagnostics is not None and r.diagnostics.cache_miss_reason is not None:

from line 784

813784 cache_control: { type: "ephemeral" },

814785 system: SYSTEM,

815786 messages,

816 diagnostics: { previous_message_id: prevId },

817 betas: ["cache-diagnosis-2026-04-07"]

787 diagnostics: { previous_message_id: prevId }

818788 });

819789

820790 if (r.diagnostics?.cache_miss_reason) {

from line 820

850820 System = system,

851821 Messages = messages,

852822 Diagnostics = new() { PreviousMessageID = prevId },

853 Betas = [AnthropicBeta.CacheDiagnosis2026_04_07],

854823 }

855824 );

856825

from line 866

897866 Diagnostics: anthropic.BetaDiagnosticsParam{

898867 PreviousMessageID: prevID,

899868 },

900 Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaCacheDiagnosis2026_04_07},

901869 })

902870 if err != nil {

903871 panic(err)

from line 907

939907 .system(system)

940908 .messages(messages)

941909 .diagnostics(BetaDiagnosticsParam.builder().previousMessageId(prevId).build())

942 .addBeta(AnthropicBeta.CACHE_DIAGNOSIS_2026_04_07)

943910 .build()

944911 );

945912

from line 944

977944 system: $system,

978945 messages: $messages,

979946 diagnostics: (new BetaDiagnosticsParam)->withPreviousMessageID($prevId),

980 betas: [AnthropicBeta::CACHE_DIAGNOSIS_2026_04_07],

981947 );

982948

983949 if ($r->diagnostics?->cacheMissReason !== null) {

from line 974

1008974 cache_control: {type: "ephemeral"},

1009975 system_: SYSTEM,

1010976 messages: messages,

1011 diagnostics: {previous_message_id: prev_id},

1012 betas: ["cache-diagnosis-2026-04-07"]

977 diagnostics: {previous_message_id: prev_id}

1013978 )

1014979

1015980 if (reason = r.diagnostics&.cache_miss_reason)

from line 990

1025990

1026991## Response format

1027992

1028The `diagnostics` field on the response `Message` has four possible states:

993The `diagnostics` field on the response `Message` has three possible values:

1029994

1030995| Value | Meaning |

1031996| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1032| field absent | The request did not include `diagnostics`, or the beta header was missing. |

1033| `null` | Either `previous_message_id` was `null` (first turn, nothing to compare), or a comparison ran and found no divergence. |

997| `null` | The request did not include the `diagnostics` object, `previous_message_id` was `null` (first turn, nothing to compare), or a comparison ran and found no divergence. |

1034998| `{"cache_miss_reason": null}` | The comparison was still running when the response was serialized. This can happen when the response starts very quickly. Treat it as inconclusive and check the next turn. |

1035999| `{"cache_miss_reason": {...}}` | A `cache_miss_reason` is attached. For `*_changed` types this identifies the first divergence point; `previous_message_not_found` and `unavailable` are cases where no comparison was produced. |

10361000

from line 1031

10671031| `system_changed` | The `system` parameter differs. Typically a timestamp, request ID, or other per-request value was interpolated into the system prompt. | Make the system prompt a byte-stable constant and move dynamic data into the first `user` message after your cache breakpoint. |

10681032| `tools_changed` | The `tools` array differs: tools were added, removed, or reordered between turns, or tool `input_schema` JSON was serialized non-deterministically. | Send the same tool list on every turn in a fixed order with deterministically serialized schemas (for example, sort keys). |

10691033| `messages_changed` | The model, system, and tools all match, but an earlier entry in `messages` was altered, reordered, or removed rather than appended to. Typically conversation history was truncated or edited, or assistant turns and `tool_result` blocks were re-serialized differently on resend. | Treat the history as append-only; echo assistant `content` and tool results back verbatim. |

1070| `previous_message_not_found` | No stored fingerprint exists for the supplied `previous_message_id`. This is not evidence that your request changed. Typically the previous request did not carry the beta header, it came from a different workspace, or too much time has passed since it was sent. | Send the beta header on every turn and keep consecutive turns close together in time. |

1034| `previous_message_not_found` | No stored fingerprint exists for the supplied `previous_message_id`. This is not evidence that your request changed. Typically the previous request did not include the `diagnostics` object, it came from a different workspace, or too much time has passed since it was sent. | Include the `diagnostics` object on every turn and keep consecutive turns close together in time. |

10711035| `unavailable` | Diagnostic information was not available for this request. This includes the case where `model`, `system`, and `tools` match but another prompt-affecting request parameter (`tool_choice`, `thinking`, `context_management`, `output_config`, `output_format`, or the set of active `anthropic-beta` headers) differs, and very long conversations where the divergence is beyond the comparison horizon. Your request was processed normally. | Keep the prompt-affecting request parameters constant for the lifetime of a cached conversation. If persistent, apply the manual checks under [Troubleshooting common issues](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#troubleshooting-common-issues) on the prompt caching page. |

10721036

10731037<Note>

from line 1053

10891053

10901054## Limitations

10911055

1092* **Beta:** Field names and semantics may change while this feature is in beta.

10931056* **Claude API only:** Not available on Amazon Bedrock or Google Cloud.

10941057* **Limited retention:** Fingerprints for `previous_message_id` lookup expire after a short period. Run diagnostic comparisons between closely spaced requests.

10951058* **Same workspace:** The previous request must have run in the same organization and workspace. To check, compare the `anthropic-workspace-id` [response header](https://platform.claude.com/docs/en/api/overview#response-headers) on the two responses.

from line 1063

11001063

11011064Cache diagnostics is ZDR eligible (qualified). Anthropic does not store the raw text of your prompts or Claude's outputs for this feature.

11021065

1103The fingerprint stored for each request consists only of cryptographic hashes and token-count estimates, keyed by the response `id` and scoped to your organization and workspace. Fingerprints expire after a short period and are not used for any other purpose.

1066The API stores a fingerprint only for requests that include the `diagnostics` object. The fingerprint consists only of cryptographic hashes and token-count estimates, keyed by the response `id` and scoped to your organization and workspace. Fingerprints expire after a short period and are not used for any other purpose.

11041067

11051068For ZDR eligibility across all features, see [API and data retention](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention).

11061069

from line 1071

11081071

11091072* [Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)

11101073* [Token counting](https://platform.claude.com/docs/en/build-with-claude/token-counting)

1111* [Beta headers](https://platform.claude.com/docs/en/api/beta-headers)

11121074

build-with-claude/claude-platform-on-aws Changed · +15 / -15 lines

from line 22

2222

2323Both offerings let you use Claude through AWS, but they differ in architecture, API surface, and feature availability.

2424

25| Aspect | Claude Platform on AWS | [Claude in Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock) | [Amazon Bedrock (Opus 4.6 and earlier)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy) |

26| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |

27| **Who operates the stack** | Anthropic | AWS | AWS |

28| **API surface** | Claude API (`/v1/{endpoint}`) | Messages API at `/anthropic/v1/messages` | Bedrock Converse / InvokeModel |

29| **Feature availability** | Typically same-day as Claude API (see [feature limitations](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#features-not-supported)) | Per Amazon Bedrock release schedule | Per Amazon Bedrock release schedule |

31| **Beta features** | Pass through with `anthropic-beta` headers (see [feature limitations](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#features-not-supported)) | `anthropic-beta` header not supported | `anthropic-beta` header not supported |

34| **Base URL** | `aws-external-anthropic.{region}.api.aws` | `bedrock-mantle.{region}.api.aws` | `bedrock-runtime.{region}.amazonaws.com` |

38| **Inference data processor** | Anthropic | AWS | AWS |

25| Aspect | Claude Platform on AWS | [Claude in Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock) | [Amazon Bedrock (Opus 4.6 and earlier)](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy) |

26| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |

27| **Who operates the stack** | Anthropic | AWS | AWS |

28| **API surface** | Claude API (`/v1/{endpoint}`) | Messages API at `/anthropic/v1/messages` | Bedrock Converse / InvokeModel |

29| **Feature availability** | Typically same-day as Claude API (see [feature limitations](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#features-not-supported)) | Per Amazon Bedrock release schedule | Per Amazon Bedrock release schedule |

31| **Beta features** | Pass through with `anthropic-beta` headers (see [feature limitations](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#features-not-supported)) | `anthropic-beta` header not supported | `anthropic-beta` header not supported |

34| **Base URL** | `aws-external-anthropic.{region}.api.aws` | `bedrock-mantle.{region}.api.aws` | `bedrock-runtime.{region}.amazonaws.com` |

35| **SDK client** | `AnthropicAWS` (python; typescript: `AnthropicAws`; csharp: `AnthropicAwsClient`; go: `anthropicaws.NewClient`; java: `AwsBackend`; php: `Anthropic\Aws\Client`; ruby: `Anthropic::AWSClient`), in beta | `AnthropicBedrockMantle` | `AnthropicBedrock` / Bedrock SDK |

38| **Inference data processor** | Anthropic | AWS | AWS |

3939

4040If you need AWS-operated Claude, see [Claude in Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock). Claude Platform on AWS uses a separate capacity pool from both the first-party Claude API and Amazon Bedrock. You can run workloads on more than one platform and fail over between them.

4141

from line 272

272272

273273## Install an SDK

274274

275Anthropic's [client SDKs](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) support Claude Platform on AWS. Each SDK provides a platform-specific client class that handles SigV4 signing, region-based base URL construction, and the `anthropic-workspace-id` header.

275Anthropic's [client SDKs](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) support Claude Platform on AWS. Your SDK provides `AnthropicAWS` (python; typescript: `AnthropicAws`; csharp: `AnthropicAwsClient`; go: `anthropicaws.NewClient`; java: `AwsBackend`; php: `Anthropic\Aws\Client`; ruby: `Anthropic::AWSClient`), which handles SigV4 signing, region-based base URL construction, and the `anthropic-workspace-id` header.

276276

277277<Tabs>

278278 <Tab title="Python">

build-with-claude/fast-mode Changed · +3 / -3 lines

from line 407

407407

408408### Automatic retries

409409

410When fast mode rate limits are exceeded, the API returns a `429` error with a `retry-after` header. The Anthropic SDKs automatically retry these requests up to 2 times by default (configurable with `max_retries`), waiting for the server-specified delay before each retry. Because fast mode uses continuous token replenishment, the `retry-after` delay is typically short and requests succeed once capacity is available.

410When fast mode rate limits are exceeded, the API returns a `429` error with a `retry-after` header. The Anthropic SDKs automatically retry these requests up to 2 times by default (configurable with `max_retries` (typescript, java, php: `maxRetries`; csharp: `MaxRetries`; go: `option.WithMaxRetries`)), waiting for the server-specified delay before each retry. Because fast mode uses continuous token replenishment, the `retry-after` delay is typically short and requests succeed once capacity is available.

411411

412412### Falling back to standard speed

413413

from line 415

415415 This section covers an opt-in client-side fallback when fast mode is rate limited. It is separate from the behavior on [Claude Opus 4.6](https://platform.claude.com/docs/en/build-with-claude/fast-mode#supported-models), where fast mode is not available and requests run at standard speed automatically.

416416</Note>

417417

418If you'd prefer to fall back to standard speed rather than wait for fast mode capacity, catch the rate limit error and retry without `speed: "fast"`. Set `max_retries` to `0` on the initial fast request to skip automatic retries and fail immediately on rate limit errors.

418If you'd prefer to fall back to standard speed rather than wait for fast mode capacity, catch the rate limit error and retry without `speed: "fast"`. Set `max_retries` (typescript, java, php: `maxRetries`; csharp: `MaxRetries`; go: `option.WithMaxRetries`) to `0` on the initial fast request to skip automatic retries and fail immediately on rate limit errors.

419419

420420<Note>

421421 Falling back from fast to standard speed will result in a [prompt cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) miss. Requests at different speeds do not share cached prefixes.

422422</Note>

423423

424Because setting `max_retries` to `0` also disables retries for other transient errors (overloaded, internal server errors), the following examples reissue the original request with default retries for those cases.

424Because setting `max_retries` (typescript, java, php: `maxRetries`; csharp: `MaxRetries`; go: `option.WithMaxRetries`) to `0` also disables retries for other transient errors (overloaded, internal server errors), the following examples reissue the original request with default retries for those cases.

425425

426426<CodeGroup exclude="shell:cURL">

427427 ```bash CLI

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

from line 17

1717

1818 This feature is available on Claude Fable 5.1, [Claude Mythos 5.1](https://anthropic.com/glasswing), Claude Fable 5, [Claude Mythos 5](https://anthropic.com/glasswing), Claude Opus 5.5, Claude Opus 4.8, and Claude Opus 5. No beta header is required for mid-conversation system messages. This feature is not available on Claude Sonnet 5. Use the top-level `system` field there instead.

1919

20 [Mid-conversation tool changes](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#mid-conversation-tool-changes) are in beta and require the `mid-conversation-tool-changes-2026-07-01` beta header. They are available on the same models, on the Claude API, Amazon Bedrock, and Google Cloud. [Defining a tool inside a `tool_addition` block](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#define-tools-in-a-message-beta) uses the `inline-tools-2026-09-15` beta header in place of that one, and is available on the Claude API. [Adding an MCP server that way](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#add-an-mcp-server-mid-conversation-beta) also needs the `mcp-client-2026-09-15` beta header.

20 [Mid-conversation tool changes](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#mid-conversation-tool-changes) are in beta on the same models. On the Claude API, send the `inline-tools-2026-09-15` beta header, which also covers [defining a tool inside a `tool_addition` block](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#define-tools-in-a-message-beta). Defining a tool in a message is available on the Claude API only, and [adding an MCP server that way](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#add-an-mcp-server-mid-conversation-beta) needs the `mcp-client-2026-09-15` beta header as well. The older `mid-conversation-tool-changes-2026-07-01` header still works for changes that name a tool by reference, on the Claude API, Amazon Bedrock, and Google Cloud.

2121

2222 [Turn-scoped system messages](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#turn-scoped-system-messages) (`clear_at`) are in beta and require the `mid-conversation-system-clear-at-2026-08-21` beta header, on the same models and platforms as mid-conversation system messages.

2323</Note>

from line 24

2424

2525## Mid-conversation tool changes

2626

27The `tools` array sits even earlier in the hashed request prefix than the top-level `system` field, so editing it invalidates the [prompt cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) for the entire conversation. Mid-conversation tool changes are the tools counterpart to mid-conversation system messages. Instead of fixing the tool list for the lifetime of the conversation, you change which tools are offered to the model between turns: declare the full tool set in `tools` up front, then use `tool_addition` and `tool_removal` blocks to offer a tool to the model, or withdraw it, from a specific point in the conversation onward. The `tools` array itself never changes, so the cached prefix stays intact.

27The `tools` array sits even earlier in the hashed request prefix than the top-level `system` field, so editing it invalidates the [prompt cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) for the entire conversation. Mid-conversation tool changes are the tools counterpart to mid-conversation system messages. Instead of fixing the tool list for the lifetime of the conversation, you change which tools are offered to the model between turns: declare the full tool set in `tools` up front, then use `tool_addition` and `tool_removal` blocks to offer a tool to the model, or withdraw it, from a specific point in the conversation onward. The `tools` array itself never changes, so the cached prefix stays intact. Mid-conversation tool changes are in beta and use the `inline-tools-2026-09-15` beta header on the Claude API. On Amazon Bedrock and Google Cloud, use the older `mid-conversation-tool-changes-2026-07-01` header, which covers changes that name a tool by reference.

2828

29`tool_addition` and `tool_removal` are content blocks in the `content` array of a `role: "system"` message, and they can be mixed with `text` blocks in the same message. The message follows the placement rules for any mid-conversation system message, with one extra restriction after a paused turn (see [Limitations](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#limitations)), and the change applies from that point in the conversation onward. Each block's `tool` field references a tool rather than defining one: `{"type": "tool_reference", "name": "..."}` names a tool declared in the request's `tools` array, and [MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector) tools can be referenced individually with `mcp_tool_reference` (`server_name` and `name`) or as a whole toolset with `mcp_toolset_reference` (`server_name`). Referencing a name that is not declared in `tools` returns a 400 error (on the Claude API, with `error.details.error_code` set to `tool_reference_unresolved`). With the `inline-tools-2026-09-15` beta header, a `tool_addition` block can instead [carry the tool's full definition](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#define-tools-in-a-message-beta).

29`tool_addition` and `tool_removal` are content blocks in the `content` array of a `role: "system"` message, and they can be mixed with `text` blocks in the same message. The message follows the placement rules for any mid-conversation system message, with one extra restriction after a paused turn (see [Limitations](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#limitations)), and the change applies from that point in the conversation onward. Each block's `tool` field references a tool rather than defining one: `{"type": "tool_reference", "name": "..."}` names a tool declared in the request's `tools` array, and [MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector) tools can be referenced individually with `mcp_tool_reference` (`server_name` and `name`) or as a whole toolset with `mcp_toolset_reference` (`server_name`). Referencing a name that is not declared in `tools` returns a 400 error (on the Claude API, with `error.details.error_code` set to `tool_reference_unresolved`). A `tool_addition` block can instead [carry the tool's full definition](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#define-tools-in-a-message-beta), which the older `mid-conversation-tool-changes-2026-07-01` header doesn't support.

3030

3131Every tool declared in `tools` is offered to the model from the start of the conversation unless it is declared with `defer_loading: true`, which keeps it withheld until a `tool_addition` block surfaces it. `tool_addition` also re-offers a tool that an earlier `tool_removal` withdrew.

3232

33The following request declares `get_weather` in `tools`, then withdraws it after the first user turn with a `tool_removal` block. Mid-conversation tool changes are in beta, so the request sends the `mid-conversation-tool-changes-2026-07-01` beta header.

33The following request declares `get_weather` in `tools`, then withdraws it after the first user turn with a `tool_removal` block. The request sends the `inline-tools-2026-09-15` beta header.

3434

3535<CodeGroup>

3636 ```bash cURL

from line 38

3838 -H "content-type: application/json" \

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

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

41 -H "anthropic-beta: mid-conversation-tool-changes-2026-07-01" \

41 -H "anthropic-beta: inline-tools-2026-09-15" \

4242 -d '{

4343 "model": "claude-opus-5-5",

4444 "max_tokens": 1024,

from line 74

7474 ```

7575

7676 ```bash CLI

77 ant beta:messages create --beta mid-conversation-tool-changes-2026-07-01 \

77 ant beta:messages create --beta inline-tools-2026-09-15 \

7878 --transform 'content.#(type=="text").text' --raw-output <<'YAML'

7979 model: claude-opus-5-5

8080 max_tokens: 1024

from line 107

107107 response = client.beta.messages.create(

108108 model="claude-opus-5-5",

109109 max_tokens=1024,

110 betas=["mid-conversation-tool-changes-2026-07-01"],

110 betas=["inline-tools-2026-09-15"],

111111 # The full tool set is declared up front and never changes, so the

112112 # cached prefix stays intact.

113113 tools=[

from line 154

154154 const response = await client.beta.messages.create({

155155 model: "claude-opus-5-5",

156156 max_tokens: 1024,

157 betas: ["mid-conversation-tool-changes-2026-07-01"],

157 betas: ["inline-tools-2026-09-15"],

158158 // The full tool set is declared up front and never changes, so the

159159 // cached prefix stays intact.

160160 tools: [

from line 198

198198 ```

199199

200200 ```csharp C#

201 using Anthropic.Models.Beta;

201202 using Anthropic.Models.Beta.Messages;

202203 using Messages = Anthropic.Models.Messages;

203204

from line 208

207208 {

208209 Model = Messages::Model.ClaudeOpus5_5,

209210 MaxTokens = 1024,

210 Betas = ["mid-conversation-tool-changes-2026-07-01"],

211 Betas = [AnthropicBeta.InlineTools2026_09_15],

211212 // The full tool set is declared up front and never changes, so the

212213 // cached prefix stays intact.

213214 Tools =

from line 262

261262 response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{

262263 Model: anthropic.ModelClaudeOpus5_5,

263264 MaxTokens: 1024,

264 Betas: []anthropic.AnthropicBeta{"mid-conversation-tool-changes-2026-07-01"},

265 Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaInlineTools2026_09_15},

265266 // The full tool set is declared up front and never changes, so the

266267 // cached prefix stays intact.

267268 Tools: []anthropic.BetaToolUnionParam{

from line 307

306307 ```

307308

308309 ```java Java

310 import com.anthropic.models.beta.AnthropicBeta;

309311 import com.anthropic.models.beta.messages.BetaContentBlockParam;

310312 import com.anthropic.models.beta.messages.BetaMessage;

311313 import com.anthropic.models.beta.messages.BetaMessageParam;

from line 335

333335 MessageCreateParams params = MessageCreateParams.builder()

334336 .model(Model.CLAUDE_OPUS_5_5)

335337 .maxTokens(1024)

336 .addBeta("mid-conversation-tool-changes-2026-07-01")

338 .addBeta(AnthropicBeta.INLINE_TOOLS_2026_09_15)

337339 .addTool(weatherTool)

338340 .addUserMessage("Say OK.")

339341 // Withdraw get_weather from this point onward. The block references

from line 357

355357 ```

356358

357359 ```php PHP

360 use Anthropic\Beta\AnthropicBeta;

361 // ...

362

358363 $client = new Client();

359364

360365 $response = $client->beta->messages->create(

361 model: 'claude-opus-5-5',

366 model: Model::CLAUDE_OPUS_5_5,

362367 maxTokens: 1024,

363 betas: ['mid-conversation-tool-changes-2026-07-01'],

368 betas: [AnthropicBeta::INLINE_TOOLS_2026_09_15],

364369 // The full tool set is declared up front and never changes, so the

365370 // cached prefix stays intact.

366371 tools: [

from line 412

407412 client = Anthropic::Client.new

408413

409414 response = client.beta.messages.create(

410 model: "claude-opus-5-5",

415 model: Anthropic::Model::CLAUDE_OPUS_5_5,

411416 max_tokens: 1024,

412 betas: ["mid-conversation-tool-changes-2026-07-01"],

417 betas: [Anthropic::AnthropicBeta::INLINE_TOOLS_2026_09_15],

413418 # The full tool set is declared up front and never changes, so the

414419 # cached prefix stays intact.

415420 tools: [

build-with-claude/refusals-and-fallback Changed · +19 / -11 lines

from line 180

180180* `category` and `explanation` are both `null` when the refusal does not map to a named category. That `null` is a normal, permanent value, not a placeholder.

181181* `stop_details` itself is `null` for every stop reason other than `refusal`.

182182

183| `category` | What it means |

184| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

185| `"cyber"` | The request could enable cyber harm, such as malware or exploit development. Benign cybersecurity work can also trigger this category. |

186| `"bio"` | The request could enable biological harm, such as dangerous lab methods. Beneficial life sciences work can also trigger this category. |

187| `"frontier_llm"` | The request could assist the development of competing AI models, which is restricted under [Anthropic's commercial terms](https://www.anthropic.com/legal/commercial-terms). Benign machine learning work can also trigger this category. |

188| `"reasoning_extraction"` | The request asks the model to reproduce its internal reasoning in the response text. To get reasoning in a structured form instead, use [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking). |

189| `"general_harms"` | The request falls under a usage-policy area outside the four named categories. Benign work can also trigger this category. |

183| `category` | What it means | Billed before any output |

184| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |

185| `"cyber"` | The request could enable cyber harm, such as malware or exploit development. Benign cybersecurity work can also trigger this category. | No |

186| `"bio"` | The request could enable biological harm, such as dangerous lab methods. Beneficial life sciences work can also trigger this category. | Yes |

187| `"frontier_llm"` | The request could assist the development of competing AI models, which is restricted under [Anthropic's commercial terms](https://www.anthropic.com/legal/commercial-terms). Benign machine learning work can also trigger this category. | Yes |

188| `"reasoning_extraction"` | The request asks the model to reproduce its internal reasoning in the response text. To get reasoning in a structured form instead, use [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking). | Yes |

189| `"general_harms"` | The request falls under a usage-policy area outside the four named categories. Benign work can also trigger this category. | No |

190190

191191A refusal can arrive before any output, or mid-stream after partial output. In either case, treat any partial output as incomplete and discard it.

192192

193193## How refusals are billed

194194

195You are not billed for a refusal that arrives before any output. `content` is empty, and token counts appear in `usage` but are not charged. The request still counts against your rate limits. A mid-stream refusal bills the input tokens and the output already streamed at normal rates.

195These billing rules apply on every platform: the Claude API, Amazon Bedrock, Claude Platform on AWS, Google Cloud, and Microsoft Foundry.

196196

197**Refusals before any output:** To disrupt attempts to circumvent Anthropic's safeguards at scale, a refusal that arrives before any output is billed when its `stop_details.category` is `"bio"`, `"frontier_llm"`, or `"reasoning_extraction"`. These are the categories where Anthropic measures low volumes of false positives, as of September 2026. These refusals are billed like any other request, at the rates of the model that ran it. A refusal before any output in any other category, or with a `null` category, is not billed. Either way, `content` is empty and token counts appear in `usage`. The request still counts against your rate limits.

198

199**Mid-stream refusals:** A mid-stream refusal bills the input tokens and the output already streamed at normal rates.

200

201**Fallback:** When you use fallback, the refusal that triggered it is billed, in addition to the fallback request, when it arrived mid-stream or is in one of the billed categories. [Fallback credit](https://platform.claude.com/docs/en/build-with-claude/fallback-credit) compensates for the fallback request's prompt-cache miss, so you don't pay to cache the conversation twice. For how server-side fallback reports each attempt, see [Billing and rate limits](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#billing-and-rate-limits).

202

203The billed categories may change as Anthropic keeps measuring and refining its safeguards' false positive rates. The **Billed before any output** column in the [refusal category table](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#refusal-response) lists the billed categories.

204

197205## Picking a fallback approach

198206

199207There are three ways to retry a refused request on another model. The right one depends on where you are running and how much control you need.

from line 745

737745

738746### Billing and rate limits

739747

740An attempt that declined before producing any output is not billed: its tokens are reported on its `usage.iterations` entry but not charged. Every attempt that produced output, including one that declined partway through its response, is billed separately at the rates of the model that ran it. The `usage.iterations` array is the per-attempt record of what you're billed. The top-level `usage` counts describe only the attempt that produced the returned message. Tokens from different models are never summed into one field.

748Each attempt follows the rules in [How refusals are billed](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#how-refusals-are-billed), at the rates of the model that ran it. An attempt that declined before producing any output is billed only when its refusal category is billed, and its tokens are reported on its `usage.iterations` entry either way. Every attempt that produced output, including one that declined partway through its response, is billed separately. The `usage.iterations` array is the per-attempt record of what you're billed. The top-level `usage` counts describe only the attempt that produced the returned message. Tokens from different models are never summed into one field.

741749

742750Every attempt that runs, including one that declined, counts against its own model's rate limits.

743751

from line 763

755763

756764## Client-side fallback with the SDK middleware

757765

758Every Anthropic SDK includes a refusal-fallback middleware. You configure it once on the client with your list of fallback models. Calls through `client.beta.messages` then retry refused requests automatically, on any platform. The middleware also sends the `fallback-credit-2026-07-01` beta header on every request it handles, so retries are repriced without per-request setup.

766Every Anthropic SDK includes a refusal-fallback middleware. You configure it once on the client with your list of fallback models. Calls through `client.beta.messages` (csharp, go: `client.Beta.Messages`; java: `client.beta().messages()`; php: `$client->beta->messages`) then retry refused requests automatically, on any platform. The middleware also sends the `fallback-credit-2026-07-01` beta header on every request it handles, so retries are repriced without per-request setup.

759767

760768### Setting it up

761769

762Pass the middleware to the client constructor, and share one `BetaFallbackState` instance across the requests of a conversation.

770Pass `BetaRefusalFallbackMiddleware` (typescript: `betaRefusalFallbackMiddleware`; go: `betafallback.BetaRefusalFallbackMiddleware`; csharp: `BetaRefusalFallbackHandler`; java: `BetaRefusalFallbackInterceptor`; php: `RefusalFallbackMiddleware`) to the client constructor, and share one `BetaFallbackState` instance across the requests of a conversation.

763771

764772<CodeGroup>

765773 ```bash cURL

manage-claude/inference-hooks Changed · +14 / -1 lines

## Continue a conversation after a denied request

from line 41

4141

4242***

4343

44## Continue a conversation after a denied request

45

46Each request includes the whole conversation, so a denied message is sent again with every later message. If your AI security server evaluates the whole transcript, it denies those requests too. To continue, the user removes the denied content from what the app sends next, including any file Claude would read again.

47

48The steps depend on the app:

49

50* **claude.ai, including Claude Desktop and the mobile apps.** The user edits the denied message, or an earlier one, rather than sending a corrected copy as a new message. On the web and in Claude Desktop, the edit resends the message's attachments unless the user removes them. A new chat also works.

51* **Claude Code.** The user runs `/rewind` and selects the prompt that first brought the content in. If asked, they select **Restore conversation**, then edit or clear the prompt that returns to the input field. `/clear` starts over. See [Checkpointing](https://code.claude.com/docs/en/checkpointing).

52* **Cowork.** The user edits the denied message if it is their latest one. The edit resends attached files, and **Restart from here** resends the whole message unchanged. If the content is in a file or an earlier message, the user selects **New task**.

53* **Claude Tag.** In Slack, the user first edits the denied message, or deletes it if it is a reply. They then send `@Claude !restart` on its own where Claude was answering: in that thread, or at the channel's top level. The new session rereads the messages still in Slack, so the edit or deletion comes first. See the [`!restart` command](https://claude.com/docs/claude-tag/users/commands#restart-a-stuck-or-wrong-context-session).

54

55***

56

4457## Use cases

4558

4659* **Data loss prevention (DLP).** Forward the transcript to your DLP scanner and deny prompts that carry regulated or classified material. This is the most common deployment.

from line 75

6275

6376Inference hooks are available to Claude Enterprise organizations. Configuring them requires the `organization:manage` permission, which only the Owner and Primary owner roles hold.

6477

65One hook governs conversations across claude.ai, Cowork, and Claude Code sessions in your Claude Enterprise organization, whether they run on the web, in the desktop or mobile apps, or in the CLI. Inference hooks are not available on Amazon Bedrock or Google Cloud.

78One hook governs conversations across claude.ai, Cowork, Claude Code, and Claude Tag sessions in your Claude Enterprise organization, whether they run on the web, in the desktop or mobile apps, in the CLI, or in Slack. Inference hooks are not available on Amazon Bedrock or Google Cloud.

6679

6780Governed requests are the inference requests behind the user's conversation. Ancillary requests, such as conversation title generation, aren't sent to your endpoint, and system prompts and tool definitions are never included in what is sent. Voice mode is not covered.

6881

manage-claude/wif-providers/azure Changed · +4 / -4 lines

from line 141

141141

142142### Acquire and use the token

143143

144At runtime your workload fetches its Entra token, exchanges it at `POST /v1/oauth/token`, and uses the returned bearer token to call Claude. Each Anthropic SDK handles the exchange and refresh loop when you supply a token-provider callable, as shown in the following examples. The cURL tab shows the raw flow.

144At runtime your workload fetches its Entra token, exchanges it at `POST /v1/oauth/token`, and uses the returned bearer token to call Claude. Each Anthropic SDK handles the exchange and refresh loop when you supply `identity_token_provider` (typescript, php: `identityTokenProvider`; csharp: `IdentityTokenProvider`; go: `option.WithFederationTokenProvider`; java: `federationTokenProvider`), as shown in the following examples. The cURL tab shows the raw flow.

145145

146146The samples fetch the managed identity token from the platform's token endpoint: IMDS on VMs and VM Scale Sets, or the `IDENTITY_ENDPOINT` service on App Service, Functions, and Container Apps. Replace `<APP_ID>` in the `api://<APP_ID>` resource value with the audience app registration's client ID from [Register the token audience](https://platform.claude.com/docs/en/manage-claude/wif-providers/azure#register-the-token-audience).

147147

148148<Tip>

149 If your workload already uses the Azure Identity client library, pass its token acquisition (`DefaultAzureCredential` with the scope `api://<APP_ID>/.default`) as the identity token provider instead of calling the token endpoints directly. The library selects the correct endpoint on every Azure platform, including AKS with Entra Workload Identity.

149 If your workload already uses the Azure Identity client library, pass its token acquisition (`DefaultAzureCredential` with the scope `api://<APP_ID>/.default`) to `identity_token_provider` (typescript, php: `identityTokenProvider`; csharp: `IdentityTokenProvider`; go: `option.WithFederationTokenProvider`; java: `federationTokenProvider`) instead of calling the token endpoints directly. The library selects the correct endpoint on every Azure platform, including AKS with Entra Workload Identity.

150150</Tip>

151151

152152<CodeGroup>

from line 761

761761

762762### Acquire and use the token

763763

764At runtime the pod performs the two-hop exchange: it sends the Kubernetes-projected token (the file at `AZURE_FEDERATED_TOKEN_FILE`) to Entra's token endpoint as a federated `client_credentials` assertion, then exchanges the resulting Entra access token at `POST /v1/oauth/token`. Each Anthropic SDK handles the second exchange and the refresh loop when you supply the Entra fetch as a token-provider callable, as shown in the following examples. The cURL tab shows the raw flow.

764At runtime the pod performs the two-hop exchange: it sends the Kubernetes-projected token (the file at `AZURE_FEDERATED_TOKEN_FILE`) to Entra's token endpoint as a federated `client_credentials` assertion, then exchanges the resulting Entra access token at `POST /v1/oauth/token`. Each Anthropic SDK handles the second exchange and the refresh loop when you pass the Entra fetch to `identity_token_provider` (typescript, php: `identityTokenProvider`; csharp: `IdentityTokenProvider`; go: `option.WithFederationTokenProvider`; java: `federationTokenProvider`), as shown in the following examples. The cURL tab shows the raw flow.

765765

766766Two different client IDs appear in the samples. `<APP_ID>` is the audience app registration's client ID from [Register the token audience](https://platform.claude.com/docs/en/manage-claude/wif-providers/azure#register-the-token-audience); the scope `api://<APP_ID>/.default` asks Entra for a token addressed to that audience. `$AZURE_CLIENT_ID` is the managed identity's client ID, injected by the webhook, and identifies the caller. Do not substitute one for the other.

767767

768768<Tip>

769 If your workload already uses the Azure Identity client library, pass its token acquisition (`DefaultAzureCredential` with the scope `api://<APP_ID>/.default`) as the identity token provider instead of performing the two-hop exchange yourself. The library reads the same `AZURE_FEDERATED_TOKEN_FILE`, `AZURE_CLIENT_ID`, and `AZURE_TENANT_ID` environment variables and handles the Entra exchange.

769 If your workload already uses the Azure Identity client library, pass its token acquisition (`DefaultAzureCredential` with the scope `api://<APP_ID>/.default`) to `identity_token_provider` (typescript, php: `identityTokenProvider`; csharp: `IdentityTokenProvider`; go: `option.WithFederationTokenProvider`; java: `federationTokenProvider`) instead of performing the two-hop exchange yourself. The library reads the same `AZURE_FEDERATED_TOKEN_FILE`, `AZURE_CLIENT_ID`, and `AZURE_TENANT_ID` environment variables and handles the Entra exchange.

770770</Tip>

771771

772772<CodeGroup>

managed-agents/migration Changed · +10 / -10 lines

from line 618

618618

619619### What changes

620620

621| Agent SDK | Managed Agents |

622| --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

623| `ClaudeAgentOptions(...)` constructed per run | `client.beta.agents.create(...)` once; the Agent is persisted and versioned server-side. See [Agent setup](https://platform.claude.com/docs/en/managed-agents/agent-setup). |

624| `async with ClaudeSDKClient(...)` or `query(...)` | `client.beta.sessions.create(...)` then send and receive [events](https://platform.claude.com/docs/en/managed-agents/events-and-streaming). |

625| `@tool`-decorated functions dispatched automatically by the SDK | Declare as `{"type": "custom", ...}` on the Agent; your client handles `agent.custom_tool_use` events and replies with `user.custom_tool_result`. See [Tools](https://platform.claude.com/docs/en/managed-agents/tools). |

626| Built-in tools run in your process against your filesystem | `{"type": "agent_toolset_20260401"}` runs the same tools inside the session sandbox against `/workspace`. |

627| `cwd`, `add_dirs` point at local paths | Upload or mount [files](https://platform.claude.com/docs/en/managed-agents/files) as session resources. |

628| `system_prompt` and the `CLAUDE.md` hierarchy | A single `system` string on the Agent. Each update that changes the agent produces a new server-side version; pin sessions to a specific version to promote or roll back without a deploy. See [Agent setup](https://platform.claude.com/docs/en/managed-agents/agent-setup). |

629| `mcp_servers` configured and authenticated in one place | Declare servers on the Agent; provide credentials through a [Vault](https://platform.claude.com/docs/en/managed-agents/vaults) on the Session. |

630| `permission_mode`, `can_use_tool` | Per-tool [`permission_policy`](https://platform.claude.com/docs/en/managed-agents/permission-policies) (`always_allow`, `always_ask`, or `auto`); send `user.tool_confirmation` events for calls that pause for your approval. |

621| Agent SDK | Managed Agents |

622| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

623| `ClaudeAgentOptions(...)` (python; typescript: `options`) constructed per run | `client.beta.agents.create(...)` (csharp: `client.Beta.Agents.Create(...)`; go: `client.Beta.Agents.New(...)`; java: `client.beta().agents().create(...)`; php: `$client->beta->agents->create(...)`) once; the Agent is persisted and versioned server-side. See [Agent setup](https://platform.claude.com/docs/en/managed-agents/agent-setup). |

624| `async with ClaudeSDKClient(...)` or `query(...)` | `client.beta.sessions.create(...)` (csharp: `client.Beta.Sessions.Create(...)`; go: `client.Beta.Sessions.New(...)`; java: `client.beta().sessions().create(...)`; php: `$client->beta->sessions->create(...)`) then send and receive [events](https://platform.claude.com/docs/en/managed-agents/events-and-streaming). |

625| Functions defined with `@tool` (python; typescript: `tool()`), dispatched automatically by the SDK | Declare as `{"type": "custom", ...}` on the Agent; your client handles `agent.custom_tool_use` events and replies with `user.custom_tool_result`. See [Tools](https://platform.claude.com/docs/en/managed-agents/tools). |

626| Built-in tools run in your process against your filesystem | `{"type": "agent_toolset_20260401"}` runs the same tools inside the session sandbox against `/workspace`. |

627| `cwd`, `add_dirs` (python; typescript: `additionalDirectories`) point at local paths | Upload or mount [files](https://platform.claude.com/docs/en/managed-agents/files) as session resources. |

628| `system_prompt` (python; typescript: `systemPrompt`) and the `CLAUDE.md` hierarchy | A single `system` string on the Agent. Each update that changes the agent produces a new server-side version; pin sessions to a specific version to promote or roll back without a deploy. See [Agent setup](https://platform.claude.com/docs/en/managed-agents/agent-setup). |

629| `mcp_servers` (python; typescript: `mcpServers`) configured and authenticated in one place | Declare servers on the Agent; provide credentials through a [Vault](https://platform.claude.com/docs/en/managed-agents/vaults) on the Session. |

630| `permission_mode` (python; typescript: `permissionMode`), `can_use_tool` (python; typescript: `canUseTool`) | Per-tool [`permission_policy`](https://platform.claude.com/docs/en/managed-agents/permission-policies) (`always_allow`, `always_ask`, or `auto`); send `user.tool_confirmation` events for calls that pause for your approval. |

631631

632632### Code comparison

633633

managed-agents/self-hosted-sandboxes Changed · +27 / -27 lines

from line 426

426426 <Step title="Implement the webhook handler">

427427 `EnvironmentWorker` claims the work item, downloads skills, executes tool calls in the working directory, posts results back, and exits. Invoke it when `session.status_run_started` fires.

428428

429 When you hand a claimed work item to `handle_item()` yourself, as this handler does, pass the work item's `secret` along as `work_secret` (`workSecret` in TypeScript, `WorkSecret` in Go) so the session can mount any [memory stores](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes#use-memory-stores) attached to it. A handler like this one runs every claimed item in one process on one host, so two sessions that attach the same memory store cannot run through it at the same time (see [Prepare the host](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes#prepare-the-host)); if your sessions share stores, launch [one sandbox per session](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes#run-one-sandbox-per-session) instead.

429 When you hand a claimed work item to `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`) yourself, as this handler does, pass the work item's `secret` along as `work_secret` (typescript: `workSecret`; go: `WorkSecret`) so the session can mount any [memory stores](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes#use-memory-stores) attached to it. A handler like this one runs every claimed item in one process on one host, so two sessions that attach the same memory store cannot run through it at the same time (see [Prepare the host](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes#prepare-the-host)); if your sessions share stores, launch [one sandbox per session](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes#run-one-sandbox-per-session) instead.

430430

431431 <CodeGroup exclude="shell">

432432 ```python Python

from line 689

689689

690690* **`EnvironmentWorker`:** the out-of-the-box worker. Handles polling, setup, and execution end to end.

691691

692 * `.run()`: runs indefinitely, picking up sessions as they arrive.

693 * `.handle_item()`: handles a single claimed work item and exits. Pass the work, session, and environment identifiers explicitly, or let it read the `ANTHROPIC_*` variables that `ant beta:worker poll --on-work` sets for the process it spawns. To let the session mount its [memory stores](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes#use-memory-stores), also pass the work item's `secret` as `work_secret` (`workSecret` in TypeScript, `WorkSecret` in Go) or set `ANTHROPIC_WORK_SECRET`; `ant beta:worker poll --on-work` does not set that variable, so read the secret from the work item JSON it writes to your script's standard input, as shown in [Run one sandbox per session](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes#run-one-sandbox-per-session).

694 * `memory_sync_interval` (`memorySyncIntervalMs` in TypeScript, `MemorySyncInterval` in Go) and `memory_sync_deletions` (`memorySyncDeletions`, `MemorySyncDeletions`): how often attached memory stores reconcile with the server while the session runs, and whether files the agent deletes locally are also deleted from the store. See [Configure sync](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes#configure-sync) for units, defaults, and how to disable memory support.

692 * `.run()` (go: `.Run()`): runs indefinitely, picking up sessions as they arrive.

693 * `.handle_item()` (typescript: `.handleItem()`; go: `.HandleItem()`): handles a single claimed work item and exits. Pass the work, session, and environment identifiers explicitly, or let it read the `ANTHROPIC_*` variables that `ant beta:worker poll --on-work` sets for the process it spawns. To let the session mount its [memory stores](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes#use-memory-stores), also pass the work item's `secret` as `work_secret` (typescript: `workSecret`; go: `WorkSecret`) or set `ANTHROPIC_WORK_SECRET`; `ant beta:worker poll --on-work` does not set that variable, so read the secret from the work item JSON it writes to your script's standard input, as shown in [Run one sandbox per session](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes#run-one-sandbox-per-session).

694 * `memory_sync_interval` (typescript: `memorySyncIntervalMs`; go: `MemorySyncInterval`) and `memory_sync_deletions` (typescript: `memorySyncDeletions`; go: `MemorySyncDeletions`): how often attached memory stores reconcile with the server while the session runs, and whether files the agent deletes locally are also deleted from the store. See [Configure sync](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes#configure-sync) for units, defaults, and how to disable memory support.

695695

696* **`work.poller()`:** polls the work queue on your behalf and gives you each claimed session. Use this when you want to decide what happens for each session, for example launching a sandbox rather than running tools in-process.

696* **`work.poller()` (go: `environments.NewWorkPoller()`):** polls the work queue on your behalf and gives you each claimed session. Use this when you want to decide what happens for each session, for example launching a sandbox rather than running tools in-process.

697697

698 * `drain`: whether to stop polling once the queue is empty rather than waiting for new work.

699 * `block_ms`: how long to wait for work to arrive before returning, in milliseconds. Must be between 1 and 999 (per-poll wait; the helper re-polls automatically). Pass `null` (`None` in Python, `param.Null[int64]()` in Go) for a non-blocking check; omitting the parameter uses the default 999 ms long-poll.

700 * `reclaim_older_than_ms`: re-claim work items that were claimed but never acknowledged within this many milliseconds.

701 * `auto_stop` (`autoStop` in TypeScript, `AutoStop` in Go): whether to post a stop signal for each work item once your loop body finishes with it. Turn it off whenever whatever runs the work item posts the stop itself: `handle_item()` does, so set it to false when you hand claimed items to `handle_item()` as the webhook handlers on this page do, and so does a sandbox you launch that owns the stop call.

698 * `drain` (go: `Drain`): whether to stop polling once the queue is empty rather than waiting for new work.

699 * `block_ms` (python; typescript: `blockMs`; go: `BlockMs`): how long to wait for work to arrive before returning, in milliseconds. Must be between 1 and 999 (per-poll wait; the helper re-polls automatically). Pass `null` (typescript; python: `None`; go: `param.Null[int64]()`) for a non-blocking check; omitting the parameter uses the default 999 ms long-poll.

700 * `reclaim_older_than_ms` (typescript: `reclaimOlderThanMs`; go: `ReclaimOlderThanMs`): re-claim work items that were claimed but never acknowledged within this many milliseconds.

701 * `auto_stop` (typescript: `autoStop`; go: `AutoStop`): whether to post a stop signal for each work item once your loop body finishes with it. Turn it off whenever whatever runs the work item posts the stop itself: `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`) does, so set it to false when you hand claimed items to `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`) as the webhook handlers on this page do, and so does a sandbox you launch that owns the stop call.

702702

703703* **`client.beta.sessions.events.tool_runner()`:** runs tool calls for a single session, given the session ID and a tool list. Use when you've already claimed the work and only need the execution layer.

704704

705Use the work poller directly when you want to launch your own per-session process, for example spinning up a sandbox for each claimed session:

705Use `work.poller()` (typescript: `new WorkPoller()`; go: `environments.NewWorkPoller()`) directly when you want to launch your own per-session process, for example spinning up a sandbox for each claimed session:

706706

707707<CodeGroup>

708708 ```bash cURL

from line 911

911911

912912Whatever launches the sandbox must forward the claimed work item's `secret` into it (for example as `ANTHROPIC_WORK_SECRET`) alongside the session, work, and environment identifiers, so the worker inside can mount the session's [memory stores](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes#use-memory-stores); see [Run one sandbox per session](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes#run-one-sandbox-per-session).

913913

914**`AgentToolContext`** is the execution context for tool calls. It defines the working directory and path policy, and can download the session's skills. The file tools (`read`, `write`, `edit`, `glob`, `grep`) are confined to the working directory plus any directories listed in `allowed_roots` (`allowedRoots` in TypeScript, `AllowedRoots` in Go), and `write` and `edit` additionally refuse paths under `read_only_roots` (`readOnlyRoots`, `ReadOnlyRoots`). `EnvironmentWorker` adds the session's memory store directories to these lists itself. The confinement is a guardrail for the file tools only, not a sandbox; it does not constrain `bash`. **`beta_agent_toolset_20260401(env)`** takes an `AgentToolContext` and returns the standard tool implementations (`bash`, `read`, `write`, `edit`, `glob`, `grep`).

914**`AgentToolContext`** is the execution context for tool calls. It defines the working directory and path policy, and can download the session's skills. The file tools (`read`, `write`, `edit`, `glob`, `grep`) are confined to the working directory plus any directories listed in `allowed_roots` (typescript: `allowedRoots`; go: `AllowedRoots`), and `write` and `edit` additionally refuse paths under `read_only_roots` (typescript: `readOnlyRoots`; go: `ReadOnlyRoots`). `EnvironmentWorker` adds the session's memory store directories to these lists itself. The confinement is a guardrail for the file tools only, not a sandbox; it does not constrain `bash`. **`beta_agent_toolset_20260401(env)` (typescript: `betaAgentToolset20260401(ctx)`; go: `agenttoolset.BetaAgentToolset20260401(env)`)** takes an `AgentToolContext` and returns the standard tool implementations (`bash`, `read`, `write`, `edit`, `glob`, `grep`).

915915

916**With `EnvironmentWorker`:** both are managed automatically. Pass a `tools` factory to customize the tool list:

916**With `EnvironmentWorker`:** both are managed automatically. Pass a `tools` (go: `ToolsFunc`) factory to customize the tool list:

917917

918918<CodeGroup exclude="shell">

919919 ```python Python

from line 960

960960 ```

961961</CodeGroup>

962962

963**With `work.poller()` and `tool_runner()`:** pass a tool list as `tools` to `client.beta.sessions.events.tool_runner()`. To build that list, set up `AgentToolContext` yourself and call `beta_agent_toolset_20260401(env)`:

963**With `work.poller()` (typescript; go: `environments.NewWorkPoller()`) and `tool_runner()`:** pass a tool list as `tools` to `client.beta.sessions.events.tool_runner()`. To build that list, set up `AgentToolContext` yourself and call `beta_agent_toolset_20260401(env)` (typescript: `betaAgentToolset20260401(ctx)`; go: `agenttoolset.BetaAgentToolset20260401(env)`):

964964

965965<CodeGroup exclude="shell">

966966 ```python Python

from line 1131

11311131

11321132## Use memory stores

11331133

1134Sessions on a self-hosted environment attach [memory stores](https://platform.claude.com/docs/en/managed-agents/memory) exactly as sessions on cloud environments do: list them in `resources` when you create the session, as shown in [Attach a memory store to a session](https://platform.claude.com/docs/en/managed-agents/memory#attach-a-memory-store-to-a-session). A session accepts up to 8 memory stores. On a self-hosted environment the SDK worker, rather than Anthropic's infrastructure, materializes each store for the agent, so memory stores there require `EnvironmentWorker` (or its `handle_item()` method) from the Python, TypeScript, or Go SDK.

1134Sessions on a self-hosted environment attach [memory stores](https://platform.claude.com/docs/en/managed-agents/memory) exactly as sessions on cloud environments do: list them in `resources` when you create the session, as shown in [Attach a memory store to a session](https://platform.claude.com/docs/en/managed-agents/memory#attach-a-memory-store-to-a-session). A session accepts up to 8 memory stores. On a self-hosted environment the SDK worker, rather than Anthropic's infrastructure, materializes each store for the agent, so memory stores there require `EnvironmentWorker` (or its `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`) method) from the Python, TypeScript, or Go SDK.

11351135

11361136The `ant` CLI worker (`ant beta:worker poll` and `ant beta:worker run`) does not mount memory stores. To combine the CLI poller with memory stores, run the SDK worker inside a per-session sandbox as described in [Run one sandbox per session](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes#run-one-sandbox-per-session).

11371137

from line 1167

11671167

11681168### Run one sandbox per session

11691169

1170The sandbox-per-session pattern in [Run a worker](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes#run-a-worker) gives each session a fresh filesystem, which is what [Prepare the host](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes#prepare-the-host) calls for when sessions attach the same store. Keep `ant beta:worker poll --on-work` (or the SDK's work poller) as the poller on the host.

1170The sandbox-per-session pattern in [Run a worker](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes#run-a-worker) gives each session a fresh filesystem, which is what [Prepare the host](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes#prepare-the-host) calls for when sessions attach the same store. Keep `ant beta:worker poll --on-work` (or the SDK's `work.poller()` (go: `environments.NewWorkPoller()`)) as the poller on the host.

11711171

1172The `ant beta:worker run` entrypoint shown there does not mount memory stores, so build the per-session image around the SDK worker instead: its entrypoint constructs `EnvironmentWorker` and calls `handle_item()` (`handleItem` in TypeScript, `HandleItem` in Go), which reads the session, work, and environment identifiers from the `ANTHROPIC_*` variables and the work item's per-session `secret` from `ANTHROPIC_WORK_SECRET`. You can also pass the secret explicitly as `work_secret` (`workSecret` in TypeScript, `WorkSecret` in Go).

1172The `ant beta:worker run` entrypoint shown there does not mount memory stores, so build the per-session image around the SDK worker instead: its entrypoint constructs `EnvironmentWorker` and calls `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`), which reads the session, work, and environment identifiers from the `ANTHROPIC_*` variables and the work item's per-session `secret` from `ANTHROPIC_WORK_SECRET`. You can also pass the secret explicitly as `work_secret` (typescript: `workSecret`; go: `WorkSecret`).

11731173

11741174<CodeGroup exclude="shell">

11751175 ```python Python

from line 1288

12881288 your-sdk-worker-image

12891289```

12901290

1291If you claim work with the SDK's work poller instead, pass each claimed item's `secret` into the sandbox you launch in the same way. Pass it only into the sandbox that serves that session, and never log it.

1291If you claim work with the SDK's `work.poller()` (go: `environments.NewWorkPoller()`) instead, pass each claimed item's `secret` into the sandbox you launch in the same way. Pass it only into the sandbox that serves that session, and never log it.

12921292

12931293The sandbox image also needs a writable `/mnt/memory` (see [Prepare the host](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes#prepare-the-host)). Because each sandbox serves one session and is discarded afterward, no leftover directories need cleanup, and the memory directories do not need to be bind-mounted to the host: the worker uploads their contents to the store before the sandbox exits. If you stop a container before its session ends, send a signal that the entrypoint turns into cancellation (see [Prepare the host](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes#prepare-the-host)) rather than killing it, so that upload still runs. Give the container time to finish the upload as well: Docker follows the stop signal with SIGKILL after 10 seconds by default, so raise that limit to at least the 30 seconds that Prepare the host calls for, with `--stop-timeout` on `docker run` or your orchestrator's termination grace period.

12941294

from line 1296

12961296

12971297Two `EnvironmentWorker` options control memory behavior:

12981298

1299* **`memory_sync_interval`** (Python, in seconds; `memorySyncIntervalMs` in TypeScript, in milliseconds; `MemorySyncInterval` in Go, a duration): how often attached stores reconcile with the server while the session runs. Defaults to 15 seconds; the minimum is 5 seconds. A shorter interval narrows the window in which another session sees stale memories, at the cost of more memory store requests. `None` in Python, `null` in TypeScript, or a negative duration in Go disables memory support entirely: the worker neither downloads nor syncs stores, and a session with memory stores attached runs without them even though its system prompt still describes them, so disable memory support only on workers whose sessions attach no memory stores. While memory support is enabled, a work item that arrives without a per-session `secret` for a session with attached stores fails rather than running without memory (see [Troubleshoot memory mounts](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes#troubleshoot-memory-mounts)).

1300* **`memory_sync_deletions`** (`memorySyncDeletions` in TypeScript, `MemorySyncDeletions` in Go): whether a file the agent deletes locally is also deleted from the store. The value is one of `"enabled"` (the default), `"log_only"`, or `"disabled"` in Python and TypeScript, and one of the constants `environments.MemorySyncDeletionsEnabled` (the zero value), `environments.MemorySyncDeletionsLogOnly`, or `environments.MemorySyncDeletionsDisabled` in Go. When enabled, the worker deletes the memory from the store once a later sync confirms the file is still gone; in log-only mode it runs the same checks but only logs what it would have deleted, which lets you watch what your workers would delete before you trust the enabled mode; when disabled, it never deletes from the store. Uploads and downloads are unaffected by this setting.

1299* **`memory_sync_interval` (typescript: `memorySyncIntervalMs`; go: `MemorySyncInterval`)** (in seconds in Python, in milliseconds in TypeScript, a duration in Go): how often attached stores reconcile with the server while the session runs. Defaults to 15 seconds; the minimum is 5 seconds. A shorter interval narrows the window in which another session sees stale memories, at the cost of more memory store requests. `None` in Python, `null` in TypeScript, or a negative duration in Go disables memory support entirely: the worker neither downloads nor syncs stores, and a session with memory stores attached runs without them even though its system prompt still describes them, so disable memory support only on workers whose sessions attach no memory stores. While memory support is enabled, a work item that arrives without a per-session `secret` for a session with attached stores fails rather than running without memory (see [Troubleshoot memory mounts](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes#troubleshoot-memory-mounts)).

1300* **`memory_sync_deletions` (typescript: `memorySyncDeletions`; go: `MemorySyncDeletions`)**: whether a file the agent deletes locally is also deleted from the store. The value is one of `"enabled"` (the default), `"log_only"`, or `"disabled"` in Python and TypeScript, and one of the constants `environments.MemorySyncDeletionsEnabled` (the zero value), `environments.MemorySyncDeletionsLogOnly`, or `environments.MemorySyncDeletionsDisabled` in Go. When enabled, the worker deletes the memory from the store once a later sync confirms the file is still gone; in log-only mode it runs the same checks but only logs what it would have deleted, which lets you watch what your workers would delete before you trust the enabled mode; when disabled, it never deletes from the store. Uploads and downloads are unaffected by this setting.

13011301

13021302Set these options where you construct the worker, whether through the `EnvironmentWorker` constructor or, in Python and TypeScript, the `client.beta.environments.work.worker()` factory that the webhook handler uses.

13031303

from line 1375

13751375[Custom tools](https://platform.claude.com/docs/en/managed-agents/tools#custom-tools) are tools your own code executes: the agent emits an `agent.custom_tool_use` event and waits for a matching `user.custom_tool_result`. The worker can be that code, and because it runs inside your sandbox, the tool reaches the internal services, credentials, and network egress you configured for the sandbox, and nothing more. The environment key authorizes posting custom tool results, so your Claude API key stays off the worker host.

13761376

13771377<Note>

1378 Serving custom tools requires the SDK worker: the `ant` CLI worker has no way to register a custom tool implementation. In the sandbox-per-session pattern, run `EnvironmentWorker` inside the sandbox with `handle_item()` (`handleItem` in TypeScript, `HandleItem` in Go) in place of `ant beta:worker run`.

1378 Serving custom tools requires the SDK worker: the `ant` CLI worker has no way to register a custom tool implementation. In the sandbox-per-session pattern, run `EnvironmentWorker` inside the sandbox with `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`) in place of `ant beta:worker run`.

13791379</Note>

13801380

13811381<Steps>

from line 1399

13991399 </Step>

14001400

14011401 <Step title="Register the implementation with the worker">

1402 Pass the tool through the worker's `tools` factory (see [SDK helpers](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes#sdk-helpers)), alongside the built-in toolset:

1402 Pass the tool through the worker's `tools` (go: `ToolsFunc`) factory (see [SDK helpers](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes#sdk-helpers)), alongside the built-in toolset:

14031403

14041404 <CodeGroup exclude="shell">

14051405 ```python Python

from line 1562

156215622. The worker, inside your sandbox, forwards the call over its open MCP session to the server on your network.

156315633. The worker posts the server's response as the `user.custom_tool_result`.

15641564

1565The SDKs' [Client-side MCP helpers](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector#client-side-mcp-helpers) convert the server's tools into the runnable tools the worker accepts; install an MCP SDK alongside the Anthropic SDK (`pip install "anthropic[mcp]" "mcp>=1.24"`, `npm install @modelcontextprotocol/sdk`, `go get github.com/modelcontextprotocol/go-sdk`). The examples connect without authentication; to send credentials, configure the HTTP client or request options you hand to the MCP transport (`http_client` in Python, `requestInit` in TypeScript, `HTTPClient` in Go).

1565The SDKs' [Client-side MCP helpers](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector#client-side-mcp-helpers) convert the server's tools into the runnable tools the worker accepts; install an MCP SDK alongside the Anthropic SDK (`pip install "anthropic[mcp]" "mcp>=1.24"`, `npm install @modelcontextprotocol/sdk`, `go get github.com/modelcontextprotocol/go-sdk`). The examples connect without authentication; to send credentials, configure the HTTP client or request options you hand to the MCP transport (`http_client` (typescript: `requestInit`; go: `HTTPClient`)).

15661566

15671567<Steps>

15681568 <Step title="Declare the server's tools on the agent">

from line 1781

17811781 </Step>

17821782

17831783 <Step title="Serve the tools from the worker">

1784 Connect to the same MCP server at startup, convert its tools with the MCP helpers, and register them alongside the built-in toolset. Keep one MCP session open for the life of the worker.

1784 Connect to the same MCP server at startup, convert its tools with `async_mcp_tool` (python; typescript: `mcpTools`; go: `mcp.NewBetaTools`), and register them alongside `beta_agent_toolset_20260401` (python; typescript: `betaAgentToolset20260401`; go: `agenttoolset.BetaAgentToolset20260401`). Keep one MCP session open for the life of the worker.

17851785

17861786 <CodeGroup exclude="shell">

17871787 ```python Python

release-notes/overview Changed · +13 / -0 lines

### September 24, 2026 ### September 23, 2026 ### September 9, 2026

from line 12

1212 For updates to Claude Code, see the [complete CHANGELOG.md](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md) in the `claude-code` repository.

1313</Tip>

1414

15### September 24, 2026

16

17* We're expanding which refusals are billed to include refusals that arrive before any output when `stop_details.category` is `"bio"`, `"frontier_llm"`, or `"reasoning_extraction"`, the categories where we measure low volumes of false positives. Mid-stream refusals were already billed. The newly billed refusals are charged like any other request, at the rates of the model that ran it. Refusals before any output in other categories are still not billed, and fallback credit is unchanged. This change applies on all platforms. See [How refusals are billed](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#how-refusals-are-billed).

18

19### September 23, 2026

20

21* [Cache diagnostics](https://platform.claude.com/docs/en/build-with-claude/cache-diagnostics) is out of beta on the Claude API and no longer requires the `cache-diagnosis-2026-04-07` beta header. Include the `diagnostics` object on a Messages request to opt in; requests that still send the header work as before. Responses from `POST /v1/messages` now always include the `diagnostics` field, which is `null` when the request did not include the `diagnostics` object.

22

1523### September 22, 2026

1624

1725* We've launched **Claude Opus 5.5** (`claude-opus-5-5`), a model for long-running agentic coding and knowledge work. It has a [1M token context window](https://platform.claude.com/docs/en/build-with-claude/context-windows) by default, 128k max output tokens, and always-on [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking), at $4 / $20 USD per MTok (Claude Opus 5 is $5 / $25). Claude Opus 5.5 is available on the Claude API, [Claude in Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), [Claude on Google Cloud](https://platform.claude.com/docs/en/build-with-claude/claude-on-vertex-ai), and [Claude in Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry). See [What's new in Claude Opus 5.5](https://platform.claude.com/docs/en/models/opus-5-5/whats-new-opus-5-5) for capabilities, API changes, and migration guidance.

from line 29

2129

2230### September 18, 2026

2331

32* For [cache diagnostics](https://platform.claude.com/docs/en/build-with-claude/cache-diagnostics), a response to a request that sends the `cache-diagnosis-2026-04-07` beta header now always includes the `diagnostics` field. The field is `null` when the request did not include the `diagnostics` object. Previously the field was omitted in that case.

2433* The [Compliance API](https://platform.claude.com/docs/en/manage-claude/compliance-api) local session endpoints now also return transcripts of Claude in Chrome sessions (`product_surface` value `claude_in_chrome`), in beta for Claude Enterprise organizations, with your existing Compliance Access Key and the `read:compliance_user_data` scope. See [Sessions on users' machines](https://platform.claude.com/docs/en/manage-claude/compliance-sessions#retrieve-local-sessions).

2534

2635### September 14, 2026

from line 41

3241

3342* Claude Managed Agents permission policies now include `auto`: the server evaluates each agent or MCP tool call and runs it, denies it, or pauses for your approval. `agent.tool_use` and `agent.mcp_tool_use` events report how each call was evaluated in an `evaluation` field alongside `evaluated_permission`. See [Let the server evaluate each call with `auto`](https://platform.claude.com/docs/en/managed-agents/permission-policies#let-the-server-evaluate-each-call-with-auto).

3443* Version 1.32.0 of the `ant` CLI adds `ant beta:sessions connect`, which attaches your terminal to a Claude Managed Agents session. You can follow the session live, send messages, and allow or deny tool calls that are waiting for approval. Pass `--web` to serve the Claude Console's session viewer locally and open the session there instead. See [Connect to a Managed Agents session from your terminal](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/sessions-connect).

44

45### September 9, 2026

46

47* For [cache diagnostics](https://platform.claude.com/docs/en/build-with-claude/cache-diagnostics), the API now stores a request's fingerprint only when the request includes the `diagnostics` object. A request that sends only the `cache-diagnosis-2026-04-07` beta header is still accepted, but no fingerprint is stored. A later turn that points `previous_message_id` at it reports `previous_message_not_found`. Include `diagnostics` on every turn, with `"previous_message_id": null` on the first.

3548

3649### September 3, 2026

3750

agents-and-tools/mcp-connector Changed · +1 / -1 lines

from line 1950

19501950

19511951### Error handling

19521952

1953The conversion functions throw `UnsupportedMCPValueError` if an MCP value isn't supported by the Claude API (in Go, the helpers return an `UnsupportedValueError`; in Java and C#, they throw `AnthropicInvalidDataException`). This can happen with unsupported content types, MIME types, or resource links (resolve resource links with your MCP client before converting).

1953The conversion functions fail with `UnsupportedMCPValueError` (go: `UnsupportedValueError`; java, csharp: `AnthropicInvalidDataException`) if an MCP value isn't supported by the Claude API (thrown, or in Go returned as an error). This can happen with unsupported content types, MIME types, or resource links (resolve resource links with your MCP client before converting).

19541954

19551955## Batch requests

19561956

agents-and-tools/tool-use/build-a-tool-using-agent Changed · +1 / -1 lines

from line 4015

40154015

40164016## Ring 5: The Tool Runner SDK abstraction

40174017

4018Rings 2 through 4 wrote the same loop by hand: call the API, check `stop_reason`, run tools, append results, repeat. The Tool Runner does this for you. Define each tool as a function, pass the list to `tool_runner`, and retrieve the final message once the loop completes. Error wrapping, result formatting, and conversation management are handled internally.

4018Rings 2 through 4 wrote the same loop by hand: call the API, check `stop_reason`, run tools, append results, repeat. The Tool Runner does this for you. Define each tool as a function, pass the list to `client.beta.messages.tool_runner()` (typescript: `client.beta.messages.toolRunner()`; java: `client.beta().messages().toolRunner()`; php: `$client->beta->messages->toolRunner()`; csharp: `client.Beta.Messages.ToolRunner()`; go: `client.Beta.Messages.NewToolRunner()`), and retrieve the final message once the loop completes. Error wrapping, result formatting, and conversation management are handled internally.

40194019

40204020Each SDK provides a helper that turns an ordinary function into a runnable tool and derives the input schema from its signature; the tabs below show the idiomatic form for each language.

40214021

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

from line 1525

15251525

15261526## Data retention

15271527

1528Code execution runs in server-side sandbox containers. Container data, including execution artifacts, uploaded files, and outputs, is retained for up to 30 days. This retention applies to all data processed within the container environment. Files that code execution creates in the [Files API](https://platform.claude.com/docs/en/build-with-claude/files) (retrievable with `client.files.download()`) persist until explicitly deleted.

1528Code execution runs in server-side sandbox containers. Container data, including execution artifacts, uploaded files, and outputs, is retained for up to 30 days. This retention applies to all data processed within the container environment. Files that code execution creates in the [Files API](https://platform.claude.com/docs/en/build-with-claude/files) (retrievable with `client.files.download()` (csharp, go: `client.Files.Download()`; java: `client.files().download()`; php: `$client->files->download()`)) persist until explicitly deleted.

15291529

15301530For ZDR eligibility across all features, see [API and data retention](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention).

15311531

One read of Claude Developer Platformapi-20260924T173729Z

What this read moved

api/compliance/apps/sessions/local/messages Changed · +8 / -1 lines

api/compliance/apps/sessions/local/messages/list Changed · +8 / -1 lines

api/compliance/organizations/settings Changed · +6 / -2 lines

api/errors Changed · +3 / -3 lines

api/messages Changed · +529 / -0 lines

api/messages/batches Changed · +255 / -0 lines

api/messages/batches/create Changed · +11 / -0 lines

api/messages/batches/results Changed · +61 / -0 lines

api/messages/create Changed · +78 / -0 lines

api/models Changed · +16 / -12 lines

api/models/list Changed · +8 / -6 lines

api/models/retrieve Changed · +8 / -6 lines

build-with-claude/cache-diagnostics Changed · +16 / -54 lines

build-with-claude/claude-platform-on-aws Changed · +15 / -15 lines

build-with-claude/fast-mode Changed · +3 / -3 lines

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

build-with-claude/refusals-and-fallback Changed · +19 / -11 lines

manage-claude/inference-hooks Changed · +14 / -1 lines

manage-claude/wif-providers/azure Changed · +4 / -4 lines

managed-agents/migration Changed · +10 / -10 lines

managed-agents/self-hosted-sandboxes Changed · +27 / -27 lines

release-notes/overview Changed · +13 / -0 lines

agents-and-tools/mcp-connector Changed · +1 / -1 lines

agents-and-tools/tool-use/build-a-tool-using-agent Changed · +1 / -1 lines

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