Home Docs Claude Developer Platform

One capture · api

One read of Claude Developer Platformapi-20261021T193714Z

242 pages moved out of 808 read.

Pages moved 242 significant first

Pages read 808 in this capture

Captured 21 Oct 2026 19:37 UTC

Corpus hash 851c97e9b6f0 corpus-hash

What this read moved

51-75 of 242, page 3 of 10

This capture is too large to show at once. Changes 51-75 of 242 are below, significant first; the rest are on the following screens.

api/errors Changed · +15 / -15 lines

from line 31

3131* 529 - `overloaded_error`: The API is temporarily overloaded.

3232

3333 <Warning>

34 529 errors can occur when the API experiences high traffic across all users.

34 A 529 error can occur when the API experiences high traffic across all users.

3535

36 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.

36 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, increase your traffic gradually and maintain consistent usage patterns.

3737 </Warning>

3838

3939The official SDK automatically retries 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.

from line 260

260260

261261Avoid setting a large `max_tokens` value without using the [streaming Messages API](https://platform.claude.com/docs/en/build-with-claude/streaming) or [Message Batches API](https://platform.claude.com/docs/en/api/messages/batches/create):

262262

263* Some networks may drop idle connections after a variable period of time, which can cause the request to fail or time out without receiving a response from Anthropic.

263* Some networks might drop idle connections after a variable period of time, which can cause the request to fail or time out without receiving a response from Anthropic.

264264* Networks differ in reliability. The [Message Batches API](https://platform.claude.com/docs/en/api/messages/batches/create) can help you manage the risk of network issues by allowing you to poll for results rather than requiring an uninterrupted network connection.

265265

266266If you are building a direct API integration, setting a [TCP socket keep-alive](https://tldp.org/HOWTO/TCP-Keepalive-HOWTO/programming.html) can reduce the impact of idle connection timeouts on some networks.

267267

268The [SDKs](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) validate that your non-streaming Messages API requests are not expected to exceed a 10-minute timeout. They also set a socket option for TCP keep-alive.

268The [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) validates that your non-streaming Messages API requests are not expected to exceed a 10-minute timeout. It also sets a socket option for TCP keep-alive.

269269

270270If you don't need to process events incrementally, the SDK can consume the stream for you and return the complete `Message` object, identical to what a non-streaming call returns:

271271

from line 422

422422 ```

423423</CodeGroup>

424424

425See [Streaming Messages](https://platform.claude.com/docs/en/build-with-claude/streaming#get-the-final-message-without-handling-events) for more details.

425See [Streaming messages](https://platform.claude.com/docs/en/build-with-claude/streaming#get-the-final-message-without-handling-events) for more details.

426426

427427## Common validation errors

428428

from line 450

450450`thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified. These blocks must remain as they were in the original response.

451451```

452452

453With tool use, every `thinking` and `redacted_thinking` block from the assistant turn must be passed back exactly as received, including blocks whose `thinking` field is empty. Pass thinking blocks back unchanged, and if your application filters content blocks by type before resending, include both `thinking` and `redacted_thinking`. See [Troubleshooting thinking](https://platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting#error-thinking-blocks-modified), [Preserving thinking blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#preserving-thinking-blocks), and [Preserved thinking](https://platform.claude.com/docs/en/build-with-claude/thinking#preserved-thinking).

453With tool use, every `thinking` and `redacted_thinking` block from the assistant turn must be passed back exactly as received, including blocks whose `thinking` field is empty. Pass thinking blocks back unchanged, and if your application filters content blocks by type before resending, include both `thinking` and `redacted_thinking`. See the [fix for modified thinking blocks](https://platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting#error-thinking-blocks-modified) in Troubleshooting thinking, and also [Preserving thinking blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#preserving-thinking-blocks) and [Preserved thinking](https://platform.claude.com/docs/en/build-with-claude/thinking#preserved-thinking).

454454

455455### Extended thinking not supported

456456

from line 460

460460"thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

461461```

462462

463Use [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking) instead. [Migrating to adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#migrating-to-adaptive-thinking) shows the parameter mapping, and [Troubleshooting thinking](https://platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting#error-thinking-type-enabled) covers the symptom-first fix.

463Use [adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/thinking) instead. [Migrating to adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#migrating-to-adaptive-thinking) shows the parameter mapping, and Troubleshooting thinking covers the [symptom-first fix for the extended thinking error](https://platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting#error-thinking-type-enabled).

464464

465465### Adaptive thinking not supported

466466

from line 470

470470adaptive thinking is not supported on this model

471471```

472472

473Use `thinking: {"type": "enabled", "budget_tokens": N}` on these models; see [Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for the configuration and [Troubleshooting thinking](https://platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting#error-thinking-type-adaptive) for the symptom-first fix.

473Use `thinking: {"type": "enabled", "budget_tokens": N}` on these models; see [Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for the configuration and the [symptom-first fix for the adaptive thinking error](https://platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting#error-thinking-type-adaptive) in Troubleshooting thinking.

474474

475475### Thinking cannot be disabled

476476

from line 506

506506

507507Claude Haiku 5.5 accepts `thinking: {"type": "disabled"}` and holds it to the same two effort limits that apply to `between_tools`: at `xhigh` or `max` effort, or with a per-message `output_config.effort` that differs from the level in effect, the request returns a 400 `invalid_request_error` with the matching message shown earlier.

508508

509In both messages, "enable thinking" means adaptive thinking: omit the `thinking` field or send `thinking: {"type": "adaptive"}`. Claude Sonnet 5.5 and Claude Haiku 5.5 reject `"enabled"` with a 400 error. To vary effort per turn, use adaptive thinking.

510510

511511Sending `thinking: {"type": "between_tools"}` to any model other than Claude Sonnet 5.5 returns a 400 `invalid_request_error`:

512512

from line 514

514514"thinking.type.between_tools" is not supported for this model.

515515```

516516

517For the fixes, see [Troubleshooting thinking](https://platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting#error-thinking-type-between-tools), which covers the `between_tools` and effort errors.

517For the fixes, see the [`between_tools` and effort errors](https://platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting#error-thinking-type-between-tools) in Troubleshooting thinking.

518518

519Omit the `thinking` parameter and the request runs with adaptive thinking. To keep thinking content out of responses without turning thinking off, set `display: "omitted"` on the thinking configuration. See [Troubleshooting thinking](https://platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting#error-thinking-type-disabled).

519Omit the `thinking` parameter and the request runs with adaptive thinking. To keep thinking content out of responses without turning thinking off, set `display: "omitted"` on the thinking configuration. See the [fix for the disabled thinking error](https://platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting#error-thinking-type-disabled) in Troubleshooting thinking.

520520

521521### Forced tool use not supported

522522

from line 546

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

547547```

548548

549Without the `thinking-binding-controls-2026-08-01` beta header the message also names that header. Keep the conversation history append-only, or send the beta header with `prefix_mismatch_behavior: "drop_block"` to drop the block and continue. On Claude Sonnet 5.5 and Claude Haiku 5.5, `block_binding` works only with `thinking: {"type": "adaptive"}`. With `between_tools` on Claude Sonnet 5.5, or `thinking: {"type": "disabled"}` on Claude Haiku 5.5, keep the history append-only, or strip the thinking blocks from the edited turn on. A block from a model the target model can't read is dropped rather than rejected. See [Keeping the prefix unchanged](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#prefix-check) and [Troubleshooting thinking](https://platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting#error-thinking-block-signature).

549Without the `thinking-binding-controls-2026-08-01` beta header, the message also names that header. Keep the conversation history append-only, or send the beta header with `prefix_mismatch_behavior: "drop_block"` to drop the block and continue. On Claude Sonnet 5.5 and Claude Haiku 5.5, `block_binding` works only with `thinking: {"type": "adaptive"}`. With `between_tools` on Claude Sonnet 5.5, or `thinking: {"type": "disabled"}` on Claude Haiku 5.5, keep the history append-only, or strip the thinking blocks from the edited turn on. A block from a model the target model can't read is dropped rather than rejected. See [Keeping the prefix unchanged](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#prefix-check) and the [fix for an invalid thinking block signature](https://platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting#error-thinking-block-signature) in Troubleshooting thinking.

550550

551551Sending `thinking.block_binding` without the `thinking-binding-controls-2026-08-01` [beta header](https://platform.claude.com/docs/en/api/beta-headers) returns a 400 `invalid_request_error` whose message ends in:

552552

from line 558

558558

559559### Outbound web identity federation disabled (Claude Platform on AWS)

560560

561If every request to [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws) returns `"Outbound web identity federation is disabled for your account"`, run `aws iam enable-outbound-web-identity-federation` once per AWS account. See [Enable outbound web identity federation](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#enable-outbound-web-identity-federation) for details.

561If every request to [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws) returns `"Outbound web identity federation is disabled for your account"`, run `aws iam enable-outbound-web-identity-federation` once for each AWS account. See [Enable outbound web identity federation](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#enable-outbound-web-identity-federation) for details.

562562

563563## Next steps

564564

api/opentelemetry/spans Changed · +14 / -14 lines

from line 71

7171

7272### Content attributes

7373

74Attributes tagged with <Badge>Content</Badge> are only on spans in content mode, from the SDK and the API alike. See [how the content modes differ in the guide](https://platform.claude.com/docs/en/manage-claude/opentelemetry#choose-a-content-mode). When this content is too large, the SDK and the API [shorten it](https://platform.claude.com/docs/en/manage-claude/opentelemetry#content-limits) and set `anthropic.content.truncated` to `true`. If Anthropic's safeguards withhold content from a response, the API's spans don't include that content either.

74Attributes tagged with <Badge>Content</Badge> are only on spans in content mode, from the SDK and the API alike. See [how the content modes differ in the guide](https://platform.claude.com/docs/en/manage-claude/opentelemetry#choose-a-content-mode). When this content is too large, the SDK and the API shorten it to fit the [content limits](https://platform.claude.com/docs/en/manage-claude/opentelemetry#content-limits) and set `anthropic.content.truncated` to `true`. If Anthropic's safeguards withhold content from a response, the API's spans don't include that content either.

7575

7676The message attributes are JSON strings in the message format of the OpenTelemetry GenAI conventions. Each Anthropic content block becomes one GenAI conventions message part, on the Messages API and in Managed Agents message events such as `agent.message`:

7777

from line 207

207207

208208 * The [`anthropic.sessions.create`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-sessions-create) span, for the first turn of a session that was created with non-empty [`initial_events`](https://platform.claude.com/docs/en/api/beta/sessions/create#create.initial_events).

209209 * The [`anthropic.sessions.events.send`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-sessions-events-send) span for the request in which the event was sent, for a turn that started because of an event, for example a [`user.message`](https://platform.claude.com/docs/en/api/beta/sessions/events#beta_managed_agents_user_message_event) event.

210 * The [`anthropic.sessions.update`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-sessions-update) span, for a turn that resumes because the session budget was raised or removed through the request.

211211 * The `anthropic.session.turn` span for the turn of [the agent that the session runs](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration) during which that agent started this turn, for a turn on another thread.

212212 * The `anthropic.session.turn` span for the turn that produced the reply, for a turn that starts because an agent on another thread replied, such as an agent that the primary agent called.

213213 * None, for any other turn, such as a turn that starts because a [workflow run](https://platform.claude.com/docs/en/managed-agents/workflow-runs) ended.

from line 439

439439

440440Every SDK span for a request, including [`anthropic.messages.create`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-messages-create), [`anthropic.messages.count_tokens`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-messages-count-tokens), and [`anthropic.messages.batches.<method>`](https://platform.claude.com/docs/en/api/opentelemetry/spans#anthropic-messages-batches-method), has the following attributes:

441441

442| Attribute | Type | Description |

443| --------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

444| `gen_ai.conversation.id` | `string` | The conversation ID passed with the [`conversation_id` (typescript, java, php: `conversationId`; csharp: `ConversationId`; go: `option.WithOpenTelemetryConversationID()`) option](https://platform.claude.com/docs/en/manage-claude/opentelemetry/sdk#configure-the-sdk). Without one, the session thread ID on the Managed Agents requests that [Session attributes](https://platform.claude.com/docs/en/api/opentelemetry/spans#session-attributes) lists, and absent on other requests. |

445| `anthropic.<resource>.id` | `string` | One attribute for each ID in the request's path and one for the ID of an object that the method creates. The name comes from the path, in the singular, for example `anthropic.session.id` or `anthropic.session.thread.id`. |

446| `gen_ai.agent.id` | `string` | The agent ID, on the agent methods. |

447| `gen_ai.memory.store.id` | `string` | The memory store ID, on the memory store methods. |

448| `gen_ai.memory.record.id` | `string` | The memory ID, on the memory methods. |

449| `http.request.resend_count` | `int` | The number of times that the SDK resent the request, for any reason, such as a retry. Absent when the SDK didn't resend it. |

450| `error.type` | `string` | A failed call's [error type](https://platform.claude.com/docs/en/api/errors#http-errors), for example `rate_limit_error`. The HTTP status code, for example `502`, when the error response doesn't have an error type. `connection_error`, `client_timeout_error`, or `client_error` when the call failed in the SDK. `api_error` when the server ended a stream early. |

451| `server.address` | `string` | The host of the client's base URL, `api.anthropic.com` by default. On a cloud platform's client, that platform's host. |

452| `url.query` | `string` | The URL's query string, with only the query parameters that the endpoint defines. Absent when there are none. In metadata-only mode, absent when the query has a sensitive parameter, such as `email`. |

453| `url.full` | `string` | The URL, made of `url.scheme`, `server.address`, the port when the base URL has one, `url.path`, and `url.query`. In metadata-only mode, absent whenever that mode leaves out `url.query`. |

442| Attribute | Type | Description |

444| `gen_ai.conversation.id` | `string` | The conversation ID passed with the [`conversation_id` (typescript, java, php: `conversationId`; csharp: `ConversationId`; go: `option.WithOpenTelemetryConversationID()`) option](https://platform.claude.com/docs/en/manage-claude/opentelemetry/sdk#configure-the-sdk). Without one, the session thread ID on requests to one session thread, and on the request in which the session tool runner sends a tool's result. Absent on other requests. |

446| `gen_ai.agent.id` | `string` | The agent ID, on the agent methods. |

447| `gen_ai.memory.store.id` | `string` | The memory store ID, on the memory store methods. |

448| `gen_ai.memory.record.id` | `string` | The memory ID, on the memory methods. |

449| `http.request.resend_count` | `int` | The number of times that the SDK resent the request, for any reason, such as a retry. Absent when the SDK didn't resend it. |

451| `server.address` | `string` | The host of the client's base URL, `api.anthropic.com` by default. On a cloud platform's client, that platform's host. |

454454

api/overview Changed · +29 / -29 lines

## Claude API versus cloud platforms ## Claude API vs cloud platforms

from line 23

2323

2424The Claude API includes the following APIs:

2525

26* **[Messages API](https://platform.claude.com/docs/en/api/messages/create)**: Send messages to Claude for conversational interactions (`POST /v1/messages`)

27* **[Message Batches API](https://platform.claude.com/docs/en/api/messages/batches/create)**: Process large volumes of Messages requests asynchronously with 50% cost reduction (`POST /v1/messages/batches`)

28* **[Token Counting API](https://platform.claude.com/docs/en/api/messages/count_tokens)**: Count tokens in a message before sending to manage costs and rate limits (`POST /v1/messages/count_tokens`)

29* **[Models API](https://platform.claude.com/docs/en/api/models/list)**: List available Claude models and their details (`GET /v1/models`)

30* **[Files API](https://platform.claude.com/docs/en/api/files/upload)**: Upload and manage files for use across multiple API calls (`POST /v1/files`, `GET /v1/files`)

31* **[Skills API](https://platform.claude.com/docs/en/api/skills/create)**: Create and manage custom agent skills (`POST /v1/skills`, `GET /v1/skills`)

26* **[Messages API](https://platform.claude.com/docs/en/api/messages/create):** Send messages to Claude for conversational interactions (`POST /v1/messages`)

27* **[Message Batches API](https://platform.claude.com/docs/en/api/messages/batches/create):** Process large volumes of Messages requests asynchronously with a 50 percent cost reduction (`POST /v1/messages/batches`)

28* **[Token Counting API](https://platform.claude.com/docs/en/api/messages/count_tokens):** Count tokens in a message before sending to manage costs and rate limits (`POST /v1/messages/count_tokens`)

29* **[Models API](https://platform.claude.com/docs/en/api/models/list):** List available Claude models and their details (`GET /v1/models`)

30* **[Files API](https://platform.claude.com/docs/en/api/files/upload):** Upload and manage files for use across multiple API calls (`POST /v1/files`, `GET /v1/files`)

31* **[Skills API](https://platform.claude.com/docs/en/api/skills/create):** Create and manage custom agent skills (`POST /v1/skills`, `GET /v1/skills`)

3232

3333The following APIs are in beta:

3434

35* **[Agents API](https://platform.claude.com/docs/en/managed-agents/agent-setup)**: Define reusable, versioned agent configurations for Claude Managed Agents (`POST /v1/agents`, `GET /v1/agents`)

36* **[Sessions API](https://platform.claude.com/docs/en/managed-agents/sessions)**: Run stateful agent sessions in managed cloud sandboxes (`POST /v1/sessions`, `GET /v1/sessions/{id}/events/stream`)

37* **[Environments API](https://platform.claude.com/docs/en/managed-agents/environments)**: Configure sandbox templates for agent sessions (`POST /v1/environments`, `GET /v1/environments`)

35* **[Agents API](https://platform.claude.com/docs/en/managed-agents/agent-setup):** Define reusable, versioned agent configurations for Claude Managed Agents (`POST /v1/agents`, `GET /v1/agents`)

36* **[Sessions API](https://platform.claude.com/docs/en/managed-agents/sessions):** Run stateful agent sessions in managed cloud sandboxes (`POST /v1/sessions`, `GET /v1/sessions/{id}/events/stream`)

37* **[Environments API](https://platform.claude.com/docs/en/managed-agents/environments):** Configure sandbox templates for agent sessions (`POST /v1/environments`, `GET /v1/environments`)

3838

3939For the complete API reference with all endpoints, parameters, and response schemas, explore the API reference pages listed in the navigation. To access beta features, see [Beta headers](https://platform.claude.com/docs/en/api/beta-headers).

4040

from line 42

4242

4343For details on each authentication method and when to use it, see [Authentication](https://platform.claude.com/docs/en/manage-claude/authentication). Requests to the Claude API include these headers:

4444

45| Header | Value | Required |

46| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

47| `Authorization` | `Bearer <token>`, where `<token>` is your API key or a short-lived access token obtained from `POST /v1/oauth/token` through [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) | Yes, unless `x-api-key` is set |

48| `x-api-key` | Your API key from Console. Legacy fallback for `Authorization`, still supported | No |

49| `anthropic-workspace-id` | ID of the [workspace](https://platform.claude.com/docs/en/manage-claude/workspaces) the request runs in (for example, `wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ`). See [Select a workspace](https://platform.claude.com/docs/en/manage-claude/authentication#select-a-workspace). | Required with a multi-workspace API key. Optional for other API keys. A key created for a single workspace runs in that workspace when you omit the header. Not used with Workload Identity Federation tokens, which select a workspace at token exchange. |

50| `anthropic-version` | API version (for example, `2026-10-21`) | Yes |

51| `content-type` | `application/json` | Yes |

45| Header | Value | Required |

48| `x-api-key` | Your API key from Console. Legacy fallback for `Authorization`, still supported | No |

49| `anthropic-workspace-id` | ID of the [workspace](https://platform.claude.com/docs/en/manage-claude/workspaces) the request runs in (for example, `wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ`). See [Select a workspace](https://platform.claude.com/docs/en/manage-claude/authentication#select-a-workspace). | Required with an API key that isn't scoped to a workspace. Optional for other API keys. A key created for a single workspace runs in that workspace when you omit the header. Not used with Workload Identity Federation tokens, which select a workspace at token exchange. |

50| `anthropic-version` | API version (for example, `2026-10-21`) | Yes |

51| `content-type` | `application/json` | Yes |

5252

5353If you are using the [Client SDKs](https://platform.claude.com/docs/en/api/overview#client-sdks), the SDK sends the authentication, version, and content-type headers automatically; you pass `anthropic-workspace-id` yourself when your key needs it. For API versioning details, see [API versions](https://platform.claude.com/docs/en/api/versioning).

5454

from line 70

7070* Streaming support

7171* Request timeouts and connection management

7272

73For a list of client SDKs, see [Client SDKs](https://platform.claude.com/docs/en/cli-sdks-libraries/overview).

73For a list of client SDKs, see [SDKs, CLI, and libraries](https://platform.claude.com/docs/en/cli-sdks-libraries/overview).

7474

75## Claude API vs cloud platforms

75## Claude API versus cloud platforms

7676

7777Claude is available through the direct Claude API and through cloud platforms. Choose based on your infrastructure, feature availability, compliance requirements, and pricing preferences.

7878

from line 105

105105

106106### Request size limits

107107

108| Endpoint | Maximum request size |

109| --------------------------------------------------------------------------------------------- | -------------------- |

110| Messages, Token Counting | 32 MB |

111| [Message Batches API](https://platform.claude.com/docs/en/build-with-claude/batch-processing) | 256 MB |

112| [Files API](https://platform.claude.com/docs/en/build-with-claude/files) | 500 MB |

113| Sessions, Agents, Environments | 32 MB |

108| Endpoint | Maximum request size |

109| -------------------------------------------------------------------------------------------------------------------- | -------------------- |

110| Messages, Token Counting | 32 MB |

111| Message Batches API (see [Batch processing](https://platform.claude.com/docs/en/build-with-claude/batch-processing)) | 256 MB |

112| [Files API](https://platform.claude.com/docs/en/build-with-claude/files) | 500 MB |

113| Sessions, Agents, Environments | 32 MB |

114114

115115If you exceed these limits, you'll receive a 413 `request_too_large` error.

116116

from line 148

148148

149149To go back a page, pass `prev_page` as the `page` parameter. `prev_page` is `null` when you're on the first page. Not all list endpoints support `prev_page`. Only `GET /v1/sessions` returns `prev_page`; on list endpoints that do not support backward pagination, the field is absent from the response rather than `null`. For a request walkthrough, see [Listing sessions](https://platform.claude.com/docs/en/managed-agents/session-operations#listing-sessions).

150150

151The SDK provides an auto-paginating iterator that follows `next_page` for you. For example, `for session in client.beta.sessions.list()` (typescript: `for await (const session of client.beta.sessions.list())`; go: `client.Beta.Sessions.ListAutoPaging()`; java: `client.beta().sessions().list().autoPager()`; csharp: `(await client.Beta.Sessions.List()).Paginate()`; php: `$client->beta->sessions->list()->pagingEachItem()`; ruby: `client.beta.sessions.list.auto_paging_each`) walks through every session. SDK auto-pagination is forward-only; to go back a page, read `prev_page` from the response and pass it back as the `page` parameter yourself. See [client SDKs](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) for details.

151The SDK provides an auto-paginating iterator that follows `next_page` for you. For example, `for session in client.beta.sessions.list()` (typescript: `for await (const session of client.beta.sessions.list())`; go: `client.Beta.Sessions.ListAutoPaging()`; java: `client.beta().sessions().list().autoPager()`; csharp: `(await client.Beta.Sessions.List()).Paginate()`; php: `$client->beta->sessions->list()->pagingEachItem()`; ruby: `client.beta.sessions.list.auto_paging_each`) walks through every session. SDK auto-pagination is forward-only; to go back a page, read `prev_page` from the response and pass it back as the `page` parameter yourself. See [SDKs, CLI, and libraries](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) for details.

152152

153153<Note>

154 Some list endpoints use a different cursor scheme. The [Message Batches API](https://platform.claude.com/docs/en/build-with-claude/batch-processing), the [Models API](https://platform.claude.com/docs/en/api/models/list), and several [Admin API](https://platform.claude.com/docs/en/manage-claude/admin-api) endpoints take `after_id` and `before_id` query parameters instead of `page`. Their responses return `has_more`, `first_id`, and `last_id` instead of `next_page`. See the reference page for each endpoint for its exact pagination fields.

154 Some list endpoints use a different cursor scheme. The Message Batches API (see [Batch processing](https://platform.claude.com/docs/en/build-with-claude/batch-processing)), the [Models API](https://platform.claude.com/docs/en/api/models/list), and several [Admin API](https://platform.claude.com/docs/en/manage-claude/admin-api) endpoints take `after_id` and `before_id` query parameters instead of `page`. Their responses return `has_more`, `first_id`, and `last_id` instead of `next_page`. See the reference page for each endpoint for its exact pagination fields.

155155</Note>

156156

157157## Rate limits and availability

from line 160

160160

161161The API enforces rate limits and spend limits to prevent misuse and manage capacity. Limits are organized into usage tiers; your organization is placed on a tier automatically and can move to a higher tier over time. Each tier has:

162162

163* **Spend limits**: Maximum monthly cost for API usage

164* **Rate limits**: Maximum number of requests per minute (RPM) and tokens per minute (TPM)

163* **Spend limits:** Maximum monthly cost for API usage

164* **Rate limits:** Maximum number of requests per minute (RPM) and tokens per minute (TPM)

165165

166In the Console, you can view your rate limits on the [Rate limits](https://platform.claude.com/usage/limits) page and your spend limits on the [Billing](https://platform.claude.com/settings/billing) page. For higher rate limits or a higher monthly spend cap, use **Request tier increase** on the Rate limits page.

167167

168168For detailed information about limits, tiers, and the token bucket algorithm used for rate limiting, see [Rate limits](https://platform.claude.com/docs/en/api/rate-limits).

169169

api/rate-limits Changed · +16 / -16 lines

## Setting lower limits for workspaces ## Setting lower limits for Workspaces

from line 13

13131. **Spend limits** set a maximum monthly cost an organization can incur for API usage.

14142. **Rate limits** set the maximum number of API requests an organization can make over a defined period of time.

1515

16The API enforces service-configured limits at the organization level, but you may also set user-configurable limits for your organization's workspaces.

16The API enforces service-configured limits at the organization level, but you can also set user-configurable limits for your organization's workspaces.

1717

1818## About rate limits

1919

from line 80

8080 </Step>

8181</Steps>

8282

83When usage reaches a spend limit you set, requests return HTTP 400 with error type `invalid_request_error`. The message begins `You have reached your specified API usage limits`, or `You have reached your specified workspace API usage limits` for a workspace limit, and states when access resumes. Raise or remove the limit to restore access sooner.

83When usage reaches a spend limit you set, requests return HTTP 400 with error type `invalid_request_error`. The message starts with `You have reached your specified API usage limits`, or `You have reached your specified workspace API usage limits` for a workspace limit, and states when access resumes. Raise or remove the limit to restore access sooner.

8484

8585Limits on the [Claude Code workspace](https://platform.claude.com/docs/en/manage-claude/workspaces#claude-code-workspace) are checked separately: Claude Code requests over that workspace's limit can instead receive a 429 that carries a `retry-after` header.

8686

8787## Rate limits

8888

89The rate limits for the Messages API are measured in requests per minute (RPM), input tokens per minute (ITPM), and output tokens per minute (OTPM) for each model class. If you exceed any of the rate limits you will get a [429 error](https://platform.claude.com/docs/en/api/errors) describing which rate limit was exceeded. When the response has a `retry-after` header, wait that many seconds before retrying.

89The rate limits for the Messages API are measured in requests per minute (RPM), input tokens per minute (ITPM), and output tokens per minute (OTPM) for each model class. If you exceed any of the rate limits, you will get a [429 error](https://platform.claude.com/docs/en/api/errors) describing which rate limit was exceeded. When the response has a `retry-after` header, wait that many seconds before retrying.

9090

9191<Note>

92 You might also encounter 429 errors because of acceleration limits on the API if your organization has a sharp increase in usage. To avoid hitting acceleration limits, ramp up your traffic gradually and maintain consistent usage patterns.

92 You might also encounter 429 errors because of acceleration limits on the API if your organization has a sharp increase in usage. To avoid hitting acceleration limits, increase your traffic gradually and maintain consistent usage patterns.

9393</Note>

9494

9595### Cache-aware ITPM

9696

97Many API providers use a combined "tokens per minute" (TPM) limit that may include all tokens, both cached and uncached, input and output. **For most Claude models, only uncached input tokens count toward your ITPM rate limits.** This is a key advantage that makes the rate limits effectively higher than they might initially appear.

97Many API providers use a combined "tokens per minute" (TPM) limit that might include all tokens, both cached and uncached, input and output. **For most Claude models, only uncached input tokens count toward your ITPM rate limits.** This is a key advantage that makes the rate limits effectively higher than they might initially appear.

9898

9999ITPM rate limits are estimated at the beginning of each request, and the estimate is adjusted during the request to reflect the actual number of input tokens used.

100100

from line 111

111111 total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens

112112 ```

113113

114 This means when you have cached content, `input_tokens` will typically be much smaller than your total input. For example, with a 200k token cached document and a 50 token user question, you'd see `input_tokens: 50` even though the total input is 200,050 tokens.

114 This means when you have cached content, `input_tokens` will typically be much smaller than your total input. For example, with a 200k-token cached document and a 50-token user question, you'd see `input_tokens: 50` even though the total input is 200,050 tokens.

115115

116116 For rate limit purposes on most models, only `input_tokens` + `cache_creation_input_tokens` count toward your ITPM limit, making [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) an effective way to increase your effective throughput.

117117</Note>

118118

119**Example:** With a 2,000,000 ITPM limit and an 80% cache hit rate, you could effectively process 10,000,000 total input tokens per minute (2M uncached + 8M cached), because cached tokens don't count toward your rate limit.

119**Example:** With a 2,000,000 ITPM limit and an 80 percent cache hit rate, you could effectively process 10,000,000 total input tokens per minute (2M uncached + 8M cached), because cached tokens don't count toward your rate limit.

120120

121121<Note>

122122 Claude Haiku 3.5 (marked with footnote 4 in the following rate limit tables) also counts `cache_read_input_tokens` toward ITPM rate limits.

from line 124

124124 For all other models, cached input tokens do not count toward rate limits and are billed at the [cache read rate](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pricing), a fraction of the base input price. This means you can achieve significantly higher effective throughput by using [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching).

125125</Note>

126126

127To make the most of your rate limits, cache repeated content such as system instructions and prompts, large context documents, tool definitions, and conversation history; see [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) for guidance. With effective caching, you can substantially increase your actual throughput without raising your rate limits. Monitor your cache hit rate on the [Usage page](https://platform.claude.com/usage) in the Claude Console to tune your caching strategy.

127To get the highest throughput within your rate limits, cache repeated content such as system instructions and prompts, large context documents, tool definitions, and conversation history; see [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) for guidance. With effective caching, you can substantially increase your actual throughput without raising your rate limits. Monitor your cache hit rate on the [Usage](https://platform.claude.com/usage) page in the Claude Console to tune your caching strategy.

128128

129129OTPM rate limits are evaluated in real time as output tokens are produced, counting only the actual tokens generated. The `max_tokens` parameter does not factor into OTPM rate limit calculations, so there is no rate limit downside to setting a higher `max_tokens` value.

130130

from line 195

195195

196196### Message Batches API

197197

198The Message Batches API has its own set of rate limits which are shared across all models. These include a requests per minute (RPM) limit to all API endpoints and a limit on the number of batch requests that can be in the processing queue at the same time. A "batch request" here refers to part of a Message Batch. You may create a Message Batch containing thousands of batch requests, each of which count toward this limit. A batch request is considered part of the processing queue when it has yet to be successfully processed by the model.

198The Message Batches API has its own set of rate limits, which are shared across all models. These include a requests per minute (RPM) limit to all API endpoints and a limit on the number of batch requests that can be in the processing queue at the same time. A "batch request" here refers to part of a Message Batch. You can create a Message Batch containing thousands of batch requests, each of which counts toward this limit. A batch request is considered part of the processing queue when it has yet to be successfully processed by the model.

199199

200200<Tabs>

201201 <Tab title="Start tier">

from line 223

223223

224224### Managed Agents

225225

226[Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) endpoints are rate-limited per organization. These limits are separate from the Messages API rate limits above.

226[Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) endpoints are rate-limited for each organization. These limits are separate from the Messages API rate limits described earlier on this page.

227227

228228| Operation | Limit |

229229| ------------------------------------------------------------------ | ------------------------- |

from line 244

244244

245245You can monitor your rate limit usage on the [Usage](https://platform.claude.com/usage) page of the [Claude Console](https://platform.claude.com/).

246246

247In addition to providing token and request charts, the Usage page provides two separate rate limit charts. Use these charts to see what headroom you have to grow, identify when you may be hitting peak use, understand what rate limits to request, and learn how to improve your caching rates. The charts visualize a number of metrics for a given rate limit (for example, per model):

247In addition to providing token and request charts, the Usage page provides two separate rate limit charts. Use these charts to see what headroom you have to grow, identify when you might be hitting peak use, understand what rate limits to request, and learn how to improve your caching rates. The charts visualize a number of metrics for a given rate limit (for example, for each model):

248248

249249* The **Rate Limit - Input Tokens** chart includes:

250250

from line 265

265265 **[Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws):** The **Request tier increase** flow is not available. Contact your Anthropic account representative or [Anthropic support](https://support.claude.com), and include the models you need raised, your peak input and output tokens per minute for each model, and roughly what share of your input is cached or repeated context. See [Rate limits and quotas on Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#rate-limits-and-quotas).

266266</Note>

267267

268## Setting lower limits for Workspaces

268## Setting lower limits for workspaces

269269

270270For more about workspaces, see [Workspaces](https://platform.claude.com/docs/en/manage-claude/workspaces).

271271

272To protect Workspaces in your Organization from potential overuse, you can set custom spend and rate limits per Workspace.

272To protect Workspaces in your Organization from potential overuse, you can set custom spend and rate limits for each Workspace.

273273

274274Example: If your Organization's limit is 40,000 input tokens per minute and 8,000 output tokens per minute, you might limit one Workspace to 30,000 input tokens per minute. This protects other Workspaces from potential overuse and ensures a more equitable distribution of resources across your Organization. The remaining unused tokens per minute (or more, if that Workspace doesn't use the limit) are then available for other Workspaces to use.

275275

from line 277

277277

278278* You can't set spend limits on the default Workspace.

279279* If not set, Workspace limits match the Organization's limit.

280* Workspace limits are set per limiter type (such as requests per minute, input tokens per minute, or output tokens per minute).

280* Workspace limits are set for each limiter type (such as requests per minute, input tokens per minute, or output tokens per minute).

281281* Organization-wide limits always apply, even if Workspace limits add up to more.

282282

283283To read your current organization and workspace rate limits programmatically, use the [Rate Limits API](https://platform.claude.com/docs/en/manage-claude/rate-limits-api).

api/service-tiers Changed · +4 / -4 lines

from line 36

3636**Input tokens**

3737

3838* Cache reads as 0.1 tokens per token read from the cache

39* Cache writes as 1.25 tokens per token written to the cache with a 5 minute TTL

40* Cache writes as 2.00 tokens per token written to the cache with a 1 hour TTL

39* Cache writes as 1.25 tokens per token written to the cache with a 5-minute TTL

40* Cache writes as 2.00 tokens per token written to the cache with a 1-hour TTL

4141* For [US-only inference](https://platform.claude.com/docs/en/manage-claude/data-residency) (`inference_geo: "us"`) requests on Claude 4.6 and later models, input tokens are 1.1 tokens per token

4242* All other input tokens are 1 token per token

4343

from line 183

183183The `service_tier` parameter accepts the following values:

184184

185185* `"auto"` (default) - Uses the Priority Tier capacity if available, falling back to your other capacity if not

186* `"standard_only"` - Only use standard tier capacity, useful if you don't want to use your Priority Tier capacity

186* `"standard_only"` - Uses only standard tier capacity, useful if you don't want to use your Priority Tier capacity

187187

188188The response `usage` object also includes the service tier assigned to the request:

189189

from line 223

223223* A commitment duration (1, 3, 6, or 12 months)

224224* A specific model version

225225

226Priority Tier targets 99.5% uptime with prioritized computational resources. Requests beyond your committed capacity automatically fall back to standard tier.

226Priority Tier targets 99.5 percent uptime with prioritized computational resources. Requests beyond your committed capacity automatically fall back to standard tier.

227227

228228### Supported models

229229

build-with-claude/batch-processing Changed · +121 / -123 lines

from line 1

11---

22title: Batch processing

33url: https://platform.claude.com/docs/en/build-with-claude/batch-processing

4description: Process large volumes of Messages requests asynchronously with the Message Batches API, cutting costs by 50% and increasing throughput.

4description: Process large volumes of Messages requests asynchronously with the Message Batches API, cutting costs by 50 percent and increasing throughput.

55---

77Batch processing is a powerful approach for handling large volumes of requests efficiently. Instead of processing requests one at a time with immediate responses, batch processing allows you to submit multiple requests together for asynchronous processing. This pattern is particularly useful when:

from line 42

4242

4343* A Message Batch is limited to either 100,000 Message requests or 256 MB in size, whichever is reached first.

4444* The system processes each batch as fast as possible, with most batches completing within 1 hour. You can access batch results when all messages have completed or after 24 hours, whichever comes first. Batches expire if processing does not complete within 24 hours.

45* Batch results are available for 29 days after creation. After that, you may still view the Batch, but its results will no longer be available for download.

45* Batch results are available for 29 days after creation. After that, you can still view the Batch, but its results will no longer be available for download.

4646* Batches are scoped to a [Workspace](https://platform.claude.com/settings/workspaces) in the Claude Console. You may view all batches (and their results) that were created within the Workspace your request runs in.

47* Rate limits apply to both Batches API HTTP requests and the number of requests within a batch waiting to be processed. See [Message Batches API rate limits](https://platform.claude.com/docs/en/api/rate-limits#message-batches-api). Additionally, processing may be slowed down based on current demand and your request volume. In that case, you may see more requests expiring after 24 hours.

47* Rate limits apply to both Batches API HTTP requests and the number of requests within a batch waiting to be processed. See [Message Batches API rate limits](https://platform.claude.com/docs/en/api/rate-limits#message-batches-api). Additionally, processing might be slowed down based on current demand and your request volume. In that case, you might see more requests expiring after 24 hours.

4848* Because of high throughput and concurrent processing, batches may go slightly over the [spend limit](https://platform.claude.com/settings/billing) configured in the Claude Console for your Workspace.

4949* Each batched request must have `max_tokens` of at least `1`. `max_tokens: 0` ([cache pre-warming](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pre-warming-the-cache)) is not supported inside a batch, because an ephemeral cache entry written during batch processing would likely expire before the follow-up request runs.

5050

from line 67

6767

6868A small number of Messages API parameters are **not** supported in batch requests. Including any of these returns a validation error:

6969

70| Parameter | Why |

71| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |

72| `stream: true` | Batch results come back as a single file, not a stream. |

73| `speed` ([Fast mode](https://platform.claude.com/docs/en/build-with-claude/fast-mode)) | Fast mode tunes synchronous latency, which doesn't apply to asynchronous batch processing. |

74| `max_tokens: 0` | See [Batch limitations](https://platform.claude.com/docs/en/build-with-claude/batch-processing#batch-limitations). |

70| Parameter | Why |

71| -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

72| `stream: true` | Batch results come back as a single file, not a stream. |

73| `speed` ([Fast mode](https://platform.claude.com/docs/en/build-with-claude/fast-mode)) | Fast mode tunes synchronous latency, which doesn't apply to asynchronous batch processing. |

74| `fallbacks` ([Server-side fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#server-side-fallback)) | Server-side fallback doesn't apply to batches. To retry refused requests, see [Refusals in Message Batches](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#refusals-in-message-batches). |

75| `max_tokens: 0` | See [Batch limitations](https://platform.claude.com/docs/en/build-with-claude/batch-processing#batch-limitations). |

7576

7677<Tip>

7778 Because batches can take longer than 5 minutes to process, consider using the [1-hour cache duration](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#1-hour-cache-duration) with prompt caching for better cache hit rates when processing batches with shared context.

from line 80

7980

8081## Pricing

8182

82The Batches API offers significant cost savings. All usage is charged at 50% of the standard API prices.

83The Batches API offers significant cost savings. All usage is charged at 50 percent of the standard API prices.

8384

8485| Model | Batch input | Batch output |

8586| :----------------------------------------------------------------------------------------------------------------------------------- | :----------- | :------------ |

from line 124

123124<CodeGroup>

124125 ```bash cURL

125126 curl https://api.anthropic.com/v1/messages/batches \

126 --header "x-api-key: $ANTHROPIC_API_KEY" \

127 --header "anthropic-version: 2023-06-01" \

128 --header "content-type: application/json" \

129 --data \

130 '{

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

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

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

130 -d '{

131131 "requests": [

132 {

133 "custom_id": "my-first-request",

134 "params": {

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

136 "max_tokens": 1024,

137 "messages": [

138 {"role": "user", "content": "Hello, world"}

139 ]

140 }

141 },

142 {

143 "custom_id": "my-second-request",

144 "params": {

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

146 "max_tokens": 1024,

147 "messages": [

148 {"role": "user", "content": "Hi again, friend"}

149 ]

150 }

132 {

133 "custom_id": "my-first-request",

134 "params": {

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

136 "max_tokens": 1024,

137 "messages": [

138 {"role": "user", "content": "Hello, world"}

139 ]

151140 }

141 },

142 {

143 "custom_id": "my-second-request",

144 "params": {

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

146 "max_tokens": 1024,

147 "messages": [

148 {"role": "user", "content": "Hi again, friend"}

149 ]

150 }

151 }

152152 ]

153 }'

154154 ```

155155

156156 ```bash CLI

from line 453

453453 ```bash cURL

454454 # Check the status; repeat until processing_status is "ended"

455455 curl "https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID" \

456 --header "x-api-key: $ANTHROPIC_API_KEY" \

457 --header "anthropic-version: 2023-06-01"

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

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

458458 ```

459459

460460 ```bash CLI

from line 603

603603 # last_id as after_id to fetch the next page. (The SDKs and the CLI

604604 # perform automatic pagination.)

605605 curl -s "https://api.anthropic.com/v1/messages/batches?limit=20" \

606 --header "x-api-key: $ANTHROPIC_API_KEY" \

607 --header "anthropic-version: 2023-06-01"

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

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

608608 ```

609609

610610 ```bash CLI

from line 717

717717 # Streams the batch's .jsonl results, one result per line.

718718 # For per-result handling (retries, validation errors), use the Claude SDK.

719719 curl "https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d/results" \

720 --header "anthropic-version: 2023-06-01" \

721 --header "x-api-key: $ANTHROPIC_API_KEY"

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

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

722722 ```

723723

724724 ```bash CLI

725 # Prints one result per line, e.g. `{"custom_id":"test-1","result":{"type":"succeeded",…}}`.

725 # Prints one result per line, for example `{"custom_id":"test-1","result":{"type":"succeeded",…}}`.

726726 # For per-result handling (retries, validation errors), use the SDK

727727 # examples in the other tabs.

728728 ant messages:batches results \

from line 938

938938

939939<CodeGroup>

940940 ```bash cURL

941 curl --request POST https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/cancel \

942 --header "x-api-key: $ANTHROPIC_API_KEY" \

943 --header "anthropic-version: 2023-06-01"

941 curl -X POST https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/cancel \

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

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

944944 ```

945945

946946 ```bash CLI

from line 1038

10381038

10391039### Using prompt caching with Message Batches

10401040

1041The Message Batches API supports prompt caching, allowing you to potentially reduce costs and processing time for batch requests. The pricing discounts from prompt caching and Message Batches can stack, providing even greater cost savings when both features are used together. However, because batch requests are processed asynchronously and concurrently, cache hits are provided on a best-effort basis. Users typically experience cache hit rates ranging from 30% to 98%, depending on their traffic patterns.

10421042

10431043To maximize the likelihood of cache hits in your batch requests:

10441044

from line 1051

10511051<CodeGroup>

10521052 ```bash cURL

10531053 curl https://api.anthropic.com/v1/messages/batches \

1054 --header "x-api-key: $ANTHROPIC_API_KEY" \

1055 --header "anthropic-version: 2023-06-01" \

1056 --header "content-type: application/json" \

1057 --data \

1058 '{

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

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

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

1057 -d '{

10591058 "requests": [

1060 {

1061 "custom_id": "my-first-request",

1062 "params": {

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

1064 "max_tokens": 1024,

1065 "system": [

1066 {

1067 "type": "text",

1068 "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"

1069 },

1070 {

1071 "type": "text",

1072 "text": "<the entire contents of Pride and Prejudice>",

1073 "cache_control": {"type": "ephemeral"}

1074 }

1075 ],

1076 "messages": [

1077 {"role": "user", "content": "Analyze the major themes in Pride and Prejudice."}

1078 ]

1059 {

1060 "custom_id": "my-first-request",

1061 "params": {

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

1063 "max_tokens": 1024,

1064 "system": [

1065 {

1066 "type": "text",

1067 "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"

1068 },

1069 {

1070 "type": "text",

1071 "text": "<the entire contents of Pride and Prejudice>",

1072 "cache_control": {"type": "ephemeral"}

10791073 }

1080 },

1081 {

1082 "custom_id": "my-second-request",

1083 "params": {

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

1085 "max_tokens": 1024,

1086 "system": [

1087 {

1088 "type": "text",

1089 "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"

1090 },

1091 {

1092 "type": "text",

1093 "text": "<the entire contents of Pride and Prejudice>",

1094 "cache_control": {"type": "ephemeral"}

1095 }

1096 ],

1097 "messages": [

1098 {"role": "user", "content": "Write a summary of Pride and Prejudice."}

1099 ]

1074 ],

1075 "messages": [

1076 {"role": "user", "content": "Analyze the major themes in Pride and Prejudice."}

1077 ]

1078 }

1079 },

1080 {

1081 "custom_id": "my-second-request",

1082 "params": {

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

1084 "max_tokens": 1024,

1085 "system": [

1086 {

1087 "type": "text",

1088 "text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"

1089 },

1090 {

1091 "type": "text",

1092 "text": "<the entire contents of Pride and Prejudice>",

1093 "cache_control": {"type": "ephemeral"}

11001094 }

1095 ],

1096 "messages": [

1097 {"role": "user", "content": "Write a summary of Pride and Prejudice."}

1098 ]

11011099 }

1100 }

11021101 ]

1103 }'

1102 }'

11041103 ```

11051104

11061105 ```bash CLI

from line 1542

15431542

15441543All [server tools](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools) (web search, web fetch, code execution, MCP connectors, advisor, and tool search) work in batch requests. The batch worker runs the same server-side agentic loop as the synchronous Messages API.

15451544

1546Because there is no open connection to maintain, the batch loop runs **more iterations per turn** than a synchronous request before it returns `stop_reason: "pause_turn"`. If a batch result comes back with `pause_turn`, the turn did not finish; you can continue it by submitting the paused assistant content in a follow-up request (batch or synchronous) exactly as shown in the [pause\_turn continuation pattern](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools#the-server-side-loop-and-pause-turn).

1545Because there is no open connection to maintain, the batch loop runs **more iterations per turn** than a synchronous request before it returns `stop_reason: "pause_turn"`. If a batch result comes back with `pause_turn`, the turn did not complete; you can continue it by submitting the paused assistant content in a follow-up request (batch or synchronous) exactly as shown in the [pause\_turn continuation pattern](https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools#the-server-side-loop-and-pause-turn).

15471546

1548The batch worker additionally throttles `web_search` per organization so that highly concurrent batch processing does not exhaust your organization's web-search rate limit. The batch retries throttled requests automatically; you don't need to handle this yourself, but very large web-search batches might take longer to complete.

1547The batch worker additionally throttles `web_search` for each organization so that highly concurrent batch processing does not exhaust your organization's web-search rate limit. The batch retries throttled requests automatically; you don't need to handle this yourself, but very large web-search batches might take longer to complete.

15491548

15501549### Extended output (beta)

15511550

from line 1556

15571556

15581557Use extended output for long-form generation such as book-length drafts and technical documentation, exhaustive structured data extraction, large code-generation scaffolds, and long reasoning chains.

15591558

1560A single 300k-token generation can take over an hour to complete, so plan your batch submissions with the 24-hour processing window in mind. Standard batch pricing (50% of standard API prices) applies.

1559A single 300k-token generation can take over an hour to complete, so plan your batch submissions with the 24-hour processing window in mind. Standard batch pricing (50 percent of standard API prices) applies.

15611560

15621561<CodeGroup>

15631562 ```bash cURL

15641563 curl https://api.anthropic.com/v1/messages/batches \

1565 --header "x-api-key: $ANTHROPIC_API_KEY" \

1566 --header "anthropic-version: 2023-06-01" \

1567 --header "anthropic-beta: output-300k-2026-03-24" \

1568 --header "content-type: application/json" \

1569 --data \

1570 '{

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

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

1566 -H "anthropic-beta: output-300k-2026-03-24" \

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

1568 -d '{

15711569 "requests": [

1572 {

1573 "custom_id": "long-form-request",

1574 "params": {

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

1576 "max_tokens": 300000,

1577 "messages": [

1578 {"role": "user", "content": "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices."}

1579 ]

1580 }

1570 {

1571 "custom_id": "long-form-request",

1572 "params": {

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

1574 "max_tokens": 300000,

1575 "messages": [

1576 {"role": "user", "content": "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices."}

1577 ]

15811578 }

1579 }

15821580 ]

1583 }'

1581 }'

15841582 ```

15851583

15861584 ```bash CLI

from line 1786

17881786

17891787### Best practices for effective batching

17901788

1791To get the most out of the Batches API:

1789To use the Batches API effectively:

17921790

17931791* Monitor batch processing status regularly and implement appropriate retry logic for failed requests.

1794* Use meaningful `custom_id` values to easily match results with requests, since order is not guaranteed.

1792* Use meaningful `custom_id` values to easily match results with requests, because order is not guaranteed.

17951793* Consider breaking very large datasets into multiple batches for better manageability.

17961794* Dry run a single request shape with the Messages API to avoid validation errors.

17971795

from line 1797

17991797

18001798If experiencing unexpected behavior:

18011799

1802* Verify that the total batch request size doesn't exceed 256 MB. If the request size is too large, you may get a 413 `request_too_large` error.

1800* Verify that the total batch request size doesn't exceed 256 MB. If the request size is too large, you might get a 413 `request_too_large` error.

18031801* Check that you're using [supported models](https://platform.claude.com/docs/en/build-with-claude/batch-processing#supported-models) for all requests in the batch.

18041802* Ensure each request in the batch has a unique `custom_id`.

18051803* Ensure that it has been less than 29 days since batch `created_at` (not processing `ended_at`) time. If over 29 days have passed, results will no longer be viewable.

from line 1807

18091807

18101808## Batch storage and privacy

18111809

1812* **Workspace isolation**: Batches are isolated within the Workspace they are created in. They can only be accessed by API requests in that same Workspace, or users with permission to view Workspace batches in the Console.

1810* **Workspace isolation:** Batches are isolated within the Workspace they are created in. They can only be accessed by API requests in that same Workspace, or users with permission to view Workspace batches in the Console.

18131811

1814* **Result availability**: Batch results are available for 29 days after the batch is created, allowing ample time for retrieval and processing.

1812* **Result availability:** Batch results are available for 29 days after the batch is created, allowing ample time for retrieval and processing.

18151813

18161814## Data retention

18171815

from line 1821

18231821

18241822<AccordionGroup>

18251823 <Accordion title="How long does it take for a batch to process?">

1826 Batches may take up to 24 hours for processing, but many finish sooner. Actual processing time depends on the size of the batch, current demand, and your request volume. It is possible for a batch to expire and not complete within 24 hours.

1824 Batches might take up to 24 hours for processing, but many complete sooner. Actual processing time depends on the size of the batch, current demand, and your request volume. It is possible for a batch to expire and not complete within 24 hours.

18271825 </Accordion>

18281826

18291827 <Accordion title="Is the Batches API available for all models?">

from line 1829

18311829 </Accordion>

18321830

18331831 <Accordion title="Can I use the Message Batches API with other API features?">

1834 Yes, the Message Batches API supports nearly all features available in the Messages API, including most beta features. A small number of parameters (`stream`, `speed`, and `max_tokens: 0`) are not supported. See [What can be batched](https://platform.claude.com/docs/en/build-with-claude/batch-processing#what-can-be-batched) for the full list.

1832 Yes, the Message Batches API supports nearly all features available in the Messages API, including most beta features. A small number of parameters (`stream`, `speed`, `fallbacks`, and `max_tokens: 0`) are not supported. See [What can be batched](https://platform.claude.com/docs/en/build-with-claude/batch-processing#what-can-be-batched) for the full list.

18351833 </Accordion>

18361834

18371835 <Accordion title="How does the Message Batches API affect pricing?">

1838 The Message Batches API offers a 50% discount on all usage compared to standard API prices. This applies to input tokens, output tokens, and any special tokens. For more on pricing, visit [Pricing](https://claude.com/pricing#anthropic-api).

1836 The Message Batches API offers a 50 percent discount on all usage compared to standard API prices. This applies to input tokens, output tokens, and any special tokens. For more on pricing, visit [Pricing](https://claude.com/pricing#anthropic-api).

18391837 </Accordion>

18401838

18411839 <Accordion title="Can I update a batch after it's been submitted?">

1842 No, once a batch has been submitted, it cannot be modified. If you need to make changes, you should cancel the current batch and submit a new one. Note that cancellation may not take immediate effect.

1840 No, once a batch has been submitted, it cannot be modified. If you need to make changes, you should cancel the current batch and submit a new one. Note that cancellation might not take immediate effect.

18431841 </Accordion>

18441842

18451843 <Accordion title="Are there Message Batches API rate limits and do they interact with the Messages API rate limits?">

from line 1854

18561854 1. Batches and their results are isolated within the Workspace in which they were created. This means they can only be accessed by API requests in that same Workspace.

18571855 2. Each request within a batch is processed independently, with no data leakage between requests.

18581856 3. Results are only available for a limited time (29 days), and follow Anthropic's [data retention policy](https://support.claude.com/en/articles/7996866-how-long-do-you-store-personal-data).

1859 4. Downloading batch results in the Console can be disabled on the organization-level or on a per-workspace basis.

1857 4. Downloading batch results in the Console can be disabled on the organization level or on a per-workspace basis.

18601858 </Accordion>

18611859

18621860 <Accordion title="Can I use prompt caching in the Message Batches API?">

1863 Yes, it is possible to use prompt caching with Message Batches API. However, because asynchronous batch requests can be processed concurrently and in any order, cache hits are provided on a best-effort basis.

1861 Yes, it is possible to use prompt caching with the Message Batches API. However, because asynchronous batch requests can be processed concurrently and in any order, cache hits are provided on a best-effort basis.

18641862 </Accordion>

18651863</AccordionGroup>

18661864

from line 1866

18681866

18691867<CardGroup cols={2}>

18701868 <Card title="Search results" icon="magnifying-glass" href="https://platform.claude.com/docs/en/build-with-claude/search-results">

1871 Enable natural citations for RAG applications by providing search results with source attribution.

1869 Get natural citations for RAG applications by providing search results with source attribution.

18721870 </Card>

18731871

18741872 <Card title="Prompt caching" icon="database" href="https://platform.claude.com/docs/en/build-with-claude/prompt-caching">

build-with-claude/cache-diagnostics Changed · +7 / -7 lines

from line 702

702702<Tabs>

703703 <Tab title="cURL">

704704 <Info>

705 This workflow doesn't translate well to a one-off shell command. See the SDK tabs for the loop pattern; the per-turn HTTP request is identical to [Basic usage](https://platform.claude.com/docs/en/build-with-claude/cache-diagnostics#basic-usage).

705 This workflow doesn't translate well to a one-off shell command. Use the Claude SDK to run the loop; the per-turn HTTP request is identical to [Basic usage](https://platform.claude.com/docs/en/build-with-claude/cache-diagnostics#basic-usage).

706706 </Info>

707707 </Tab>

708708

709709 <Tab title="CLI">

710710 <Info>

711 This workflow doesn't translate well to a one-off shell command. See the SDK tabs for the loop pattern; the per-turn CLI invocation is identical to [Basic usage](https://platform.claude.com/docs/en/build-with-claude/cache-diagnostics#basic-usage).

711 This workflow doesn't translate well to a one-off shell command. Use the Claude SDK to run the loop; the per-turn CLI command is identical to [Basic usage](https://platform.claude.com/docs/en/build-with-claude/cache-diagnostics#basic-usage).

712712 </Info>

713713 </Tab>

714714

from line 968

968968| Value | Meaning |

969969| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

970970| `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. |

971| `{"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. |

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

972972| `{"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. |

973973

974974When `cache_miss_reason` is non-null, it looks like this:

from line 996

996996

997997## Cache miss reason types

998998

999`cache_miss_reason` is a discriminated union on `type`. The response reports the earliest divergence only, so fix it first; later ones may be hidden behind it.

999`cache_miss_reason` is a discriminated union on `type`. The response reports the earliest divergence only, so fix it first; later ones might be hidden behind it.

10001000

10011001| Type | What it means | What to change |

10021002| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

from line 1013

10131013

10141014## Reading diagnostics alongside usage

10151015

1016`diagnostics` answers "did my request change?" while `usage.cache_read_input_tokens` answers "did the cache hit?". Combining them tells you where to look.

1016`diagnostics` answers "did my request change?" whereas `usage.cache_read_input_tokens` answers "did the cache hit?" Combining them tells you where to look.

10171017

10181018This matrix applies to turns where you passed a real `previous_message_id`. On the first turn (`previous_message_id: null`), `diagnostics` is always `null` and `cache_read_input_tokens` is normally zero because the cache is being written, not read; no troubleshooting is needed. The matrix also does not apply when `cache_miss_reason` is `null` (the comparison is still pending; check the next turn) or when its `type` is `previous_message_not_found` or `unavailable` (no comparison was produced).

10191019

from line 1021

10211021| ----------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

10221022| `null` | high | Working as expected. Your prefix is stable and the cache hit. |

10231023| `null` | low or zero | Your requests match but the cache entry was no longer available. Consider shortening gaps between turns or using the [1-hour cache TTL](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#1-hour-cache-duration). |

1024| `cache_miss_reason` is a `*_changed` type | low or zero | Your bug. The request changed; fix the cause indicated by `type`. |

1024| `cache_miss_reason` is a `*_changed` type | low or zero | The request changed; fix the cause indicated by `type`. |

10251025| `cache_miss_reason` is a `*_changed` type | high | Rare. A change occurred late in the prompt but an earlier `cache_control` breakpoint still hit. Worth fixing, but low impact. |

10261026

10271027## Limitations

from line 1029

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

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

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

1032* **Comparison horizon:** For very long conversations where the only change is deep in the message list, the response may be `unavailable` rather than a precise location.

1032* **Comparison horizon:** For very long conversations where the only change is deep in the message list, the response might be `unavailable` rather than a precise location.

10331033* **Best-effort:** Diagnostics never blocks or fails your request. If diagnostic information is not available, the response returns `unavailable`, or `cache_miss_reason: null` when the comparison was still running.

10341034

10351035## Data retention

build-with-claude/citations Changed · +3 / -3 lines

from line 311

311311

312312 Compared to prompting Claude to cite sources, the citations feature offers the following advantages:

313313

314 * **Cost savings:** If your prompt-based approach asks Claude to output direct quotes, you may see cost savings because `cited_text` does not count toward your output tokens.

314 * **Cost savings:** If your prompt-based approach asks Claude to output direct quotes, you might see cost savings because `cited_text` does not count toward your output tokens.

315315 * **Better citation reliability:** Because the API parses citations into the response formats described in the following sections and extracts `cited_text` directly, citations are guaranteed to contain valid pointers to the provided documents.

316316 * **Improved citation quality:** In Anthropic's evaluations, the citations feature is significantly more likely to cite the most relevant quotes from documents than purely prompt-based approaches.

317317</Tip>

from line 338

338338 </Step>

339339

340340 <Step title="Claude provides cited response">

341 * Responses may now include multiple text blocks where each text block can contain a claim that Claude is making and a list of citations that support the claim.

341 * Responses might now include multiple text blocks where each text block can contain a claim that Claude is making and a list of citations that support the claim.

342342

343343 * Citations reference specific locations in source documents. The format of these citations is dependent on the type of document being cited from.

344344

from line 988

988988

989989### PDF documents

990990

991PDF documents can be provided as base64-encoded data, a URL, or by `file_id`. PDF text is extracted and chunked into sentences. As image citations are not yet supported, PDFs that are scans of documents and do not contain extractable text are not citable.

991PDF documents can be provided as base64-encoded data, as a URL, or by `file_id`. PDF text is extracted and chunked into sentences. As image citations are not yet supported, PDFs that are scans of documents and do not contain extractable text are not citable.

992992

993993<Tabs>

994994 <Tab title="Base64">

build-with-claude/claude-in-amazon-bedrock Changed · +6 / -6 lines

from line 16

1616

1717## Prerequisites

1818

19Before you begin, ensure you have:

19Before you start, ensure you have:

2020

21* An AWS account with [Amazon Bedrock model access](https://console.aws.amazon.com/bedrock/home#/modelaccess) enabled for the Claude models you intend to use.

22* The [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) installed and configured (optional, for credential management).

21* An AWS account with [Amazon Bedrock model access](https://console.aws.amazon.com/bedrock/home#/modelaccess) enabled for the Claude models you intend to use

22* The [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) installed and configured (optional, for credential management)

2323

2424Claude Mythos Preview additionally requires a dedicated AWS account that has been allowlisted by the Bedrock Marketplace team. Your Anthropic account executive can submit your account ID for allowlisting (typically processed within 24 hours), and AWS sends a welcome email once it's complete.

2525

from line 37

3737 </Step>

3838

3939 <Step title="Developer: pass the role">

40 When calling the API, Bedrock assumes the service role on your behalf. See the [Amazon Bedrock documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-mantle.html) for how to associate the role with your requests.

40 When you call the API, Bedrock assumes the service role on your behalf. See the [Amazon Bedrock documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-mantle.html) for how to associate the role with your requests.

4141 </Step>

4242</Steps>

4343

from line 390

390390Claude in Amazon Bedrock is available in the following AWS regions. Amazon Bedrock offers two endpoint types:

391391

392392* **Global:** dynamic routing across all available regions for maximum availability. No pricing premium.

393* **Regional:** the endpoint resolves to the single AWS region you specify, for data-residency requirements. Regional endpoints carry a 10% pricing premium over global endpoints. To route across multiple regions within a geography, use an [inference profile](https://docs.aws.amazon.com/bedrock/latest/userguide/cross-region-inference.html) (US, EU, JP, or AU). Regions marked **In-region only** in the table support direct single-region routing without an inference profile.

393* **Regional:** the endpoint resolves to the single AWS region you specify, for data-residency requirements. Regional endpoints carry a 10 percent pricing premium over global endpoints. To route across multiple regions within a geography, use an [inference profile](https://docs.aws.amazon.com/bedrock/latest/userguide/cross-region-inference.html) (US, EU, JP, or AU). Regions marked **In-region only** in the table support direct single-region routing without an inference profile.

394394

395395The global endpoint is available for Claude Fable 5.1, Claude Fable 5, Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Sonnet 5.5, Claude Sonnet 5, Claude Haiku 5.5, and Claude Haiku 4.5. For Claude Fable 5.1, regional endpoints are currently available in `us-east-1` only. Claude Mythos Preview is regional only and is available in `us-east-1`.

396396

build-with-claude/claude-in-microsoft-foundry Changed · +7 / -7 lines

from line 27

2727

2828## Prerequisites

2929

30Before you begin, ensure you have:

30Before you start, ensure you have:

3131

3232* An active Azure subscription

3333* Access to the [Foundry portal](https://ai.azure.com/)

from line 36

3636

3737## Install an SDK

3838

39Anthropic's [client SDKs](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) support Foundry through a platform-specific package or client class. The examples on this page also show requests with cURL and the ant CLI. To set up the CLI, see [CLI quickstart](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/quickstart).

39Anthropic's [client SDKs](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) support Foundry through a platform-specific package or client class. The examples on this page also show requests with cURL and the `ant` CLI. To set up the CLI, see [CLI quickstart](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/quickstart).

4040

4141<Note>

4242 Foundry is supported by the C#, Go, Java, PHP, Python, and TypeScript SDKs. Foundry is not currently available in the Ruby SDK.

from line 129

129129

130130## Provisioning

131131

132Foundry uses a two-level hierarchy: **resources** contain your security and billing configuration, while **deployments** are the model instances you call through the API. You'll first create a Foundry resource, then create one or more Claude deployments within it.

132Foundry uses a two-level hierarchy: **resources** contain your security and billing configuration, whereas **deployments** are the model instances you call through the API. You'll first create a Foundry resource, then create one or more Claude deployments within it.

133133

134134### Provisioning Foundry resources

135135

from line 151

151151

1521522. Search for and select a Claude model (for example, claude-opus-5-5). Each model appears once in the catalog regardless of how many hosting options it supports.

153153

1543. On the model card, select **Deploy**, then **Custom settings** to open the deployment settings pane. If you choose **Default settings** instead, the deployment is automatically configured as Hosted on Azure for models available in both hosting options.

1543. On the model card, select **Deploy**, then **Custom settings** to open the deployment settings pane. If you select **Default settings** instead, the deployment is automatically configured as Hosted on Azure for models available in both hosting options.

155155

1561564. On your first Claude deployment, review the Azure Marketplace terms, select an industry, and select **Agree and Proceed** to accept the terms and subscribe to the Azure Marketplace offer.

157157

from line 158

1581585. Configure the deployment:

159159

160160 * **Deployment name:** Defaults to the model ID, but you can customize it (for example, `my-claude-deployment`). The deployment name cannot be changed after creation.

161 * **Region scope:** Select Global, or for models hosted on Azure, Data Zone. Selecting Data Zone creates a US Data Zone Standard deployment, which keeps inference within the United States and is equivalent to setting [`inference_geo: "us"`](https://platform.claude.com/docs/en/manage-claude/data-residency#inference-geo) on the Claude API. For Claude Sonnet 5.5, select Global.

161 * **Region scope:** Select **Global**, or for models hosted on Azure, **Data Zone**. Selecting **Data Zone** creates a US Data Zone Standard deployment, which keeps inference within the United States and is equivalent to setting [`inference_geo: "us"`](https://platform.claude.com/docs/en/manage-claude/data-residency#inference-geo) on the Claude API. For Claude Sonnet 5.5, select **Global**.

162162 * **Model version:** Expand **Model version settings** and select a version from the **Model version** dropdown menu. Each [hosting option](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options) is listed as a separate model version, labeled with its hosting option (for example, version 1 for Hosted on Anthropic, version 2 for Hosted on Azure).

163163

1641646. Select **Deploy** and wait for provisioning to complete.

from line 757

757757

758758**Error:** `403 Forbidden`

759759

760* **Solution:** Your Azure account may lack the necessary permissions. Ensure you have the appropriate Azure RBAC role assigned (for example, **Foundry User** (formerly Azure AI User) or **Cognitive Services User**).

760* **Solution:** Your Azure account might lack the necessary permissions. Ensure you have the appropriate Azure RBAC role assigned (for example, **Foundry User** (formerly Azure AI User) or **Cognitive Services User**).

761761

762762### Rate limiting

763763

from line 779

779779

780780**Error:** `Invalid model parameter`

781781

782* **Solution:** The model parameter should contain your deployment name, which can be customized in the Foundry portal. Verify the deployment exists and is properly configured.

782* **Solution:** The `model` parameter should contain your deployment name, which can be customized in the Foundry portal. Verify the deployment exists and is properly configured.

783783

784784## Next steps

785785

build-with-claude/claude-on-amazon-bedrock-legacy Changed · +14 / -14 lines

from line 19

1919## Install and configure the AWS CLI

2020

21211. [Install a version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html) at or newer than version `2.13.23`.

222. Configure your AWS credentials using the AWS configure command (see [Configure the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html)) or find your credentials by navigating to "Command line or programmatic access" within your AWS dashboard and following the directions in the modal window.

222. Configure your AWS credentials using the AWS configure command (see [Configure the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html)) or find your credentials by navigating to **Command line or programmatic access** within your AWS dashboard and following the directions in the modal window.

23233. Verify that your credentials are working:

2424

2525```bash AWS CLI

from line 28

2828

2929## Install an SDK for accessing Bedrock

3030

31Anthropic's [client SDKs](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) support Bedrock. You can also use an AWS SDK like `boto3` directly.

31Anthropic's [client SDKs](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) support Bedrock. You can also use an AWS SDK such as `boto3` directly.

3232

3333<Tabs>

3434 <Tab title="Python">

from line 56

5656 </Tab>

5757

5858 <Tab title="Java">

59 <CodeGroup>

59 <CodeGroup exclude="shell, python, typescript, csharp, go, php, ruby">

6060 ```groovy Gradle

6161 implementation("com.anthropic:anthropic-java:3.0.0")

6262 implementation("com.anthropic:anthropic-java-bedrock:3.0.0")

from line 130

130130

131131### Subscribe to Anthropic models

132132

133Go to the [AWS Console > Bedrock > Model Access](https://console.aws.amazon.com/bedrock/home?region=us-west-2#/modelaccess) and request access to Anthropic models. Note that Anthropic model availability varies by region. See [AWS documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/models-regions.html) for latest information.

133Go to the [AWS Console > Bedrock > Model Access](https://console.aws.amazon.com/bedrock/home?region=us-west-2#/modelaccess) and request access to Anthropic models. Note that Anthropic model availability varies by region. See the [AWS documentation on model availability by region](https://docs.aws.amazon.com/bedrock/latest/userguide/models-regions.html) for the latest information.

134134

135135#### API model IDs

136136

from line 146

146146Invocation of model ID anthropic.claude-sonnet-4-5-20250929-v1:0 with on-demand throughput isn't supported. Retry your request with the ID or ARN of an inference profile that contains this model.

147147```

148148

149To invoke these models, pass an inference profile instead of the base model ID. The inference profile ID is the base model ID with a prefix from a column marked "Yes" in the following table, for example us.anthropic.claude-sonnet-4-5-20250929-v1:0. You can also pass the full inference profile ARN, in the form `arn:aws:bedrock:{region}:{account-id}:inference-profile/{inference-profile-id}`. For AWS's authoritative list of available inference profiles, see [Supported Regions and models for inference profiles](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html). To learn how the prefixes affect routing and pricing, see the [Global versus regional endpoints](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy#global-vs-regional-endpoints) section.

149To call these models, pass an inference profile instead of the base model ID. The inference profile ID is the base model ID with a prefix from a column marked "Yes" in the following table, for example us.anthropic.claude-sonnet-4-5-20250929-v1:0. You can also pass the full inference profile ARN, in the form `arn:aws:bedrock:{region}:{account-id}:inference-profile/{inference-profile-id}`. For AWS's authoritative list of available inference profiles, see [Supported Regions and models for inference profiles](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html). To learn how the prefixes affect routing and pricing, see the [Global versus regional endpoints](https://platform.claude.com/docs/en/build-with-claude/claude-on-amazon-bedrock-legacy#global-vs-regional-endpoints) section.

150150

151151| Model | Base Bedrock model ID | `global` | `us` | `eu` | `jp` | `apac` |

152152| :---------------------------------------------------------------------------------------------------- | :------------------------------------------ | :------- | :--- | :--- | :--- | :----- |

from line 162

162162

163163The following examples show how to print a list of all the Claude models available through Bedrock:

164164

165<CodeGroup>

165<CodeGroup exclude="shell">

166166 ```bash AWS CLI

167167 aws bedrock list-foundation-models --region=us-west-2 --by-provider anthropic --query "modelSummaries[*].modelId"

168168 ```

from line 311

311311<Tabs>

312312 <Tab title="cURL">

313313 <Note>

314 Calling the `InvokeModel` API with AWS credentials requires SigV4 request signing, which the SDKs in the other tabs handle automatically. For a Bedrock endpoint you can call with a self-contained cURL command, see [Claude in Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock#making-your-first-request).

314 Calling the `InvokeModel` API with AWS credentials requires SigV4 request signing, which the SDK handles automatically. For a Bedrock endpoint you can call with a self-contained cURL command, see [Making your first request with Claude in Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock#making-your-first-request).

315315 </Note>

316316 </Tab>

317317

from line 769

769769

770770Claude Fable 5.1, Claude Fable 5, Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5.5, Claude Sonnet 5, Claude Sonnet 4.6, and Claude Haiku 5.5 have a [1M-token context window](https://platform.claude.com/docs/en/build-with-claude/context-windows) on Amazon Bedrock. Other Claude models, including Sonnet 4.5 (deprecated) and Sonnet 4 (deprecated), have a 200k-token context window.

771771

772Bedrock limits request payloads to 20 MB. When sending large documents or many images, you may reach this limit before the token limit.

772Bedrock limits request payloads to 20 MB. When sending large documents or many images, you might reach this limit before the token limit.

773773

774774## Global versus regional endpoints

775775

from line 778

778778* **Global endpoints:** Dynamic routing for maximum availability

779779* **Regional endpoints:** Guaranteed data routing through specific geographic regions

780780

781Regional endpoints include a 10% pricing premium over global endpoints.

781Regional endpoints include a 10 percent pricing premium over global endpoints.

782782

783783<Note>

784784 This applies to Claude Sonnet 4.5 (deprecated) and future models only. Older models (Claude Sonnet 4 (deprecated) and earlier) maintain their existing pricing structures.

from line 790

790790

791791* Provide maximum availability and uptime

792792* Dynamically route requests to regions with available capacity

793* No pricing premium

794* Best for applications where data residency is flexible

793* Carry no pricing premium

794* Work best for applications where data residency is flexible

795795

796796**Regional endpoints (CRIS):**

797797

from line 798

798798* Route traffic through specific geographic regions

799799* Required for data residency and compliance requirements

800800* Available for US, EU, Japan, and Asia-Pacific

801* 10% pricing premium reflects infrastructure costs for dedicated regional capacity

801* 10 percent pricing premium reflects infrastructure costs for dedicated regional capacity

802802

803803### Implementation

804804

from line 809

809809<Tabs>

810810 <Tab title="cURL">

811811 <Note>

812 Calling the `InvokeModel` API with AWS credentials requires SigV4 request signing, which the SDKs in the other tabs handle automatically. For a Bedrock endpoint you can call with a self-contained cURL command, see [Claude in Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock#making-your-first-request).

812 Calling the `InvokeModel` API with AWS credentials requires SigV4 request signing, which the SDK handles automatically. For a Bedrock endpoint you can call with a self-contained cURL command, see [Making your first request with Claude in Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock#making-your-first-request).

813813 </Note>

814814 </Tab>

815815

from line 960

960960<Tabs>

961961 <Tab title="cURL">

962962 <Note>

963 Calling the `InvokeModel` API with AWS credentials requires SigV4 request signing, which the SDKs in the other tabs handle automatically. For a Bedrock endpoint you can call with a self-contained cURL command, see [Claude in Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock#making-your-first-request).

963 Calling the `InvokeModel` API with AWS credentials requires SigV4 request signing, which the SDK handles automatically. For a Bedrock endpoint you can call with a self-contained cURL command, see [Making your first request with Claude in Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock#making-your-first-request).

964964 </Note>

965965 </Tab>

966966

build-with-claude/claude-on-vertex-ai Changed · +7 / -7 lines

from line 390

390390

391391Claude Fable 5.1, Claude Fable 5, Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5.5, Claude Sonnet 5, Claude Sonnet 4.6, and Claude Haiku 5.5 have a [1M-token context window](https://platform.claude.com/docs/en/build-with-claude/context-windows) on Agent Platform. Other Claude models, including Sonnet 4.5 (deprecated) and Sonnet 4 (deprecated), have a 200k-token context window.

392392

393Agent Platform limits request payloads to 30 MB. When sending large documents or many images, you might reach this limit before the token limit.

394394

395395## Global, multi-region, and regional endpoints

396396

from line 400

400400* **Multi-region endpoints:** Dynamic routing within a geographic area (for example, the United States or the European Union) for data residency with high availability

401401* **Regional endpoints:** Guaranteed data routing through specific geographic regions

402402

403Regional and multi-region endpoints include a 10% pricing premium over global endpoints.

403Regional and multi-region endpoints include a 10 percent pricing premium over global endpoints.

404404

405405<Note>

406406 This applies to Claude Sonnet 4.5 (deprecated) and future models only. Older models (Claude Sonnet 4 (deprecated), Opus 4 (deprecated), and earlier) maintain their existing pricing structures.

from line 412

412412

413413* Provide maximum availability and uptime

414414* Dynamically route requests to regions with available capacity

415* No pricing premium

416* Best for applications where data residency is flexible

417* Only supports pay-as-you-go traffic (provisioned throughput requires regional endpoints)

415* Carry no pricing premium

416* Work best for applications where data residency is flexible

417* Only support pay-as-you-go traffic (provisioned throughput requires regional endpoints)

418418

419419**Multi-region endpoints:**

420420

421421* Dynamically route requests across regions within a geographic area (currently `us` and `eu`)

422422* Useful when you need data residency within a broad geography but want higher availability than a single region

423* 10% pricing premium over global endpoints

423* 10 percent pricing premium over global endpoints

424424* Only supports pay-as-you-go traffic (provisioned throughput requires regional endpoints)

425425

426426**Regional endpoints:**

from line 428

428428* Route traffic through specific geographic regions

429429* Required for single-region data residency, strict compliance mandates, or provisioned throughput

430430* Support both pay-as-you-go and provisioned throughput

431* 10% pricing premium reflects infrastructure costs for dedicated regional capacity

431* 10 percent pricing premium reflects infrastructure costs for dedicated regional capacity

432432

433433### Implementation

434434

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

from line 14

1414

1515Claude models run on Anthropic-managed infrastructure. This is a commercial integration for billing and access through AWS. Anthropic is the data processor for inference inputs and outputs. AWS processes billing and identity metadata under the marketplace model. Customers using Claude through Claude Platform on AWS are subject to Anthropic's [data use terms](https://www.anthropic.com/legal).

1616

17Anthropic uses AWS infrastructure to process your API requests, run model inference, and store your workspace content (such as prompts, outputs, files, Skills, and batches). For workspaces created before September 18, 2026, 00:00 UTC, Anthropic might process requests, store data, and run inference outside AWS. In either case, subservices might change without notice. Set the [`inference_geo`](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#data-residency) parameter per request to pin inference to a specific geography.

17Anthropic uses AWS infrastructure to process your API requests, run model inference, and store your workspace content (such as prompts, outputs, files, Skills, and batches). For workspaces created before September 18, 2026, 00:00 UTC, Anthropic might process requests, store data, and run inference outside AWS. In either case, subservices might change without notice. Set the [`inference_geo`](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#data-residency) parameter for each request to pin inference to a specific geography.

1818

1919Claude Platform on AWS follows the same data retention policy as the first-party Claude API. Zero Data Retention (ZDR) is available on request. Contact your Anthropic account representative to enable it for your organization.

2020

from line 45

4545

4646**Which offering are you using?** Claude is available through several distinct products:

4747

48* **Claude Platform on AWS** (this page): The Claude API platform billed through AWS Marketplace. Managed in the [Claude Console](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#using-the-claude-console) and the AWS Console.

48* **Claude Platform on AWS (this page):** The Claude API platform billed through AWS Marketplace. Managed in the [Claude Console](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#using-the-claude-console) and the AWS Console.

4949* **[Claude in Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock):** An AWS-native service. Managed in the Amazon Bedrock console and billed as AWS service usage.

5050* **Claude Enterprise procured through AWS Marketplace:** A [claude.ai](https://claude.ai) plan (the Claude chat product), not an API platform. Managed at claude.ai, and its account and migration behavior differ from what this page describes. See the [Claude Help Center](https://support.claude.com).

5151* **Direct Anthropic accounts:** The first-party Claude API and claude.ai plans billed by Anthropic. Managed in the Claude Console and at claude.ai.

from line 52

5252

5353## Set up your account

5454

55Setting up Claude Platform on AWS happens in four phases: sign up on the AWS Console service page, complete your Anthropic organization setup, note your workspace ID, and sign in to the Claude Console.

55Setting up Claude Platform on AWS takes four phases: sign up on the AWS Console service page, complete your Anthropic organization setup, note your workspace ID, and sign in to the Claude Console.

5656

5757<Note>

5858 Signing up through the AWS Console provisions a new Anthropic organization tied to your AWS account. This organization is separate from any existing organizations your company has with Anthropic, including Claude Enterprise organizations procured through AWS Marketplace. API keys, workspaces, and Claude Console settings from a first-party Anthropic organization don't carry over.

from line 63

6363<Steps>

6464 <Step title="Sign up in the AWS Console">

6565 1. Open the [AWS Console](https://console.aws.amazon.com/) and navigate to the **Claude Platform on AWS** service page.

66 2. Choose **Sign up**.

66 2. Click **Sign up**.

6767 3. On the Sign-up page, review the terms (Anthropic's End User License Agreement, the AWS Privacy Notice, and the AWS Customer Agreement) and select the agreement checkbox.

68 4. Choose **Continue**.

68 4. Click **Continue**.

6969

7070 The page shows a **Sign-up in progress** banner. Stay on the page. Sign-up takes a few minutes while AWS handles the AWS Marketplace subscription for you, then redirects you automatically.

7171

from line 79

7979 <Step title="Set up your Anthropic organization">

8080 After sign-up completes, you're redirected to `platform.claude.com/partner-signup`.

8181

82 1. Enter the email address of your organization's owner and choose **Get started**.

83 2. Check that email inbox for a setup link and follow it. If your browser shows a **Signed in as a different account** page, choose **Log out and continue**.

84 3. Complete the organization details form (organization name, entity type, country, intended use) and choose **Complete setup**.

82 1. Enter the email address of your organization's owner and click **Get started**.

83 2. Check that email inbox for a setup link and follow it. If your browser shows a **Signed in as a different account** page, click **Log out and continue**.

84 3. Complete the organization details form (organization name, entity type, country, intended use) and click **Complete setup**.

8585

86 Completing setup creates your Anthropic organization and accepts Anthropic's Commercial Terms of Service and Usage Policy. The AWS Console service page now shows a left navigation with **Home**, **API keys**, **Quickstart**, and **Workspaces**.

86 Completing setup creates your Anthropic organization and accepts Anthropic's Commercial Terms of Service and Usage Policy. The AWS Console service page now shows a sidebar with **Home**, **API keys**, **Quickstart**, and **Workspaces**.

8787 </Step>

8888

8989 <Step title="Create your workspace and note its ID">

90 After you complete setup, the AWS Console prompts you to create a workspace. See [Workspaces](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#workspaces) for details on region binding, IAM resource scoping, and creating additional workspaces.

90 After you complete setup, the AWS Console prompts you to create a workspace. See [Workspace scoping](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#workspace-scoping) for details on region binding and IAM resource scoping, and [Managing workspaces](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#managing-workspaces) for creating additional workspaces.

9191

9292 Find the workspace ID under **Workspaces** on the AWS Console **Claude Platform on AWS** service page or in the [Claude Console](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#using-the-claude-console). Workspace IDs use the format `wrkspc_` followed by an alphanumeric identifier.

9393 </Step>

from line 95

9595 <Step title="Sign in to the Claude Console">

9696 Access to the Claude Console is federated through AWS IAM:

9797

98 1. Assume an IAM role with the `aws-external-anthropic:AssumeConsole` permission. See [IAM actions for Claude Platform on AWS](https://platform.claude.com/docs/en/api/claude-platform-on-aws-iam-actions#console-access).

98 1. Assume an IAM role with the `aws-external-anthropic:AssumeConsole` permission. See [Console access](https://platform.claude.com/docs/en/api/claude-platform-on-aws-iam-actions#console-access).

9999 2. From the **Claude Platform on AWS** service page, choose **Open Claude Console**. The AWS Console issues a JWT and redirects you to `platform.claude.com`.

100100 3. On first sign-in, you're prompted for an email address. Enter your work email. The platform provisions your Claude Console user just-in-time.

101101

from line 116

116116

117117Once the new organization is running, the differences are concentrated in billing and authentication, which are handled through AWS:

118118

119* **Billing** moves to AWS Marketplace: usage is billed in Claude Consumption Units rather than prepaid credits (see [Billing](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#billing)), and you set spend limits on the Billing page (see [Spend limits](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#spend-limits)). During the transition, billing stays separate: the existing organization continues to be billed as it is today.

120* **Authentication and access** move to AWS: requests authenticate with AWS credentials or with API keys generated in the AWS Console, not the Claude Console (see [Authentication](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#authentication)). Organization membership is managed through AWS IAM rather than the Claude Console (see [Available pages](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#available-pages)), and Anthropic's client SDKs provide platform-specific client classes (see [Install an SDK](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#install-an-sdk)).

119* **Billing** moves to AWS Marketplace: usage is billed in Claude Consumption Units rather than prepaid credits (see [Billing](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#billing)), and you set spend limits on the **Billing** page (see [Spend limits](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#spend-limits)). During the transition, billing stays separate: the existing organization continues to be billed as it is today.

120* **Authentication and access** move to AWS: requests authenticate with AWS credentials or with API keys generated in the AWS Console, not the Claude Console (see [Authentication](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#authentication)). Organization membership is managed through AWS IAM rather than the Claude Console (see [Available pages](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#available-pages)), and the SDK provides a platform-specific client class (see [Install an SDK](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#install-an-sdk)).

121121* **Day-to-day API usage** works the way it does on the first-party Claude API, except where noted in the [feature limitations](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#features-not-supported). Before shifting production traffic, check your rate limits: new organizations are placed on the Start tier, and limit increases go through your Anthropic account representative (see [Rate limits and quotas](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#rate-limits-and-quotas)).

122122

123123For Claude Enterprise (claude.ai) organizations, which behave differently, see the [offering comparison](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#claude-platform-on-aws-vs-amazon-bedrock).

from line 124

124124

125125### Troubleshooting account setup

126126

127* **"Sign-up failed: Failed to enable OutboundWebIdentityFederation":** If you see this banner on first submit, choose **Continue** again. The IAM enablement can take a moment to take effect.

127* **"Sign-up failed: Failed to enable OutboundWebIdentityFederation":** If you see this banner on first submit, click **Continue** again. The IAM enablement can take a moment to take effect.

128128* **No progress indicator during sign-up:** Sign-up takes a few minutes. The page shows a static **Sign-up in progress** banner without a progress bar while AWS provisions your account.

129* **"Signed in as a different account" after following the setup link:** Choose **Log out and continue**. The page reauthenticates you with the email address you entered.

129* **"Signed in as a different account" after following the setup link:** Click **Log out and continue**. The page reauthenticates you with the email address you entered.

130130* **"Not found" message during sign-in:** This message might appear briefly during redirect. You can dismiss it.

131131* **Usage page shows no data after your first API call:** Usage data can take a few minutes to appear in the Claude Console.

132132* **"Outbound web identity federation is disabled" on your first API call:** Enable federation once per account. See [Enable outbound web identity federation](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#enable-outbound-web-identity-federation).

from line 143

143143

144144### Enable outbound web identity federation

145145

146The Claude Platform on AWS gateway calls `sts:GetWebIdentityToken` server-side to mint a JWT it forwards to Anthropic. This STS capability is **disabled by default** on every AWS account. Enable it once per account:

147147

148148```bash CLI

149149aws iam enable-outbound-web-identity-federation

from line 197

197197

198198For simpler integration paths (local development and scripts), you can authenticate with an API key instead of SigV4. Set the `ANTHROPIC_AWS_API_KEY` environment variable or pass `api_key` (typescript, php: `apiKey`; go: `APIKey`; java: `.apiKey()`; csharp: `AwsClientOptions.ApiKey`) when you create the client.

199199

200Generate API keys in the **AWS Console** under **Claude Platform on AWS → API keys**. Choose **Generate a key**, then copy the key value. Grant the `aws-external-anthropic:CallWithBearerToken` IAM action to the principals that should be allowed to use API key authentication.

200Generate API keys in the **AWS Console** under **Claude Platform on AWS → API keys**. Click **Generate a key**, then copy the key value. Grant the `aws-external-anthropic:CallWithBearerToken` IAM action to the principals that should be allowed to use API key authentication.

201201

202202<Note>

203 API keys for Claude Platform on AWS are managed in the AWS Console, not the Claude Console. Keys created in the standard [Claude Console](https://platform.claude.com/) (for first-party API access) don't work with the Claude Platform on AWS endpoint.

203 API keys for Claude Platform on AWS are managed in the AWS Console, not the Claude Console. Keys created in the standard Claude Console at [platform.claude.com](https://platform.claude.com) (for first-party API access) don't work with the Claude Platform on AWS endpoint.

204204</Note>

205205

206206#### Short-term API keys

from line 337

337337</Tabs>

338338

339339<Note>

340 SDK clients for Claude Platform on AWS are in beta.

340 The SDK client for Claude Platform on AWS is in beta.

341341</Note>

342342

343343## Available models

from line 600

600600 The AWS region your workspace is bound to controls which gateway endpoint you call and where AWS-side resources (IAM, CloudTrail, billing) are scoped. It does not pin where model inference runs. To pin inference to a specific geography, set `inference_geo` on each request or configure a workspace default.

601601</Note>

602602

603Set the inference geography per request with the `inference_geo` parameter:

603Set the inference geography for each request with the `inference_geo` parameter:

604604

605605<Note>

606606 The `inference_geo` parameter is supported on Claude 4.6 and later models. Requests with `inference_geo` on Claude Opus 4.5, Claude Sonnet 4.5 (deprecated), or Claude Haiku 4.5 return a 400 error. See [Data residency](https://platform.claude.com/docs/en/manage-claude/data-residency) for model availability details.

from line 772

772772

773773### Workspace scoping

774774

775Workspaces are bound to a single AWS region. A workspace created in `us-west-2` can only be accessed through the `us-west-2` endpoint. Usage, quotas, cost, files, batches, and Skills all roll up per workspace, giving you per-region breakdowns in the Claude Console.

775Workspaces are bound to a single AWS region. A workspace created in `us-west-2` can only be accessed through the `us-west-2` endpoint. Usage, quotas, cost, files, batches, and Skills all roll up by workspace, giving you per-region breakdowns in the Claude Console.

776776

777777Workspaces also serve as the primary IAM resource for Claude Platform on AWS. You grant or deny access to specific workspaces through AWS IAM policies using the workspace ARN. The ARN's resource segment is the same `wrkspc_`-prefixed ID you pass in the `anthropic-workspace-id` header:

778778

from line 800

800800

801801Access to the Claude Console is federated through AWS IAM. See [Set up your account](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#set-up-your-account) for the full first-time sign-in flow. In short:

802802

8031. Assume an IAM role with the `aws-external-anthropic:AssumeConsole` permission. See [IAM actions for Claude Platform on AWS](https://platform.claude.com/docs/en/api/claude-platform-on-aws-iam-actions#console-access).

8031. Assume an IAM role with the `aws-external-anthropic:AssumeConsole` permission. See [Console access](https://platform.claude.com/docs/en/api/claude-platform-on-aws-iam-actions#console-access).

8048042. Navigate to the Claude Platform on AWS page in the [AWS Console](https://console.aws.amazon.com/).

8053. Choose **Open Claude Console**. The AWS Console issues a JWT and redirects you to `platform.claude.com`.

8053. Click **Open Claude Console**. The AWS Console issues a JWT and redirects you to `platform.claude.com`.

8068064. On first sign-in, you're prompted for an email address. Enter your work email. The platform provisions your Claude Console user just-in-time.

807807

808808Two Claude Console roles are available: **Admin** and **Developer**. The Admin role grants access to all Claude Console pages and settings available for Claude Platform on AWS. The Developer role grants read access to usage, cost, rate limit, and workspace information. Contact your Anthropic account representative to assign the Admin or Developer role to a principal.

from line 809

809809

810810### Available pages

811811

812The **Through AWS gateway** column indicates whether the page reads and writes data through the AWS gateway (and is therefore governed by [IAM actions](https://platform.claude.com/docs/en/api/claude-platform-on-aws-iam-actions)). Pages marked **No** read organization-level metadata directly from Anthropic and bypass IAM action checks.

812The **Through AWS gateway** column indicates whether the page reads and writes data through the AWS gateway (and is therefore governed by [IAM actions for Claude Platform on AWS](https://platform.claude.com/docs/en/api/claude-platform-on-aws-iam-actions)). Pages marked **No** read organization-level metadata directly from Anthropic and bypass IAM action checks.

813813

815| --------------------- | ------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

816| **Usage** | Yes | No | View token usage by model, workspace, and dimension. Data can take a few minutes to appear after a request. |

817| **Cost** | Yes | No | View cost breakdowns by model and workspace. AWS Cost Explorer shows the aggregated [Claude Consumption Unit (CCU)](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#billing) line item. |

818| **Rate limits** | Yes | No | View rate limits (read-only). Tier increases go through your Anthropic account representative; see [Rate limits and quotas](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#rate-limits-and-quotas). |

819| **Workspaces** | Yes | Yes (except spend limits) | View per-region workspaces. With the Admin role, you can also create, rename, and archive workspaces, and set per-workspace [spend limits](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#spend-limits). |

820| **Encryption keys** | Yes | Yes | A section of the [Data retention](https://platform.claude.com/settings/privacy#encryption-keys) page (`platform.claude.com/settings/privacy`) in the Claude Console, shown while **Organization** is selected in the dropdown menu at the top of the page. Register AWS KMS keys for [CMEK](https://platform.claude.com/docs/en/manage-claude/cmek-claude-platform-on-aws) there (Admin role). To attach a registered key to a workspace, select the workspace from that dropdown menu, then select the key under **Encryption key**. |

821| **Files** | Yes | Yes | View and manage uploaded files. |

822| **Skills** | Yes | Yes | View and manage Agent Skills. |

823| **Batches** | Yes | Yes | View and manage batch processing jobs. |

824| **Agents** | Yes | Yes | View and manage agent definitions. |

825| **Sessions** | Yes | Yes | View agent sessions and event history. |

826| **Environments** | Yes | Yes | View and manage cloud sandbox configurations for sessions. |

827| **Credential vaults** | Yes | Yes | View and manage credential vaults for session authentication. |

828| **Memory stores** | Yes | Yes | View and manage persistent agent memory. |

829| **Webhooks** | Yes | Yes | View and manage webhook endpoints. |

830| **API keys** | No | N/A | Manage API keys in the AWS Console (**Claude Platform on AWS → API keys**). See [API key authentication](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#api-key-authentication). |

831| **Members** | No | N/A | Not applicable. AWS IAM manages access. |

832| **Billing** | Yes (limited) | No | Set an organization monthly spend limit; see [Spend limits](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#spend-limits). AWS Marketplace manages invoicing. View cost breakdowns on the Cost page. |

833| **Claude Code** | No | N/A | View Claude Code usage on the Usage page. |

816| **Usage** | Yes | No | View token usage by model, workspace, and dimension. Data can take a few minutes to appear after a request. |

820| **Encryption keys** | Yes | Yes | A section of the [Data retention](https://platform.claude.com/settings/privacy#encryption-keys) page (`platform.claude.com/settings/privacy`) in the Claude Console, shown while **Organization** is selected in the dropdown menu at the top of the page. Register AWS KMS keys there (Admin role), as described in [Set up CMEK on Claude Platform on AWS](https://platform.claude.com/docs/en/manage-claude/cmek-claude-platform-on-aws). To attach a registered key to a workspace, select the workspace from that dropdown menu, then select the key under **Encryption key**. |