One read of Claude Developer Platformapi-20260814T043121Z
565 pages moved out of 565 read.
Pages moved
565
significant first
Pages read
565
in this capture
Captured
04:31 UTC
Corpus hash
764ab7e8e96e
full baseline · corpus-hash
What this read moved
401-425 of 565, page 17 of 23This capture is too large to show at once. Changes 401-425 of 565 are below, significant first; the rest are on the following screens.
api/compliance/organizations/settings First recorded · 629 lines, first recorded
# Settings ## Get effective organization settings ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Domain Types ### Setting Retrieve Response
The first capture of this source. The page was already there, and this is what it said.
---
title: Settings
url: https://platform.claude.com/docs/en/api/compliance/organizations/settings
---
# Settings
## Get effective organization settings
**get** `/v1/compliance/organizations/{organization_id}/settings`
Retrieve the effective settings for an organization.
Returns the settings currently in force for the given organization — the
enforced state after all policies are applied, which may differ from what
is configured in the admin console. Settings an organization's
administrators cannot change (for example, ones controlled by Anthropic
policy or not available to the organization) are omitted from the list.
The organization must belong to the API key's organization hierarchy;
unknown organizations and organizations outside the hierarchy return 404.
### Path Parameters
- `organization_id: string`
The organization's UUID
### Header Parameters
- `"x-api-key": optional string`
### Returns
- `api_keys: array of object { id, created_at, created_by_id, 5 more }`
Compliance API keys configured for the organization hierarchy, ordered by creation time ascending. Key secret values are never included.
- `id: string`
Unique identifier for the API key.
- `created_at: string`
When the key was created.
- `created_by_id: string or null`
Identifier of the user who created the key, or null when the key was created by automation or its creator's account no longer exists.
- `is_active: boolean`
Whether the key is currently active. A deactivated key is listed for audit visibility but cannot authenticate requests.
- `name: string`
The name given to the API key when it was created.
- `scopes: array of string`
The permission scopes granted to the key.
- `expires_at: optional string or null`
When the key will stop authenticating, or null when the key does not expire.
- `type: optional "compliance_api_key"`
- `"compliance_api_key"`
- `organization_id: string`
- `settings: array of object { name, value, type } or object { name, value, type } or object { name, value, type } or 3 more`
- `Boolean object { name, value, type }`
A setting whose enforced value is a single true/false flag.
- `name: "ai_powered_artifacts_enabled" or "api_workbench_feedback_collection_enabled" or "artifact_connectors_enabled" or 43 more`
- `"ai_powered_artifacts_enabled"`
- `"api_workbench_feedback_collection_enabled"`
- `"artifact_connectors_enabled"`
- `"ask_your_org_enabled"`
- `"chat_enabled"`
- `"claude_ai_chat_sharing_enabled"`
- `"claude_ai_feedback_collection_enabled"`
- `"claude_ai_integration_sharing_enabled"`
- `"claude_code_desktop_bypass_permissions_enabled"`
- `"claude_code_desktop_enabled"`
- `"claude_code_fast_mode_enabled"`
- `"claude_code_metrics_logging_enabled"`
- `"claude_code_remote_control_enabled"`
- `"claude_code_review_enabled"`
- `"claude_code_routines_enabled"`
- `"claude_code_security_enabled"`
- `"claude_code_trusted_devices_required"`
- `"claude_code_web_enabled"`
- `"claude_code_workflows_enabled"`
- `"claude_design_enabled"`
- `"claude_in_slack_enabled"`
- `"code_execution_enabled"`
- `"code_execution_network_egress_enabled"`
- `"connector_tools_default_always_allow"`
- `"content_redaction_enabled"`
- `"cowork_trusted_devices_required"`
- `"desktop_extension_allowlist_enabled"`
- `"directory_sync_enabled"`
- `"frontier_data_use_enabled"`
- `"hipaa_compliance_enabled"`
- `"inline_visualizations_enabled"`
- `"ip_allowlist_enabled"`
- `"location_metadata_enabled"`
- `"member_usage_dashboard_visible"`
- `"memory_enabled"`
- `"org_wide_skill_sharing_enabled"`
- `"public_projects_enabled"`
- `"skill_sharing_enabled"`
- `"skills_enabled"`
- `"sso_claude_ai_enforced"`
- `"sso_console_enforced"`
- `"sso_enabled"`
- `"third_party_interactive_content_enabled"`
- `"user_skill_creation_enabled"`
- `"web_search_enabled"`
- `"work_across_apps_enabled"`
- `value: boolean`
- `type: optional "boolean"`
- `"boolean"`
- `Integer object { name, value, type }`
A setting whose enforced value is a whole number; null means no limit
is in force.
- `name: "account_session_duration_seconds"`
- `"account_session_duration_seconds"`
- `value: number or null`
- `type: optional "integer"`
- `"integer"`
- `String object { name, value, type }`
A setting whose enforced value is a single string; null means no value
is configured.
- `name: "claude_code_default_worker_environment_id" or "claude_code_default_worker_pool_id"`
- `"claude_code_default_worker_environment_id"`
- `"claude_code_default_worker_pool_id"`
- `value: string or null`
- `type: optional "string"`
- `"string"`
- `StringList object { name, value, type }`
A setting whose enforced value is a list of strings.
- `name: "allowed_invite_domains" or "disabled_admin_request_types" or "ip_allowlist_ip_ranges"`
- `"allowed_invite_domains"`
- `"disabled_admin_request_types"`
- `"ip_allowlist_ip_ranges"`
- `value: array of string`
- `type: optional "string_list"`
- `"string_list"`
- `ProvisioningMode object { value, name, type }`
How organization members are provisioned, resolved to the enforced mode.
A configured mode is reported only while the mechanism that enforces it is
active: just-in-time modes require single sign-on to be enabled, and SCIM
modes require directory sync to be enabled. Otherwise `login_only` is
reported, regardless of any stored configuration.
- `value: "jit_advanced" or "jit_permissive" or "login_only" or 2 more`
How organization members are provisioned under SSO.
- `"jit_advanced"`
- `"jit_permissive"`
- `"login_only"`
- `"scim_advanced"`
- `"scim_permissive"`
- `name: optional "sso_provisioning_mode"`
- `"sso_provisioning_mode"`
- `type: optional "provisioning_mode"`
- `"provisioning_mode"`
- `DataRetention object { value, name, type }`
The data retention periods in force, keyed by the type of data they
apply to.
A key of `all` covers every data type and is exclusive: when present it
is the only key. A missing key means no organization-level
administrator-configured retention period is in force for that data type;
Anthropic's service defaults may still apply.
- `value: map[object { duration, timescale, type } or object { type } ]`
- `Fixed object { duration, timescale, type }`
A fixed retention window measured from each item's last activity.
- `duration: number`
- `timescale: "day" or "month"`
- `"day"`
- `"month"`
- `type: optional "fixed"`
- `"fixed"`
- `Indefinite object { type }`
An indefinite retention period: data is kept with no time limit.
- `type: optional "indefinite"`
- `"indefinite"`
- `name: optional "data_retention_periods"`
- `"data_retention_periods"`
- `type: optional "data_retention"`
Cut at 300 lines. The page has the rest.
api/compliance/organizations/settings/retrieve First recorded · 341 lines, first recorded
## Get effective organization settings ### Path Parameters ### Header Parameters ### Returns ### Example #### Response
The first capture of this source. The page was already there, and this is what it said.
---
title: Get effective organization settings
url: https://platform.claude.com/docs/en/api/compliance/organizations/settings/retrieve
---
## Get effective organization settings
**get** `/v1/compliance/organizations/{organization_id}/settings`
Retrieve the effective settings for an organization.
Returns the settings currently in force for the given organization — the
enforced state after all policies are applied, which may differ from what
is configured in the admin console. Settings an organization's
administrators cannot change (for example, ones controlled by Anthropic
policy or not available to the organization) are omitted from the list.
The organization must belong to the API key's organization hierarchy;
unknown organizations and organizations outside the hierarchy return 404.
### Path Parameters
- `organization_id: string`
The organization's UUID
### Header Parameters
- `"x-api-key": optional string`
### Returns
- `api_keys: array of object { id, created_at, created_by_id, 5 more }`
Compliance API keys configured for the organization hierarchy, ordered by creation time ascending. Key secret values are never included.
- `id: string`
Unique identifier for the API key.
- `created_at: string`
When the key was created.
- `created_by_id: string or null`
Identifier of the user who created the key, or null when the key was created by automation or its creator's account no longer exists.
- `is_active: boolean`
Whether the key is currently active. A deactivated key is listed for audit visibility but cannot authenticate requests.
- `name: string`
The name given to the API key when it was created.
- `scopes: array of string`
The permission scopes granted to the key.
- `expires_at: optional string or null`
When the key will stop authenticating, or null when the key does not expire.
- `type: optional "compliance_api_key"`
- `"compliance_api_key"`
- `organization_id: string`
- `settings: array of object { name, value, type } or object { name, value, type } or object { name, value, type } or 3 more`
- `Boolean object { name, value, type }`
A setting whose enforced value is a single true/false flag.
- `name: "ai_powered_artifacts_enabled" or "api_workbench_feedback_collection_enabled" or "artifact_connectors_enabled" or 43 more`
- `"ai_powered_artifacts_enabled"`
- `"api_workbench_feedback_collection_enabled"`
- `"artifact_connectors_enabled"`
- `"ask_your_org_enabled"`
- `"chat_enabled"`
- `"claude_ai_chat_sharing_enabled"`
- `"claude_ai_feedback_collection_enabled"`
- `"claude_ai_integration_sharing_enabled"`
- `"claude_code_desktop_bypass_permissions_enabled"`
- `"claude_code_desktop_enabled"`
- `"claude_code_fast_mode_enabled"`
- `"claude_code_metrics_logging_enabled"`
- `"claude_code_remote_control_enabled"`
- `"claude_code_review_enabled"`
- `"claude_code_routines_enabled"`
- `"claude_code_security_enabled"`
- `"claude_code_trusted_devices_required"`
- `"claude_code_web_enabled"`
- `"claude_code_workflows_enabled"`
- `"claude_design_enabled"`
- `"claude_in_slack_enabled"`
- `"code_execution_enabled"`
- `"code_execution_network_egress_enabled"`
- `"connector_tools_default_always_allow"`
- `"content_redaction_enabled"`
- `"cowork_trusted_devices_required"`
- `"desktop_extension_allowlist_enabled"`
- `"directory_sync_enabled"`
- `"frontier_data_use_enabled"`
- `"hipaa_compliance_enabled"`
- `"inline_visualizations_enabled"`
- `"ip_allowlist_enabled"`
- `"location_metadata_enabled"`
- `"member_usage_dashboard_visible"`
- `"memory_enabled"`
- `"org_wide_skill_sharing_enabled"`
- `"public_projects_enabled"`
- `"skill_sharing_enabled"`
- `"skills_enabled"`
- `"sso_claude_ai_enforced"`
- `"sso_console_enforced"`
- `"sso_enabled"`
- `"third_party_interactive_content_enabled"`
- `"user_skill_creation_enabled"`
- `"web_search_enabled"`
- `"work_across_apps_enabled"`
- `value: boolean`
- `type: optional "boolean"`
- `"boolean"`
- `Integer object { name, value, type }`
A setting whose enforced value is a whole number; null means no limit
is in force.
- `name: "account_session_duration_seconds"`
- `"account_session_duration_seconds"`
- `value: number or null`
- `type: optional "integer"`
- `"integer"`
- `String object { name, value, type }`
A setting whose enforced value is a single string; null means no value
is configured.
- `name: "claude_code_default_worker_environment_id" or "claude_code_default_worker_pool_id"`
- `"claude_code_default_worker_environment_id"`
- `"claude_code_default_worker_pool_id"`
- `value: string or null`
- `type: optional "string"`
- `"string"`
- `StringList object { name, value, type }`
A setting whose enforced value is a list of strings.
- `name: "allowed_invite_domains" or "disabled_admin_request_types" or "ip_allowlist_ip_ranges"`
- `"allowed_invite_domains"`
- `"disabled_admin_request_types"`
- `"ip_allowlist_ip_ranges"`
- `value: array of string`
- `type: optional "string_list"`
- `"string_list"`
- `ProvisioningMode object { value, name, type }`
How organization members are provisioned, resolved to the enforced mode.
A configured mode is reported only while the mechanism that enforces it is
active: just-in-time modes require single sign-on to be enabled, and SCIM
modes require directory sync to be enabled. Otherwise `login_only` is
reported, regardless of any stored configuration.
- `value: "jit_advanced" or "jit_permissive" or "login_only" or 2 more`
How organization members are provisioned under SSO.
- `"jit_advanced"`
- `"jit_permissive"`
- `"login_only"`
- `"scim_advanced"`
- `"scim_permissive"`
- `name: optional "sso_provisioning_mode"`
- `"sso_provisioning_mode"`
- `type: optional "provisioning_mode"`
- `"provisioning_mode"`
- `DataRetention object { value, name, type }`
The data retention periods in force, keyed by the type of data they
apply to.
A key of `all` covers every data type and is exclusive: when present it
is the only key. A missing key means no organization-level
administrator-configured retention period is in force for that data type;
Anthropic's service defaults may still apply.
- `value: map[object { duration, timescale, type } or object { type } ]`
- `Fixed object { duration, timescale, type }`
A fixed retention window measured from each item's last activity.
- `duration: number`
- `timescale: "day" or "month"`
- `"day"`
- `"month"`
- `type: optional "fixed"`
- `"fixed"`
- `Indefinite object { type }`
An indefinite retention period: data is kept with no time limit.
- `type: optional "indefinite"`
- `"indefinite"`
- `name: optional "data_retention_periods"`
- `"data_retention_periods"`
- `type: optional "data_retention"`
- `"data_retention"`
Cut at 300 lines. The page has the rest.
api/compliance/organizations/users First recorded · 155 lines, first recorded
# Users ## List organization users ### Path Parameters ### Query Parameters ### Header Parameters ### Returns ### Example #### Response ## Domain Types ### User List Response
The first capture of this source. The page was already there, and this is what it said.
---
title: Users
url: https://platform.claude.com/docs/en/api/compliance/organizations/users
---
# Users
## List organization users
**get** `/v1/compliance/organizations/{org_uuid}/users`
List current user members of an organization.
### Path Parameters
- `org_uuid: string`
The organization UUID
### Query Parameters
- `limit: optional number`
Maximum results (default: 500, max: 1000)
- `page: optional string`
Opaque pagination token from a previous response's `next_page` field. Pass this to retrieve the next page of results. Clients should treat this value as an opaque string and not attempt to parse or interpret its contents, as the format may change without notice.
### Header Parameters
- `"x-api-key": optional string`
### Returns
- `data: array of object { id, created_at, email, 2 more }`
List of current organization members sorted by organization join date ascending
- `id: string`
User identifier (tagged ID)
- `created_at: string`
User account creation timestamp
- `email: string`
User's current email address
- `full_name: string`
User's current full name
- `organization_role: "admin" or "billing" or "claude_code_user" or 6 more`
User's built-in role within the organization. This is distinct from any custom RBAC roles that may also be assigned.
- `"admin"`
- `"billing"`
- `"claude_code_user"`
- `"developer"`
- `"managed"`
- `"membership_admin"`
- `"owner"`
- `"primary_owner"`
- `"user"`
- `has_more: boolean`
Whether more records exist beyond the current result set
- `next_page: string or null`
Token to retrieve the next page. Use this as the 'page' parameter in your next request
### Example
```http
curl https://api.anthropic.com/v1/compliance/organizations/$ORG_UUID/users \
-H "Authorization: Bearer $ANTHROPIC_COMPLIANCE_API_KEY"
```
#### Response
```json
{
"data": [
{
"id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"created_at": "2025-03-12T18:22:41.123456Z",
"email": "[email protected]",
"full_name": "Jane Doe",
"organization_role": "admin"
}
],
"has_more": true,
"next_page": "cGFnZV90b2tlbl9leGFtcGxlXzE3MzQ1Njc4OTA="
}
```
## Domain Types
### User List Response
- `UserListResponse object { id, created_at, email, 2 more }`
User member information for compliance responses.
- `id: string`
User identifier (tagged ID)
- `created_at: string`
User account creation timestamp
- `email: string`
User's current email address
- `full_name: string`
User's current full name
- `organization_role: "admin" or "billing" or "claude_code_user" or 6 more`
User's built-in role within the organization. This is distinct from any custom RBAC roles that may also be assigned.
- `"admin"`
- `"billing"`
- `"claude_code_user"`
- `"developer"`
- `"managed"`
- `"membership_admin"`
- `"owner"`
- `"primary_owner"`
- `"user"`
api/compliance/organizations/users/list First recorded · 107 lines, first recorded
## List organization users ### Path Parameters ### Query Parameters ### Header Parameters ### Returns ### Example #### Response
The first capture of this source. The page was already there, and this is what it said.
---
title: List organization users
url: https://platform.claude.com/docs/en/api/compliance/organizations/users/list
---
## List organization users
**get** `/v1/compliance/organizations/{org_uuid}/users`
List current user members of an organization.
### Path Parameters
- `org_uuid: string`
The organization UUID
### Query Parameters
- `limit: optional number`
Maximum results (default: 500, max: 1000)
- `page: optional string`
Opaque pagination token from a previous response's `next_page` field. Pass this to retrieve the next page of results. Clients should treat this value as an opaque string and not attempt to parse or interpret its contents, as the format may change without notice.
### Header Parameters
- `"x-api-key": optional string`
### Returns
- `data: array of object { id, created_at, email, 2 more }`
List of current organization members sorted by organization join date ascending
- `id: string`
User identifier (tagged ID)
- `created_at: string`
User account creation timestamp
- `email: string`
User's current email address
- `full_name: string`
User's current full name
- `organization_role: "admin" or "billing" or "claude_code_user" or 6 more`
User's built-in role within the organization. This is distinct from any custom RBAC roles that may also be assigned.
- `"admin"`
- `"billing"`
- `"claude_code_user"`
- `"developer"`
- `"managed"`
- `"membership_admin"`
- `"owner"`
- `"primary_owner"`
- `"user"`
- `has_more: boolean`
Whether more records exist beyond the current result set
- `next_page: string or null`
Token to retrieve the next page. Use this as the 'page' parameter in your next request
### Example
```http
curl https://api.anthropic.com/v1/compliance/organizations/$ORG_UUID/users \
-H "Authorization: Bearer $ANTHROPIC_COMPLIANCE_API_KEY"
```
#### Response
```json
{
"data": [
{
"id": "user_01WCz1FkmYMm4gnmykNKUu3Q",
"created_at": "2025-03-12T18:22:41.123456Z",
"email": "[email protected]",
"full_name": "Jane Doe",
"organization_role": "admin"
}
],
"has_more": true,
"next_page": "cGFnZV90b2tlbl9leGFtcGxlXzE3MzQ1Njc4OTA="
}
```
api/errors First recorded · 504 lines, first recorded
## HTTP errors ## Request size limits ## Error shapes ## SDK error types ## Request ID ## Long requests ## Common validation errors ### Prefill not supported ### Thinking blocks cannot be modified ### Extended thinking not supported ### Adaptive thinking not supported ### Thinking cannot be disabled ### Outbound web identity federation disabled (Claude Platform on AWS) ## Next steps
The first capture of this source. The page was already there, and this is what it said.
---
title: Claude API errors
url: https://platform.claude.com/docs/en/api/errors
description: Understand the HTTP status codes, error response shape, and request IDs the Claude API returns, and handle errors with the SDKs' typed exceptions.
---
## HTTP errors
The API follows a predictable HTTP error code format:
* 400 - `invalid_request_error`: There was an issue with the format or content of your request. This error type may also be used for other 4XX status codes not listed in this section.
* 401 - `authentication_error`: There's an issue with your API key (for example, it's malformed, revoked, or expired; see [Key expiration](https://platform.claude.com/docs/en/manage-claude/authentication#key-expiration)). On Claude Platform on AWS, this can also indicate a problem with your AWS credentials or SigV4 signature.
* 402 - `billing_error`: There's an issue with your billing or payment information. Check your payment details in the [Claude Console](https://platform.claude.com), or in AWS Marketplace if you're using Claude Platform on AWS.
* 403 - `permission_error`: Your API key does not have permission to use the specified resource. Check your organization's access and workspace settings in the [Claude Console](https://platform.claude.com).
* 404 - `not_found_error`: The requested resource was not found. Check the endpoint path and any resource IDs in the request URL.
* 409 - `conflict_error`: The request conflicts with the current state of a resource. For example, the resource was modified concurrently, or a value that must be unique is already in use. Resolve the conflict, then retry the request.
* 413 - `request_too_large`: Request exceeds the maximum allowed number of bytes. See [Request size limits](https://platform.claude.com/docs/en/api/errors#request-size-limits) for per-endpoint maximums.
* 429 - `rate_limit_error`: Your account has hit a rate limit.
* 500 - `api_error`: An unexpected error has occurred internal to Anthropic's systems. Retry the request with exponential backoff; if the error persists, contact support with the [request ID](https://platform.claude.com/docs/en/api/errors#request-id).
* 504 - `timeout_error`: The request timed out while processing. Consider using the [streaming Messages API](https://platform.claude.com/docs/en/build-with-claude/streaming) for long-running requests. See [Long requests](https://platform.claude.com/docs/en/api/errors#long-requests) for more options.
* 529 - `overloaded_error`: The API is temporarily overloaded.
<Warning>
529 errors can occur when the API experiences high traffic across all users.
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.
</Warning>
The official SDKs automatically retry transient failures (such as connection errors, rate limits, and 5xx server errors) with exponential backoff, twice by default, honoring the `retry-after` header when present. Each SDK client accepts a maximum-retries option to configure or disable this behavior.
When receiving a [streaming](https://platform.claude.com/docs/en/build-with-claude/streaming) response over server-sent events (SSE), an error can occur after the API returns a 200 response. In that case, error handling doesn't follow these standard mechanisms. See [Error events](https://platform.claude.com/docs/en/build-with-claude/streaming#error-events) for the shape of mid-stream errors.
## Request size limits
The API enforces request size limits:
| Endpoint type | Maximum request size |
| ----------------------------------------------------------------------------------- | -------------------- |
| Messages API | 32 MB |
| Token Counting API | 32 MB |
| [Batch API](https://platform.claude.com/docs/en/build-with-claude/batch-processing) | 256 MB |
| [Files API](https://platform.claude.com/docs/en/build-with-claude/files) | 500 MB |
If you exceed these limits, you'll receive a 413 `request_too_large` error. On the direct Claude API, Cloudflare returns this error before the request reaches the API servers.
## Error shapes
The API always returns errors as JSON, with a top-level `error` object that always includes a `type` and `message` value. The response also includes a `request_id` field for easier tracking and debugging. For example:
```json JSON
{
"type": "error",
"error": {
"type": "not_found_error",
"message": "The requested resource could not be found."
},
"request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}
```
In accordance with the [versioning](https://platform.claude.com/docs/en/api/versioning) policy, the values within these objects may expand, and it is possible that the `type` values will grow over time.
## SDK error types
The official SDKs raise typed exceptions for these errors instead of returning raw JSON, and the class names and namespaces differ by language. For example, a 404 surfaces as `anthropic.NotFoundError` in Python, `Anthropic::Errors::NotFoundError` in Ruby, `com.anthropic.errors.NotFoundException` in Java, and as a single `*anthropic.Error` value (branch on `StatusCode`) in Go. Catch the SDK's typed classes rather than string-matching error messages, handling the most specific classes first. Each SDK page documents its full exception hierarchy:
* [Python](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/python#handling-errors) · [TypeScript](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/typescript#handling-errors) · [C#](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/csharp#error-handling) · [Go](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/go#error-handling) · [Java](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/java#error-handling) · [PHP](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/php#error-handling) · [Ruby](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/ruby#handling-errors)
## Request ID
Every API response includes a unique `request-id` header. This header contains a value such as `req_018EeWyXxfu5pfWkrYcMdjWG`. The same identifier appears as the `request_id` field in [error response bodies](https://platform.claude.com/docs/en/api/errors#error-shapes). When contacting support about a specific request, include this ID to help quickly resolve your issue.
On [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws), responses include two request IDs: the AWS request ID (`x-amzn-requestid`, primary, indexed in CloudTrail) and the Anthropic request ID (`request-id`, secondary). Use the AWS request ID for CloudTrail lookups and the Anthropic request ID for Anthropic support tickets.
The Python and TypeScript SDKs expose the request ID as a `_request_id` property on top-level response objects. The C#, Go, Java, and PHP SDKs expose it through their raw-response accessors, and the Ruby SDK through [middleware](https://platform.claude.com/docs/en/cli-sdks-libraries/middleware). The same mechanisms, along with `with_raw_response` in Python and `.withResponse()` in TypeScript, read any other [response header](https://platform.claude.com/docs/en/api/overview#response-headers) too, such as `anthropic-organization-id` and [`anthropic-workspace-id`](https://platform.claude.com/docs/en/manage-claude/workspaces#identify-the-workspace-behind-an-api-response). On Claude Platform on AWS, use the raw-response accessor to read the AWS request ID (`x-amzn-requestid`) as well:
<CodeGroup>
```bash cURL
# Print the response headers (including request-id); discard the body
curl -sS -D - -o /dev/null https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-5",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "Hello, Claude"}]
}'
```
```bash CLI
# The request-id header is printed to stderr with --debug:
ant --debug messages create \
--model claude-sonnet-5 \
--max-tokens 1024 \
--message '{role: user, content: "Hello, Claude"}'
```
```python Python
client = anthropic.Anthropic()
message = client.messages.create(
model="claude-sonnet-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(f"Request ID: {message._request_id}")
```
```typescript TypeScript
const client = new Anthropic();
const message = await client.messages.create({
model: "claude-sonnet-5",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello, Claude" }]
});
console.log("Request ID:", message._request_id);
```
```csharp C#
AnthropicClient client = new();
using var response = await client.WithRawResponse.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeSonnet5,
MaxTokens = 1024,
Messages = [new() { Role = Role.User, Content = "Hello, Claude" }]
});
Console.WriteLine($"Request ID: {response.RequestID}");
```
```go Go
client := anthropic.NewClient()
var response *http.Response
_, err := client.Messages.New(
context.Background(),
anthropic.MessageNewParams{
Model: anthropic.ModelClaudeSonnet5,
MaxTokens: 1024,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Hello, Claude")),
},
},
option.WithResponseInto(&response),
)
if err != nil {
panic(err)
}
fmt.Println("Request ID:", response.Header.Get("request-id"))
```
```java Java
import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.core.http.HttpResponseFor;
import com.anthropic.models.messages.Message;
import com.anthropic.models.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
HttpResponseFor<Message> response = client.messages().withRawResponse().create(
MessageCreateParams.builder()
.model(Model.CLAUDE_SONNET_5)
.maxTokens(1024)
.addUserMessage("Hello, Claude")
.build()
);
IO.println("Request ID: " + response.requestId().orElse(null));
}
```
```php PHP
$client = new Client();
$response = $client->messages->raw->create([
'model' => 'claude-sonnet-5',
'maxTokens' => 1024,
'messages' => [['role' => 'user', 'content' => 'Hello, Claude']],
]);
echo 'Request ID: ' . $response->getHeaderLine('request-id') . "\n";
```
```ruby Ruby
client = Anthropic::Client.new
# Read response headers in per-request middleware, which receives the
# raw HTTP response before the SDK parses it
request_id = nil
read_request_id = lambda do |request, call_next|
response = call_next.call(request)
# Keys in response.headers are lowercase
request_id = response.headers["request-id"]
response
end
client.messages.create(
model: Anthropic::Model::CLAUDE_SONNET_5,
max_tokens: 1024,
messages: [{ role: "user", content: "Hello, Claude" }],
request_options: { middleware: [read_request_id] }
)
puts "Request ID: #{request_id}"
```
```python Python (Claude Platform on AWS)
from anthropic import AnthropicAWS
client = AnthropicAWS(aws_region="us-west-2")
response = client.messages.with_raw_response.create(
model="claude-opus-4-8",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(f"AWS request ID: {response.headers.get('x-amzn-requestid')}")
message = response.parse()
print(f"Anthropic request ID: {message._request_id}")
```
```typescript TypeScript (Claude Platform on AWS)
import AnthropicAws from "@anthropic-ai/aws-sdk";
const client = new AnthropicAws({ awsRegion: "us-west-2" });
const { response: raw, request_id } = await client.messages
.create({
model: "claude-opus-4-8",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello, Claude" }]
})
.withResponse();
console.log("AWS request ID:", raw.headers.get("x-amzn-requestid"));
console.log("Anthropic request ID:", request_id);
```
</CodeGroup>
For Claude Platform on AWS request-ID examples in other languages, see [Request IDs](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#request-ids).
## Long requests
<Warning>
Consider 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) for long-running requests, especially those over 10 minutes.
</Warning>
Avoid 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):
* 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.
* 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.
If 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.
The [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.
If you don't need to process events incrementally, the SDKs can consume the stream for you and return the complete `Message` object, identical to what a non-streaming call returns:
<CodeGroup>
```bash cURL
# Raw SSE output requires handling events; there is no single-command way
# to accumulate the final message with curl. Use the SDK examples instead.
```
```bash CLI
# The CLI streams events; --format jsonl emits one event per line
ant messages create --stream --format jsonl <<'YAML'
model: claude-sonnet-5
max_tokens: 128000
messages:
- role: user
content: Write a detailed analysis...
YAML
```
```python Python
client = anthropic.Anthropic()
with client.messages.stream(
max_tokens=128000,
messages=[{"role": "user", "content": "Write a detailed analysis..."}],
model="claude-sonnet-5",
) as stream:
message = stream.get_final_message()
print(next(block.text for block in message.content if block.type == "text"))
```
Cut at 300 lines. The page has the rest.
api/ip-addresses First recorded · 41 lines, first recorded
## Inbound IP addresses ### IPv4 ### IPv6 ## Outbound IP addresses ### IPv4 ### Phased out IP addresses
The first capture of this source. The page was already there, and this is what it said.
---
title: IP addresses
url: https://platform.claude.com/docs/en/api/ip-addresses
description: Anthropic services use fixed IP addresses for both inbound and outbound connections. You can use these addresses to configure your firewall rules for secure access to the Claude API and Console. These addresses will not change without notice.
---
<Note>
**[Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws):** The inbound endpoint (`aws-external-anthropic.{region}.api.aws`) resolves to AWS IP ranges. Outbound tool calls (MCP connector, web search, and web fetch) originate from the Anthropic ranges listed on this page. See the [AWS IP address ranges](https://docs.aws.amazon.com/vpc/latest/userguide/aws-ip-ranges.html) for inbound allowlisting.
</Note>
## Inbound IP addresses
These are the IP addresses where Anthropic services receive incoming connections.
### IPv4
`160.79.104.0/23`
### IPv6
`2607:6bc0::/48`
## Outbound IP addresses
These are the stable IP addresses that Anthropic uses for outbound requests (for example, when making MCP tool calls to external servers).
### IPv4
`160.79.104.0/21`
### Phased out IP addresses
The following IP addresses are no longer in use by Anthropic. If you have previously allowlisted these addresses, you should remove them from your firewall rules.
```text wrap
34.162.46.92/32
34.162.102.82/32
34.162.136.91/32
34.162.142.92/32
34.162.183.95/32
```
api/messages First recorded · 28360 lines, first recorded
# Messages ## Create a Message ### Header Parameters ### Body Parameters ### Returns ### Example #### Response ## Count tokens in a Message ### Header Parameters ### Body Parameters ### Returns ### Example #### Response ## Domain Types ### Base64 Image Source ### Base64 PDF Source ### Bash Code Execution Output Block ### Bash Code Execution Output Block Param ### Bash Code Execution Result Block ### Bash Code Execution Result Block Param ### Bash Code Execution Tool Result Block ### Bash Code Execution Tool Result Block Param ### Bash Code Execution Tool Result Error ### Bash Code Execution Tool Result Error Code ### Bash Code Execution Tool Result Error Param ### Cache Control Ephemeral ### Cache Creation ### Citation Char Location ### Citation Char Location Param ### Citation Content Block Location ### Citation Content Block Location Param ### Citation Page Location ### Citation Page Location Param ### Citation Search Result Location Param ### Citation Web Search Result Location Param ### Citations Config ### Citations Config Param ### Citations Delta ### Citations Search Result Location ### Citations Web Search Result Location ### Code Execution Output Block ### Code Execution Output Block Param ### Code Execution Result Block ### Code Execution Result Block Param ### Code Execution Tool 20250522 ### Code Execution Tool 20250825 ### Code Execution Tool 20260120 ### Code Execution Tool 20260521 ### Code Execution Tool Result Block ### Code Execution Tool Result Block Content ### Code Execution Tool Result Block Param ### Code Execution Tool Result Block Param Content ### Code Execution Tool Result Error ### Code Execution Tool Result Error Code ### Code Execution Tool Result Error Param ### Container ### Container Upload Block ### Container Upload Block Param ### Content Block ### Content Block Param ### Content Block Source ### Content Block Source Content ### Direct Caller ### Document Block ### Document Block Param ### Encrypted Code Execution Result Block ### Encrypted Code Execution Result Block Param ### Image Block Param ### Input JSON Delta ### JSON Output Format ### Memory Tool 20250818 ### Message ### Message Count Tokens Tool ### Message Delta Usage ### Message Param ### Message Tokens Count ### Metadata ### Mid Conversation System Block Param ### Model ### Output Config ### Output Tokens Details ### Plain Text Source ### Raw Content Block Delta ### Raw Content Block Delta Event ### Raw Content Block Start Event ### Raw Content Block Stop Event ### Raw Message Delta Event ### Raw Message Start Event ### Raw Message Stop Event ### Raw Message Stream Event ### Redacted Thinking Block ### Redacted Thinking Block Param ### Refusal Stop Details ### Search Result Block Param ### Server Tool Caller ### Server Tool Caller 20260120 ### Server Tool Usage ### Server Tool Use Block ### Server Tool Use Block Param ### Signature Delta ### Stop Reason ### Text Block ### Text Block Param ### Text Citation ### Text Citation Param ### Text Delta ### Text Editor Code Execution Create Result Block ### Text Editor Code Execution Create Result Block Param ### Text Editor Code Execution Str Replace Result Block ### Text Editor Code Execution Str Replace Result Block Param ### Text Editor Code Execution Tool Result Block ### Text Editor Code Execution Tool Result Block Param ### Text Editor Code Execution Tool Result Error ### Text Editor Code Execution Tool Result Error Code ### Text Editor Code Execution Tool Result Error Param ### Text Editor Code Execution View Result Block ### Text Editor Code Execution View Result Block Param ### Thinking Block ### Thinking Block Param ### Thinking Config Adaptive ### Thinking Config Disabled ### Thinking Config Enabled ### Thinking Config Param ### Thinking Delta ### Tool ### Tool Bash 20250124 ### Tool Choice ### Tool Choice Any ### Tool Choice Auto ### Tool Choice None ### Tool Choice Tool ### Tool Reference Block ### Tool Reference Block Param ### Tool Result Block Param ### Tool Search Tool Bm25 20251119 ### Tool Search Tool Regex 20251119 ### Tool Search Tool Result Block ### Tool Search Tool Result Block Param ### Tool Search Tool Result Error ### Tool Search Tool Result Error Code ### Tool Search Tool Result Error Param ### Tool Search Tool Search Result Block ### Tool Search Tool Search Result Block Param ### Tool Text Editor 20250124 ### Tool Text Editor 20250429 ### Tool Text Editor 20250728 ### Tool Union ### Tool Use Block ### Tool Use Block Param ### URL Image Source ### URL PDF Source ### Usage ### User Location ### Web Fetch Block ### Web Fetch Block Param ### Web Fetch Tool 20250910 ### Web Fetch Tool 20260209 ### Web Fetch Tool 20260309 ### Web Fetch Tool 20260318 ### Web Fetch Tool Result Block ### Web Fetch Tool Result Block Param ### Web Fetch Tool Result Error Block ### Web Fetch Tool Result Error Block Param ### Web Fetch Tool Result Error Code ### Web Search Result Block ### Web Search Result Block Param ### Web Search Tool 20250305 ### Web Search Tool 20260209 ### Web Search Tool 20260318 ### Web Search Tool Request Error ### Web Search Tool Result Block ### Web Search Tool Result Block Content ### Web Search Tool Result Block Param ### Web Search Tool Result Block Param Content ### Web Search Tool Result Error ### Web Search Tool Result Error Code # Batches ## Create a Message Batch ### Header Parameters ### Body Parameters ### Returns ### Example #### Response ## Retrieve a Message Batch ### Path Parameters ### Returns ### Example #### Response ## List Message Batches ### Query Parameters ### Returns ### Example #### Response ## Cancel a Message Batch ### Path Parameters ### Returns ### Example #### Response ## Delete a Message Batch ### Path Parameters ### Returns ### Example #### Response ## Retrieve Message Batch results ### Path Parameters ### Returns ### Example ## Domain Types ### Deleted Message Batch ### Message Batch ### Message Batch Canceled Result ### Message Batch Errored Result ### Message Batch Expired Result ### Message Batch Individual Response ### Message Batch Request Counts ### Message Batch Result ### Message Batch Succeeded Result
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
The first capture of this source. The page was already there, and this is what it said.
---
title: Messages
url: https://platform.claude.com/docs/en/api/messages
---
# Messages
## Create a Message
**post** `/v1/messages`
Send a structured list of input messages with text and/or image content, and the model will generate the next message in the conversation.
The Messages API can be used for either single queries or stateless multi-turn conversations.
Learn more about the Messages API in our [user guide](https://platform.claude.com/docs/en/get-started)
### Header Parameters
- `"anthropic-user-profile-id": optional string`
The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. Requires the `user-profiles` beta header.
### Body Parameters
- `max_tokens: number`
The maximum number of tokens to generate before stopping.
Note that our models may stop _before_ reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate.
Set to `0` to populate the [prompt cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pre-warming-the-cache) without generating a response.
Different models have different maximum values for this parameter. See [models](https://platform.claude.com/docs/en/about-claude/models/overview) for details.
- `messages: array of MessageParam`
Input messages.
Our models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn.
Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages.
If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response.
Example with a single `user` message:
```json
[{"role": "user", "content": "Hello, Claude"}]
```
Example with multiple conversational turns:
```json
[
{"role": "user", "content": "Hello there."},
{"role": "assistant", "content": "Hi, I'm Claude. How can I help you?"},
{"role": "user", "content": "Can you explain LLMs in plain English?"},
]
```
Example with a partially-filled response from Claude:
```json
[
{"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"},
{"role": "assistant", "content": "The best answer is ("},
]
```
Each input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `"text"`. The following input messages are equivalent:
```json
{"role": "user", "content": "Hello, Claude"}
```
```json
{"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]}
```
See [input examples](https://platform.claude.com/docs/en/build-with-claude/working-with-messages).
Note that if you want to include a [system prompt](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role), you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API.
There is a limit of 100,000 messages in a single request.
- `content: string or array of ContentBlockParam`
- `string`
- `array of ContentBlockParam`
- `TextBlockParam object { text, type, cache_control, citations }`
- `text: string`
- `type: "text"`
- `"text"`
- `cache_control: optional CacheControlEphemeral or null`
Create a cache control breakpoint at this content block.
- `type: "ephemeral"`
- `"ephemeral"`
- `ttl: optional "5m" or "1h"`
The time-to-live for the cache control breakpoint.
This may be one the following values:
- `5m`: 5 minutes
- `1h`: 1 hour
Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) for details.
- `"5m"`
- `"1h"`
- `citations: optional array of TextCitationParam or null`
- `CitationCharLocationParam object { cited_text, document_index, document_title, 3 more }`
- `cited_text: string`
- `document_index: number`
- `document_title: string or null`
- `end_char_index: number`
- `start_char_index: number`
- `type: "char_location"`
- `"char_location"`
- `CitationPageLocationParam object { cited_text, document_index, document_title, 3 more }`
- `cited_text: string`
- `document_index: number`
- `document_title: string or null`
- `end_page_number: number`
- `start_page_number: number`
- `type: "page_location"`
- `"page_location"`
- `CitationContentBlockLocationParam object { cited_text, document_index, document_title, 3 more }`
- `cited_text: string`
The full text of the cited block range, concatenated.
Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns.
- `document_index: number`
- `document_title: string or null`
- `end_block_index: number`
Exclusive 0-based end index of the cited block range in the source's `content` array.
Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`.
- `start_block_index: number`
0-based index of the first cited block in the source's `content` array.
- `type: "content_block_location"`
- `"content_block_location"`
- `CitationWebSearchResultLocationParam object { cited_text, encrypted_index, title, 2 more }`
- `cited_text: string`
- `encrypted_index: string`
- `title: string or null`
- `type: "web_search_result_location"`
- `"web_search_result_location"`
- `url: string`
- `CitationSearchResultLocationParam object { cited_text, end_block_index, search_result_index, 4 more }`
- `cited_text: string`
The full text of the cited block range, concatenated.
Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns.
- `end_block_index: number`
Exclusive 0-based end index of the cited block range in the source's `content` array.
Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`.
- `search_result_index: number`
0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results.
Counted separately from `document_index`; server-side web search results are not included in this count.
- `source: string`
- `start_block_index: number`
0-based index of the first cited block in the source's `content` array.
- `title: string or null`
- `type: "search_result_location"`
- `"search_result_location"`
- `ImageBlockParam object { source, type, cache_control }`
- `source: Base64ImageSource or URLImageSource`
- `Base64ImageSource object { data, media_type, type }`
- `data: string`
- `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"`
- `"image/jpeg"`
- `"image/png"`
- `"image/gif"`
- `"image/webp"`
- `type: "base64"`
- `"base64"`
- `URLImageSource object { type, url }`
- `type: "url"`
- `"url"`
- `url: string`
- `type: "image"`
- `"image"`
- `cache_control: optional CacheControlEphemeral or null`
Create a cache control breakpoint at this content block.
- `DocumentBlockParam object { source, type, cache_control, 3 more }`
- `source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource`
- `Base64PDFSource object { data, media_type, type }`
- `data: string`
- `media_type: "application/pdf"`
- `"application/pdf"`
- `type: "base64"`
- `"base64"`
- `PlainTextSource object { data, media_type, type }`
- `data: string`
- `media_type: "text/plain"`
- `"text/plain"`
- `type: "text"`
- `"text"`
- `ContentBlockSource object { content, type }`
- `content: string or array of ContentBlockSourceContent`
- `string`
Cut at 300 lines. The page has the rest.
api/messages/batches First recorded · 7288 lines, first recorded
# Batches ## Create a Message Batch ### Header Parameters ### Body Parameters ### Returns ### Example #### Response ## Retrieve a Message Batch ### Path Parameters ### Returns ### Example #### Response ## List Message Batches ### Query Parameters ### Returns ### Example #### Response ## Cancel a Message Batch ### Path Parameters ### Returns ### Example #### Response ## Delete a Message Batch ### Path Parameters ### Returns ### Example #### Response ## Retrieve Message Batch results ### Path Parameters ### Returns ### Example ## Domain Types ### Deleted Message Batch ### Message Batch ### Message Batch Canceled Result ### Message Batch Errored Result ### Message Batch Expired Result ### Message Batch Individual Response ### Message Batch Request Counts ### Message Batch Result ### Message Batch Succeeded Result
The first capture of this source. The page was already there, and this is what it said.
---
title: Batches
url: https://platform.claude.com/docs/en/api/messages/batches
---
# Batches
## Create a Message Batch
**post** `/v1/messages/batches`
Send a batch of Message creation requests.
The Message Batches API can be used to process multiple Messages API requests at once. Once a Message Batch is created, it begins processing immediately. Batches can take up to 24 hours to complete.
Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing)
### Header Parameters
- `"anthropic-user-profile-id": optional string`
The user profile ID to attribute the requests in this batch to. Use when acting on behalf of a party other than your organization. Requires the `user-profiles` beta header. Applies to every request in the batch; an individual request whose `user_profile_id` body field conflicts with this header is errored.
### Body Parameters
- `requests: array of object { custom_id, params }`
List of requests for prompt completion. Each is an individual request to create a Message.
- `custom_id: string`
Developer-provided ID created for each request in a Message Batch. Useful for matching results to requests, as results may be given out of request order.
Must be unique for each request within the Message Batch.
- `params: object { max_tokens, messages, model, 15 more }`
Messages API creation parameters for the individual request.
See the [Messages API reference](https://platform.claude.com/docs/en/api/messages) for full documentation on available parameters.
- `max_tokens: number`
The maximum number of tokens to generate before stopping.
Note that our models may stop _before_ reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate.
Set to `0` to populate the [prompt cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pre-warming-the-cache) without generating a response.
Different models have different maximum values for this parameter. See [models](https://platform.claude.com/docs/en/about-claude/models/overview) for details.
- `messages: array of MessageParam`
Input messages.
Our models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn.
Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages.
If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response.
Example with a single `user` message:
```json
[{"role": "user", "content": "Hello, Claude"}]
```
Example with multiple conversational turns:
```json
[
{"role": "user", "content": "Hello there."},
{"role": "assistant", "content": "Hi, I'm Claude. How can I help you?"},
{"role": "user", "content": "Can you explain LLMs in plain English?"},
]
```
Example with a partially-filled response from Claude:
```json
[
{"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"},
{"role": "assistant", "content": "The best answer is ("},
]
```
Each input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `"text"`. The following input messages are equivalent:
```json
{"role": "user", "content": "Hello, Claude"}
```
```json
{"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]}
```
See [input examples](https://platform.claude.com/docs/en/build-with-claude/working-with-messages).
Note that if you want to include a [system prompt](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role), you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API.
There is a limit of 100,000 messages in a single request.
- `content: string or array of ContentBlockParam`
- `string`
- `array of ContentBlockParam`
- `TextBlockParam object { text, type, cache_control, citations }`
- `text: string`
- `type: "text"`
- `"text"`
- `cache_control: optional CacheControlEphemeral or null`
Create a cache control breakpoint at this content block.
- `type: "ephemeral"`
- `"ephemeral"`
- `ttl: optional "5m" or "1h"`
The time-to-live for the cache control breakpoint.
This may be one the following values:
- `5m`: 5 minutes
- `1h`: 1 hour
Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) for details.
- `"5m"`
- `"1h"`
- `citations: optional array of TextCitationParam or null`
- `CitationCharLocationParam object { cited_text, document_index, document_title, 3 more }`
- `cited_text: string`
- `document_index: number`
- `document_title: string or null`
- `end_char_index: number`
- `start_char_index: number`
- `type: "char_location"`
- `"char_location"`
- `CitationPageLocationParam object { cited_text, document_index, document_title, 3 more }`
- `cited_text: string`
- `document_index: number`
- `document_title: string or null`
- `end_page_number: number`
- `start_page_number: number`
- `type: "page_location"`
- `"page_location"`
- `CitationContentBlockLocationParam object { cited_text, document_index, document_title, 3 more }`
- `cited_text: string`
The full text of the cited block range, concatenated.
Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns.
- `document_index: number`
- `document_title: string or null`
- `end_block_index: number`
Exclusive 0-based end index of the cited block range in the source's `content` array.
Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`.
- `start_block_index: number`
0-based index of the first cited block in the source's `content` array.
- `type: "content_block_location"`
- `"content_block_location"`
- `CitationWebSearchResultLocationParam object { cited_text, encrypted_index, title, 2 more }`
- `cited_text: string`
- `encrypted_index: string`
- `title: string or null`
- `type: "web_search_result_location"`
- `"web_search_result_location"`
- `url: string`
- `CitationSearchResultLocationParam object { cited_text, end_block_index, search_result_index, 4 more }`
- `cited_text: string`
The full text of the cited block range, concatenated.
Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns.
- `end_block_index: number`
Exclusive 0-based end index of the cited block range in the source's `content` array.
Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`.
- `search_result_index: number`
0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results.
Counted separately from `document_index`; server-side web search results are not included in this count.
- `source: string`
- `start_block_index: number`
0-based index of the first cited block in the source's `content` array.
- `title: string or null`
- `type: "search_result_location"`
- `"search_result_location"`
- `ImageBlockParam object { source, type, cache_control }`
- `source: Base64ImageSource or URLImageSource`
- `Base64ImageSource object { data, media_type, type }`
- `data: string`
- `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"`
- `"image/jpeg"`
- `"image/png"`
- `"image/gif"`
- `"image/webp"`
- `type: "base64"`
- `"base64"`
- `URLImageSource object { type, url }`
- `type: "url"`
- `"url"`
- `url: string`
- `type: "image"`
- `"image"`
- `cache_control: optional CacheControlEphemeral or null`
Create a cache control breakpoint at this content block.
- `DocumentBlockParam object { source, type, cache_control, 3 more }`
- `source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource`
- `Base64PDFSource object { data, media_type, type }`
- `data: string`
- `media_type: "application/pdf"`
- `"application/pdf"`
- `type: "base64"`
- `"base64"`
- `PlainTextSource object { data, media_type, type }`
Cut at 300 lines. The page has the rest.
api/messages/batches/cancel First recorded · 142 lines, first recorded
## Cancel a Message Batch ### Path Parameters ### Returns ### Example #### Response
The first capture of this source. The page was already there, and this is what it said.
---
title: Cancel a Message Batch
url: https://platform.claude.com/docs/en/api/messages/batches/cancel
---
## Cancel a Message Batch
**post** `/v1/messages/batches/{message_batch_id}/cancel`
Batches may be canceled any time before processing ends. Once cancellation is initiated, the batch enters a `canceling` state, at which time the system may complete any in-progress, non-interruptible requests before finalizing cancellation.
The number of canceled requests is specified in `request_counts`. To determine which requests were canceled, check the individual results within the batch. Note that cancellation may not result in any canceled requests if they were non-interruptible.
Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing)
### Path Parameters
- `message_batch_id: string`
ID of the Message Batch.
### Returns
- `MessageBatch object { id, archived_at, cancel_initiated_at, 7 more }`
- `id: string`
Unique object identifier.
The format and length of IDs may change over time.
- `archived_at: string or null`
RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable.
- `cancel_initiated_at: string or null`
RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated.
- `created_at: string`
RFC 3339 datetime string representing the time at which the Message Batch was created.
- `ended_at: string or null`
RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends.
Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired.
- `expires_at: string`
RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation.
- `processing_status: "in_progress" or "canceling" or "ended"`
Processing status of the Message Batch.
- `"in_progress"`
- `"canceling"`
- `"ended"`
- `request_counts: MessageBatchRequestCounts`
Tallies requests within the Message Batch, categorized by their status.
Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch.
- `canceled: number`
Number of requests in the Message Batch that have been canceled.
This is zero until processing of the entire Message Batch has ended.
- `errored: number`
Number of requests in the Message Batch that encountered an error.
This is zero until processing of the entire Message Batch has ended.
- `expired: number`
Number of requests in the Message Batch that have expired.
This is zero until processing of the entire Message Batch has ended.
- `processing: number`
Number of requests in the Message Batch that are processing.
- `succeeded: number`
Number of requests in the Message Batch that have completed successfully.
This is zero until processing of the entire Message Batch has ended.
- `results_url: string or null`
URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends.
Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests.
- `type: "message_batch"`
Object type.
For Message Batches, this is always `"message_batch"`.
- `"message_batch"`
### Example
```http
curl https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/cancel \
-X POST \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_API_KEY"
```
#### Response
```json
{
"id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
"archived_at": "2024-08-20T18:37:24.100435Z",
"cancel_initiated_at": "2024-08-20T18:37:24.100435Z",
"created_at": "2024-08-20T18:37:24.100435Z",
"ended_at": "2024-08-20T18:37:24.100435Z",
"expires_at": "2024-08-20T18:37:24.100435Z",
"processing_status": "in_progress",
"request_counts": {
"canceled": 10,
"errored": 30,
"expired": 10,
"processing": 100,
"succeeded": 50
},
"results_url": "https://api.anthropic.com/v1/messages/batches/msgbatch_013Zva2CMHLNnXjNJJKqJ2EF/results",
"type": "message_batch"
}
```
api/messages/batches/create First recorded · 2379 lines, first recorded
## Create a Message Batch ### Header Parameters ### Body Parameters ### Returns ### Example #### Response
The first capture of this source. The page was already there, and this is what it said.
---
title: Create a Message Batch
url: https://platform.claude.com/docs/en/api/messages/batches/create
---
## Create a Message Batch
**post** `/v1/messages/batches`
Send a batch of Message creation requests.
The Message Batches API can be used to process multiple Messages API requests at once. Once a Message Batch is created, it begins processing immediately. Batches can take up to 24 hours to complete.
Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing)
### Header Parameters
- `"anthropic-user-profile-id": optional string`
The user profile ID to attribute the requests in this batch to. Use when acting on behalf of a party other than your organization. Requires the `user-profiles` beta header. Applies to every request in the batch; an individual request whose `user_profile_id` body field conflicts with this header is errored.
### Body Parameters
- `requests: array of object { custom_id, params }`
List of requests for prompt completion. Each is an individual request to create a Message.
- `custom_id: string`
Developer-provided ID created for each request in a Message Batch. Useful for matching results to requests, as results may be given out of request order.
Must be unique for each request within the Message Batch.
- `params: object { max_tokens, messages, model, 15 more }`
Messages API creation parameters for the individual request.
See the [Messages API reference](https://platform.claude.com/docs/en/api/messages) for full documentation on available parameters.
- `max_tokens: number`
The maximum number of tokens to generate before stopping.
Note that our models may stop _before_ reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate.
Set to `0` to populate the [prompt cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pre-warming-the-cache) without generating a response.
Different models have different maximum values for this parameter. See [models](https://platform.claude.com/docs/en/about-claude/models/overview) for details.
- `messages: array of MessageParam`
Input messages.
Our models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn.
Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages.
If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response.
Example with a single `user` message:
```json
[{"role": "user", "content": "Hello, Claude"}]
```
Example with multiple conversational turns:
```json
[
{"role": "user", "content": "Hello there."},
{"role": "assistant", "content": "Hi, I'm Claude. How can I help you?"},
{"role": "user", "content": "Can you explain LLMs in plain English?"},
]
```
Example with a partially-filled response from Claude:
```json
[
{"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"},
{"role": "assistant", "content": "The best answer is ("},
]
```
Each input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `"text"`. The following input messages are equivalent:
```json
{"role": "user", "content": "Hello, Claude"}
```
```json
{"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]}
```
See [input examples](https://platform.claude.com/docs/en/build-with-claude/working-with-messages).
Note that if you want to include a [system prompt](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role), you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API.
There is a limit of 100,000 messages in a single request.
- `content: string or array of ContentBlockParam`
- `string`
- `array of ContentBlockParam`
- `TextBlockParam object { text, type, cache_control, citations }`
- `text: string`
- `type: "text"`
- `"text"`
- `cache_control: optional CacheControlEphemeral or null`
Create a cache control breakpoint at this content block.
- `type: "ephemeral"`
- `"ephemeral"`
- `ttl: optional "5m" or "1h"`
The time-to-live for the cache control breakpoint.
This may be one the following values:
- `5m`: 5 minutes
- `1h`: 1 hour
Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) for details.
- `"5m"`
- `"1h"`
- `citations: optional array of TextCitationParam or null`
- `CitationCharLocationParam object { cited_text, document_index, document_title, 3 more }`
- `cited_text: string`
- `document_index: number`
- `document_title: string or null`
- `end_char_index: number`
- `start_char_index: number`
- `type: "char_location"`
- `"char_location"`
- `CitationPageLocationParam object { cited_text, document_index, document_title, 3 more }`
- `cited_text: string`
- `document_index: number`
- `document_title: string or null`
- `end_page_number: number`
- `start_page_number: number`
- `type: "page_location"`
- `"page_location"`
- `CitationContentBlockLocationParam object { cited_text, document_index, document_title, 3 more }`
- `cited_text: string`
The full text of the cited block range, concatenated.
Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns.
- `document_index: number`
- `document_title: string or null`
- `end_block_index: number`
Exclusive 0-based end index of the cited block range in the source's `content` array.
Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`.
- `start_block_index: number`
0-based index of the first cited block in the source's `content` array.
- `type: "content_block_location"`
- `"content_block_location"`
- `CitationWebSearchResultLocationParam object { cited_text, encrypted_index, title, 2 more }`
- `cited_text: string`
- `encrypted_index: string`
- `title: string or null`
- `type: "web_search_result_location"`
- `"web_search_result_location"`
- `url: string`
- `CitationSearchResultLocationParam object { cited_text, end_block_index, search_result_index, 4 more }`
- `cited_text: string`
The full text of the cited block range, concatenated.
Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns.
- `end_block_index: number`
Exclusive 0-based end index of the cited block range in the source's `content` array.
Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`.
- `search_result_index: number`
0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results.
Counted separately from `document_index`; server-side web search results are not included in this count.
- `source: string`
- `start_block_index: number`
0-based index of the first cited block in the source's `content` array.
- `title: string or null`
- `type: "search_result_location"`
- `"search_result_location"`
- `ImageBlockParam object { source, type, cache_control }`
- `source: Base64ImageSource or URLImageSource`
- `Base64ImageSource object { data, media_type, type }`
- `data: string`
- `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"`
- `"image/jpeg"`
- `"image/png"`
- `"image/gif"`
- `"image/webp"`
- `type: "base64"`
- `"base64"`
- `URLImageSource object { type, url }`
- `type: "url"`
- `"url"`
- `url: string`
- `type: "image"`
- `"image"`
- `cache_control: optional CacheControlEphemeral or null`
Create a cache control breakpoint at this content block.
- `DocumentBlockParam object { source, type, cache_control, 3 more }`
- `source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource`
- `Base64PDFSource object { data, media_type, type }`
- `data: string`
- `media_type: "application/pdf"`
- `"application/pdf"`
- `type: "base64"`
- `"base64"`
- `PlainTextSource object { data, media_type, type }`
- `data: string`
Cut at 300 lines. The page has the rest.
api/messages/batches/delete First recorded · 54 lines, first recorded
## Delete a Message Batch ### Path Parameters ### Returns ### Example #### Response
The first capture of this source. The page was already there, and this is what it said.
---
title: Delete a Message Batch
url: https://platform.claude.com/docs/en/api/messages/batches/delete
---
## Delete a Message Batch
**delete** `/v1/messages/batches/{message_batch_id}`
Delete a Message Batch.
Message Batches can only be deleted once they've finished processing. If you'd like to delete an in-progress batch, you must first cancel it.
Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing)
### Path Parameters
- `message_batch_id: string`
ID of the Message Batch.
### Returns
- `DeletedMessageBatch object { id, type }`
- `id: string`
ID of the Message Batch.
- `type: "message_batch_deleted"`
Deleted object type.
For Message Batches, this is always `"message_batch_deleted"`.
- `"message_batch_deleted"`
### Example
```http
curl https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID \
-X DELETE \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_API_KEY"
```
#### Response
```json
{
"id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
"type": "message_batch_deleted"
}
```
api/messages/batches/list First recorded · 168 lines, first recorded
## List Message Batches ### Query Parameters ### Returns ### Example #### Response
The first capture of this source. The page was already there, and this is what it said.
---
title: List Message Batches
url: https://platform.claude.com/docs/en/api/messages/batches/list
---
## List Message Batches
**get** `/v1/messages/batches`
List all Message Batches within a Workspace. Most recently created batches are returned first.
Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing)
### Query Parameters
- `after_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.
- `before_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.
- `limit: optional number`
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
### Returns
- `data: array of MessageBatch`
- `id: string`
Unique object identifier.
The format and length of IDs may change over time.
- `archived_at: string or null`
RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable.
- `cancel_initiated_at: string or null`
RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated.
- `created_at: string`
RFC 3339 datetime string representing the time at which the Message Batch was created.
- `ended_at: string or null`
RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends.
Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired.
- `expires_at: string`
RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation.
- `processing_status: "in_progress" or "canceling" or "ended"`
Processing status of the Message Batch.
- `"in_progress"`
- `"canceling"`
- `"ended"`
- `request_counts: MessageBatchRequestCounts`
Tallies requests within the Message Batch, categorized by their status.
Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch.
- `canceled: number`
Number of requests in the Message Batch that have been canceled.
This is zero until processing of the entire Message Batch has ended.
- `errored: number`
Number of requests in the Message Batch that encountered an error.
This is zero until processing of the entire Message Batch has ended.
- `expired: number`
Number of requests in the Message Batch that have expired.
This is zero until processing of the entire Message Batch has ended.
- `processing: number`
Number of requests in the Message Batch that are processing.
- `succeeded: number`
Number of requests in the Message Batch that have completed successfully.
This is zero until processing of the entire Message Batch has ended.
- `results_url: string or null`
URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends.
Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests.
- `type: "message_batch"`
Object type.
For Message Batches, this is always `"message_batch"`.
- `"message_batch"`
- `first_id: string or null`
First ID in the `data` list. Can be used as the `before_id` for the previous page.
- `has_more: boolean`
Indicates if there are more results in the requested page direction.
- `last_id: string or null`
Last ID in the `data` list. Can be used as the `after_id` for the next page.
### Example
```http
curl https://api.anthropic.com/v1/messages/batches \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_API_KEY"
```
#### Response
```json
{
"data": [
{
"id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
"archived_at": "2024-08-20T18:37:24.100435Z",
"cancel_initiated_at": "2024-08-20T18:37:24.100435Z",
"created_at": "2024-08-20T18:37:24.100435Z",
"ended_at": "2024-08-20T18:37:24.100435Z",
"expires_at": "2024-08-20T18:37:24.100435Z",
"processing_status": "in_progress",
"request_counts": {
"canceled": 10,
"errored": 30,
"expired": 10,
"processing": 100,
"succeeded": 50
},
"results_url": "https://api.anthropic.com/v1/messages/batches/msgbatch_013Zva2CMHLNnXjNJJKqJ2EF/results",
"type": "message_batch"
}
],
"first_id": "first_id",
"has_more": true,
"last_id": "last_id"
}
```
api/messages/batches/results First recorded · 1097 lines, first recorded
## Retrieve Message Batch results ### Path Parameters ### Returns ### Example
The first capture of this source. The page was already there, and this is what it said.
---
title: Retrieve Message Batch results
url: https://platform.claude.com/docs/en/api/messages/batches/results
---
## Retrieve Message Batch results
**get** `/v1/messages/batches/{message_batch_id}/results`
Streams the results of a Message Batch as a `.jsonl` file.
Each line in the file is a JSON object containing the result of a single request in the Message Batch. Results are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests.
Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing)
### Path Parameters
- `message_batch_id: string`
ID of the Message Batch.
### Returns
- `MessageBatchIndividualResponse object { custom_id, result }`
This is a single line in the response `.jsonl` file and does not represent the response as a whole.
- `custom_id: string`
Developer-provided ID created for each request in a Message Batch. Useful for matching results to requests, as results may be given out of request order.
Must be unique for each request within the Message Batch.
- `result: MessageBatchResult`
Processing result for this request.
Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration.
- `MessageBatchSucceededResult object { message, type }`
- `message: Message`
- `id: string`
Unique object identifier.
The format and length of IDs may change over time.
- `container: Container or null`
Information about the container used in the request (for the code execution tool)
- `id: string`
Identifier for the container used in this request
- `expires_at: string`
The time at which the container will expire.
- `content: array of ContentBlock`
Content generated by the model.
This is an array of content blocks, each of which has a `type` that determines its shape.
Example:
```json
[{"type": "text", "text": "Hi, I'm Claude."}]
```
If the request input `messages` ended with an `assistant` turn, then the response `content` will continue directly from that last turn. You can use this to constrain the model's output.
For example, if the input `messages` were:
```json
[
{"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"},
{"role": "assistant", "content": "The best answer is ("}
]
```
Then the response `content` might be:
```json
[{"type": "text", "text": "B)"}]
```
- `TextBlock object { citations, text, type }`
- `citations: array of TextCitation or null`
Citations supporting the text block.
The type of citation returned will depend on the type of document being cited. Citing a PDF results in `page_location`, plain text results in `char_location`, and content document results in `content_block_location`.
- `CitationCharLocation object { cited_text, document_index, document_title, 4 more }`
- `cited_text: string`
- `document_index: number`
- `document_title: string or null`
- `end_char_index: number`
- `file_id: string or null`
- `start_char_index: number`
- `type: "char_location"`
- `"char_location"`
- `CitationPageLocation object { cited_text, document_index, document_title, 4 more }`
- `cited_text: string`
- `document_index: number`
- `document_title: string or null`
- `end_page_number: number`
- `file_id: string or null`
- `start_page_number: number`
- `type: "page_location"`
- `"page_location"`
- `CitationContentBlockLocation object { cited_text, document_index, document_title, 4 more }`
- `cited_text: string`
The full text of the cited block range, concatenated.
Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns.
- `document_index: number`
- `document_title: string or null`
- `end_block_index: number`
Exclusive 0-based end index of the cited block range in the source's `content` array.
Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`.
- `file_id: string or null`
- `start_block_index: number`
0-based index of the first cited block in the source's `content` array.
- `type: "content_block_location"`
- `"content_block_location"`
- `CitationsWebSearchResultLocation object { cited_text, encrypted_index, title, 2 more }`
- `cited_text: string`
- `encrypted_index: string`
- `title: string or null`
- `type: "web_search_result_location"`
- `"web_search_result_location"`
- `url: string`
- `CitationsSearchResultLocation object { cited_text, end_block_index, search_result_index, 4 more }`
- `cited_text: string`
The full text of the cited block range, concatenated.
Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns.
- `end_block_index: number`
Exclusive 0-based end index of the cited block range in the source's `content` array.
Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`.
- `search_result_index: number`
0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results.
Counted separately from `document_index`; server-side web search results are not included in this count.
- `source: string`
- `start_block_index: number`
0-based index of the first cited block in the source's `content` array.
- `title: string or null`
- `type: "search_result_location"`
- `"search_result_location"`
- `text: string`
- `type: "text"`
- `"text"`
- `ThinkingBlock object { signature, thinking, type }`
- `signature: string`
A value used to verify that this thinking block was generated by Claude when it is passed back to the API.
This is an opaque field and should not be interpreted or parsed. When passing thinking blocks back to the API (required when using tools with extended thinking), pass them back exactly as received, with this field intact.
See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.
- `thinking: string`
The text of Claude's thinking process for this block.
- `type: "thinking"`
- `"thinking"`
- `RedactedThinkingBlock object { data, type }`
- `data: string`
The contents of this redacted thinking block, returned when portions of the model's thinking were safety-redacted. This field is opaque and encrypted, with no readable content.
Pass `redacted_thinking` blocks back to the API unchanged when continuing a multi-turn conversation.
See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#redacted-thinking-blocks) for details.
- `type: "redacted_thinking"`
- `"redacted_thinking"`
- `ToolUseBlock object { id, caller, input, 2 more }`
- `id: string`
- `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120`
Tool invocation directly from the model.
- `DirectCaller object { type }`
Tool invocation directly from the model.
- `type: "direct"`
- `"direct"`
- `ServerToolCaller object { tool_id, type }`
Tool invocation generated by a server-side tool.
- `tool_id: string`
- `type: "code_execution_20250825"`
- `"code_execution_20250825"`
- `ServerToolCaller20260120 object { tool_id, type }`
- `tool_id: string`
- `type: "code_execution_20260120"`
- `"code_execution_20260120"`
- `input: map[unknown]`
- `name: string`
- `type: "tool_use"`
- `"tool_use"`
- `ServerToolUseBlock object { id, caller, input, 2 more }`
- `id: string`
- `caller: DirectCaller or ServerToolCaller or ServerToolCaller20260120`
Tool invocation directly from the model.
- `DirectCaller object { type }`
Tool invocation directly from the model.
Cut at 300 lines. The page has the rest.
api/messages/batches/retrieve First recorded · 139 lines, first recorded
## Retrieve a Message Batch ### Path Parameters ### Returns ### Example #### Response
The first capture of this source. The page was already there, and this is what it said.
---
title: Retrieve a Message Batch
url: https://platform.claude.com/docs/en/api/messages/batches/retrieve
---
## Retrieve a Message Batch
**get** `/v1/messages/batches/{message_batch_id}`
This endpoint is idempotent and can be used to poll for Message Batch completion. To access the results of a Message Batch, make a request to the `results_url` field in the response.
Learn more about the Message Batches API in our [user guide](https://platform.claude.com/docs/en/build-with-claude/batch-processing)
### Path Parameters
- `message_batch_id: string`
ID of the Message Batch.
### Returns
- `MessageBatch object { id, archived_at, cancel_initiated_at, 7 more }`
- `id: string`
Unique object identifier.
The format and length of IDs may change over time.
- `archived_at: string or null`
RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable.
- `cancel_initiated_at: string or null`
RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated.
- `created_at: string`
RFC 3339 datetime string representing the time at which the Message Batch was created.
- `ended_at: string or null`
RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends.
Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired.
- `expires_at: string`
RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation.
- `processing_status: "in_progress" or "canceling" or "ended"`
Processing status of the Message Batch.
- `"in_progress"`
- `"canceling"`
- `"ended"`
- `request_counts: MessageBatchRequestCounts`
Tallies requests within the Message Batch, categorized by their status.
Requests start as `processing` and move to one of the other statuses only once processing of the entire batch ends. The sum of all values always matches the total number of requests in the batch.
- `canceled: number`
Number of requests in the Message Batch that have been canceled.
This is zero until processing of the entire Message Batch has ended.
- `errored: number`
Number of requests in the Message Batch that encountered an error.
This is zero until processing of the entire Message Batch has ended.
- `expired: number`
Number of requests in the Message Batch that have expired.
This is zero until processing of the entire Message Batch has ended.
- `processing: number`
Number of requests in the Message Batch that are processing.
- `succeeded: number`
Number of requests in the Message Batch that have completed successfully.
This is zero until processing of the entire Message Batch has ended.
- `results_url: string or null`
URL to a `.jsonl` file containing the results of the Message Batch requests. Specified only once processing ends.
Results in the file are not guaranteed to be in the same order as requests. Use the `custom_id` field to match results to requests.
- `type: "message_batch"`
Object type.
For Message Batches, this is always `"message_batch"`.
- `"message_batch"`
### Example
```http
curl https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_API_KEY"
```
#### Response
```json
{
"id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
"archived_at": "2024-08-20T18:37:24.100435Z",
"cancel_initiated_at": "2024-08-20T18:37:24.100435Z",
"created_at": "2024-08-20T18:37:24.100435Z",
"ended_at": "2024-08-20T18:37:24.100435Z",
"expires_at": "2024-08-20T18:37:24.100435Z",
"processing_status": "in_progress",
"request_counts": {
"canceled": 10,
"errored": 30,
"expired": 10,
"processing": 100,
"succeeded": 50
},
"results_url": "https://api.anthropic.com/v1/messages/batches/msgbatch_013Zva2CMHLNnXjNJJKqJ2EF/results",
"type": "message_batch"
}
```
api/messages/count_tokens First recorded · 2206 lines, first recorded
## Count tokens in a Message ### Header Parameters ### Body Parameters ### Returns ### Example #### Response
The first capture of this source. The page was already there, and this is what it said.
---
title: Count tokens in a Message
url: https://platform.claude.com/docs/en/api/messages/count_tokens
---
## Count tokens in a Message
**post** `/v1/messages/count_tokens`
Count the number of tokens in a Message.
The Token Count API can be used to count the number of tokens in a Message, including tools, images, and documents, without creating it.
Learn more about token counting in our [user guide](https://platform.claude.com/docs/en/build-with-claude/token-counting)
### Header Parameters
- `"anthropic-user-profile-id": optional string`
The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. Requires the `user-profiles` beta header.
### Body Parameters
- `messages: array of MessageParam`
Input messages.
Our models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn.
Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages.
If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response.
Example with a single `user` message:
```json
[{"role": "user", "content": "Hello, Claude"}]
```
Example with multiple conversational turns:
```json
[
{"role": "user", "content": "Hello there."},
{"role": "assistant", "content": "Hi, I'm Claude. How can I help you?"},
{"role": "user", "content": "Can you explain LLMs in plain English?"},
]
```
Example with a partially-filled response from Claude:
```json
[
{"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"},
{"role": "assistant", "content": "The best answer is ("},
]
```
Each input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `"text"`. The following input messages are equivalent:
```json
{"role": "user", "content": "Hello, Claude"}
```
```json
{"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]}
```
See [input examples](https://platform.claude.com/docs/en/build-with-claude/working-with-messages).
Note that if you want to include a [system prompt](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role), you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API.
There is a limit of 100,000 messages in a single request.
- `content: string or array of ContentBlockParam`
- `string`
- `array of ContentBlockParam`
- `TextBlockParam object { text, type, cache_control, citations }`
- `text: string`
- `type: "text"`
- `"text"`
- `cache_control: optional CacheControlEphemeral or null`
Create a cache control breakpoint at this content block.
- `type: "ephemeral"`
- `"ephemeral"`
- `ttl: optional "5m" or "1h"`
The time-to-live for the cache control breakpoint.
This may be one the following values:
- `5m`: 5 minutes
- `1h`: 1 hour
Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) for details.
- `"5m"`
- `"1h"`
- `citations: optional array of TextCitationParam or null`
- `CitationCharLocationParam object { cited_text, document_index, document_title, 3 more }`
- `cited_text: string`
- `document_index: number`
- `document_title: string or null`
- `end_char_index: number`
- `start_char_index: number`
- `type: "char_location"`
- `"char_location"`
- `CitationPageLocationParam object { cited_text, document_index, document_title, 3 more }`
- `cited_text: string`
- `document_index: number`
- `document_title: string or null`
- `end_page_number: number`
- `start_page_number: number`
- `type: "page_location"`
- `"page_location"`
- `CitationContentBlockLocationParam object { cited_text, document_index, document_title, 3 more }`
- `cited_text: string`
The full text of the cited block range, concatenated.
Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns.
- `document_index: number`
- `document_title: string or null`
- `end_block_index: number`
Exclusive 0-based end index of the cited block range in the source's `content` array.
Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`.
- `start_block_index: number`
0-based index of the first cited block in the source's `content` array.
- `type: "content_block_location"`
- `"content_block_location"`
- `CitationWebSearchResultLocationParam object { cited_text, encrypted_index, title, 2 more }`
- `cited_text: string`
- `encrypted_index: string`
- `title: string or null`
- `type: "web_search_result_location"`
- `"web_search_result_location"`
- `url: string`
- `CitationSearchResultLocationParam object { cited_text, end_block_index, search_result_index, 4 more }`
- `cited_text: string`
The full text of the cited block range, concatenated.
Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns.
- `end_block_index: number`
Exclusive 0-based end index of the cited block range in the source's `content` array.
Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`.
- `search_result_index: number`
0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results.
Counted separately from `document_index`; server-side web search results are not included in this count.
- `source: string`
- `start_block_index: number`
0-based index of the first cited block in the source's `content` array.
- `title: string or null`
- `type: "search_result_location"`
- `"search_result_location"`
- `ImageBlockParam object { source, type, cache_control }`
- `source: Base64ImageSource or URLImageSource`
- `Base64ImageSource object { data, media_type, type }`
- `data: string`
- `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"`
- `"image/jpeg"`
- `"image/png"`
- `"image/gif"`
- `"image/webp"`
- `type: "base64"`
- `"base64"`
- `URLImageSource object { type, url }`
- `type: "url"`
- `"url"`
- `url: string`
- `type: "image"`
- `"image"`
- `cache_control: optional CacheControlEphemeral or null`
Create a cache control breakpoint at this content block.
- `DocumentBlockParam object { source, type, cache_control, 3 more }`
- `source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource`
- `Base64PDFSource object { data, media_type, type }`
- `data: string`
- `media_type: "application/pdf"`
- `"application/pdf"`
- `type: "base64"`
- `"base64"`
- `PlainTextSource object { data, media_type, type }`
- `data: string`
- `media_type: "text/plain"`
- `"text/plain"`
- `type: "text"`
- `"text"`
- `ContentBlockSource object { content, type }`
- `content: string or array of ContentBlockSourceContent`
- `string`
- `ContentBlockSourceContent = array of ContentBlockSourceContent`
- `TextBlockParam object { text, type, cache_control, citations }`
- `ImageBlockParam object { source, type, cache_control }`
- `type: "content"`
- `"content"`
- `URLPDFSource object { type, url }`
Cut at 300 lines. The page has the rest.
api/messages/create First recorded · 3277 lines, first recorded
## Create a Message ### Header Parameters ### Body Parameters ### Returns ### Example #### Response
The first capture of this source. The page was already there, and this is what it said.
---
title: Create a Message
url: https://platform.claude.com/docs/en/api/messages/create
---
## Create a Message
**post** `/v1/messages`
Send a structured list of input messages with text and/or image content, and the model will generate the next message in the conversation.
The Messages API can be used for either single queries or stateless multi-turn conversations.
Learn more about the Messages API in our [user guide](https://platform.claude.com/docs/en/get-started)
### Header Parameters
- `"anthropic-user-profile-id": optional string`
The user profile ID to attribute this request to. Use when acting on behalf of a party other than your organization. Requires the `user-profiles` beta header.
### Body Parameters
- `max_tokens: number`
The maximum number of tokens to generate before stopping.
Note that our models may stop _before_ reaching this maximum. This parameter only specifies the absolute maximum number of tokens to generate.
Set to `0` to populate the [prompt cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pre-warming-the-cache) without generating a response.
Different models have different maximum values for this parameter. See [models](https://platform.claude.com/docs/en/about-claude/models/overview) for details.
- `messages: array of MessageParam`
Input messages.
Our models are trained to operate on alternating `user` and `assistant` conversational turns. When creating a new `Message`, you specify the prior conversational turns with the `messages` parameter, and the model then generates the next `Message` in the conversation. Consecutive `user` or `assistant` turns in your request will be combined into a single turn.
Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages.
If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response.
Example with a single `user` message:
```json
[{"role": "user", "content": "Hello, Claude"}]
```
Example with multiple conversational turns:
```json
[
{"role": "user", "content": "Hello there."},
{"role": "assistant", "content": "Hi, I'm Claude. How can I help you?"},
{"role": "user", "content": "Can you explain LLMs in plain English?"},
]
```
Example with a partially-filled response from Claude:
```json
[
{"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"},
{"role": "assistant", "content": "The best answer is ("},
]
```
Each input message `content` may be either a single `string` or an array of content blocks, where each block has a specific `type`. Using a `string` for `content` is shorthand for an array of one content block of type `"text"`. The following input messages are equivalent:
```json
{"role": "user", "content": "Hello, Claude"}
```
```json
{"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]}
```
See [input examples](https://platform.claude.com/docs/en/build-with-claude/working-with-messages).
Note that if you want to include a [system prompt](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role), you can use the top-level `system` parameter — there is no `"system"` role for input messages in the Messages API.
There is a limit of 100,000 messages in a single request.
- `content: string or array of ContentBlockParam`
- `string`
- `array of ContentBlockParam`
- `TextBlockParam object { text, type, cache_control, citations }`
- `text: string`
- `type: "text"`
- `"text"`
- `cache_control: optional CacheControlEphemeral or null`
Create a cache control breakpoint at this content block.
- `type: "ephemeral"`
- `"ephemeral"`
- `ttl: optional "5m" or "1h"`
The time-to-live for the cache control breakpoint.
This may be one the following values:
- `5m`: 5 minutes
- `1h`: 1 hour
Defaults to `5m`. See [prompt caching pricing](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) for details.
- `"5m"`
- `"1h"`
- `citations: optional array of TextCitationParam or null`
- `CitationCharLocationParam object { cited_text, document_index, document_title, 3 more }`
- `cited_text: string`
- `document_index: number`
- `document_title: string or null`
- `end_char_index: number`
- `start_char_index: number`
- `type: "char_location"`
- `"char_location"`
- `CitationPageLocationParam object { cited_text, document_index, document_title, 3 more }`
- `cited_text: string`
- `document_index: number`
- `document_title: string or null`
- `end_page_number: number`
- `start_page_number: number`
- `type: "page_location"`
- `"page_location"`
- `CitationContentBlockLocationParam object { cited_text, document_index, document_title, 3 more }`
- `cited_text: string`
The full text of the cited block range, concatenated.
Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns.
- `document_index: number`
- `document_title: string or null`
- `end_block_index: number`
Exclusive 0-based end index of the cited block range in the source's `content` array.
Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`.
- `start_block_index: number`
0-based index of the first cited block in the source's `content` array.
- `type: "content_block_location"`
- `"content_block_location"`
- `CitationWebSearchResultLocationParam object { cited_text, encrypted_index, title, 2 more }`
- `cited_text: string`
- `encrypted_index: string`
- `title: string or null`
- `type: "web_search_result_location"`
- `"web_search_result_location"`
- `url: string`
- `CitationSearchResultLocationParam object { cited_text, end_block_index, search_result_index, 4 more }`
- `cited_text: string`
The full text of the cited block range, concatenated.
Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns.
- `end_block_index: number`
Exclusive 0-based end index of the cited block range in the source's `content` array.
Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`.
- `search_result_index: number`
0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results.
Counted separately from `document_index`; server-side web search results are not included in this count.
- `source: string`
- `start_block_index: number`
0-based index of the first cited block in the source's `content` array.
- `title: string or null`
- `type: "search_result_location"`
- `"search_result_location"`
- `ImageBlockParam object { source, type, cache_control }`
- `source: Base64ImageSource or URLImageSource`
- `Base64ImageSource object { data, media_type, type }`
- `data: string`
- `media_type: "image/jpeg" or "image/png" or "image/gif" or "image/webp"`
- `"image/jpeg"`
- `"image/png"`
- `"image/gif"`
- `"image/webp"`
- `type: "base64"`
- `"base64"`
- `URLImageSource object { type, url }`
- `type: "url"`
- `"url"`
- `url: string`
- `type: "image"`
- `"image"`
- `cache_control: optional CacheControlEphemeral or null`
Create a cache control breakpoint at this content block.
- `DocumentBlockParam object { source, type, cache_control, 3 more }`
- `source: Base64PDFSource or PlainTextSource or ContentBlockSource or URLPDFSource`
- `Base64PDFSource object { data, media_type, type }`
- `data: string`
- `media_type: "application/pdf"`
- `"application/pdf"`
- `type: "base64"`
- `"base64"`
- `PlainTextSource object { data, media_type, type }`
- `data: string`
- `media_type: "text/plain"`
- `"text/plain"`
- `type: "text"`
- `"text"`
- `ContentBlockSource object { content, type }`
- `content: string or array of ContentBlockSourceContent`
- `string`
- `ContentBlockSourceContent = array of ContentBlockSourceContent`
Cut at 300 lines. The page has the rest.
api/models First recorded · 993 lines, first recorded
# Models ## List Models ### Query Parameters ### Header Parameters ### Returns ### Example #### Response ## Get a Model ### Path Parameters ### Header Parameters ### Returns ### Example #### Response ## Domain Types ### Capability Support ### Context Management Capability ### Effort Capability ### Model Capabilities ### Model Info ### Thinking Capability ### Thinking Types
The first capture of this source. The page was already there, and this is what it said.
---
title: Models
url: https://platform.claude.com/docs/en/api/models
---
# Models
## List Models
**get** `/v1/models`
List available models.
The Models API response can be used to determine which models are available for use in the API. More recently released models are listed first.
### Query Parameters
- `after_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.
- `before_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.
- `limit: optional number`
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
### Header Parameters
- `"anthropic-beta": optional array of AnthropicBeta`
Optional header to specify the beta version(s) you want to use.
- `string`
- `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 30 more`
- `"message-batches-2024-09-24"`
- `"prompt-caching-2024-07-31"`
- `"computer-use-2024-10-22"`
- `"computer-use-2025-01-24"`
- `"pdfs-2024-09-25"`
- `"token-counting-2024-11-01"`
- `"token-efficient-tools-2025-02-19"`
- `"output-128k-2025-02-19"`
- `"files-api-2025-04-14"`
- `"mcp-client-2025-04-04"`
- `"mcp-client-2025-11-20"`
- `"dev-full-thinking-2025-05-14"`
- `"interleaved-thinking-2025-05-14"`
- `"code-execution-2025-05-22"`
- `"extended-cache-ttl-2025-04-11"`
- `"context-1m-2025-08-07"`
- `"context-management-2025-06-27"`
- `"model-context-window-exceeded-2025-08-26"`
- `"skills-2025-10-02"`
- `"fast-mode-2026-02-01"`
- `"output-300k-2026-03-24"`
- `"user-profiles-2026-03-24"`
- `"advisor-tool-2026-03-01"`
- `"managed-agents-2026-04-01"`
- `"cache-diagnosis-2026-04-07"`
- `"dreaming-2026-04-21"`
- `"thinking-token-count-2026-05-13"`
- `"server-side-fallback-2026-06-01"`
- `"server-side-fallback-2026-07-01"`
- `"fallback-credit-2026-06-01"`
- `"fallback-credit-2026-07-01"`
- `"agent-memory-2026-07-22"`
- `"mid-conversation-tool-changes-2026-07-01"`
### Returns
- `data: array of ModelInfo`
- `id: string`
Unique model identifier.
- `capabilities: ModelCapabilities or null`
Model capability information.
- `batch: CapabilitySupport`
Whether the model supports the Batch API.
- `supported: boolean`
Whether this capability is supported by the model.
- `citations: CapabilitySupport`
Whether the model supports citation generation.
- `code_execution: CapabilitySupport`
Whether the model supports code execution tools.
- `context_management: ContextManagementCapability`
Context management support and available strategies.
- `clear_thinking_20251015: CapabilitySupport or null`
Indicates whether a capability is supported.
- `clear_tool_uses_20250919: CapabilitySupport or null`
Indicates whether a capability is supported.
- `compact_20260112: CapabilitySupport or null`
Indicates whether a capability is supported.
- `supported: boolean`
Whether this capability is supported by the model.
- `effort: EffortCapability`
Effort (reasoning_effort) support and available levels.
- `high: CapabilitySupport`
Whether the model supports high effort level.
- `low: CapabilitySupport`
Whether the model supports low effort level.
- `max: CapabilitySupport`
Whether the model supports max effort level.
- `medium: CapabilitySupport`
Whether the model supports medium effort level.
- `supported: boolean`
Whether this capability is supported by the model.
- `xhigh: CapabilitySupport or null`
Indicates whether a capability is supported.
- `image_input: CapabilitySupport`
Whether the model accepts image content blocks.
- `pdf_input: CapabilitySupport`
Whether the model accepts PDF content blocks.
- `structured_outputs: CapabilitySupport`
Whether the model supports structured output / JSON mode / strict tool schemas.
- `thinking: ThinkingCapability`
Thinking capability and supported type configurations.
- `supported: boolean`
Whether this capability is supported by the model.
- `types: ThinkingTypes`
Supported thinking type configurations.
- `adaptive: CapabilitySupport`
Whether the model supports thinking with type 'adaptive' (auto).
- `enabled: CapabilitySupport`
Whether the model supports thinking with type 'enabled'.
- `created_at: string`
RFC 3339 datetime string representing the time at which the model was released. May be set to an epoch value if the release date is unknown.
- `display_name: string`
A human-readable name for the model.
- `max_input_tokens: number or null`
Maximum input context window size in tokens for this model.
- `max_tokens: number or null`
Maximum value for the `max_tokens` parameter when using this model.
- `type: "model"`
Object type.
For Models, this is always `"model"`.
- `"model"`
- `first_id: string or null`
First ID in the `data` list. Can be used as the `before_id` for the previous page.
- `has_more: boolean`
Indicates if there are more results in the requested page direction.
- `last_id: string or null`
Last ID in the `data` list. Can be used as the `after_id` for the next page.
### Example
```http
curl https://api.anthropic.com/v1/models \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_API_KEY"
```
#### Response
```json
{
"data": [
{
"id": "claude-opus-4-6",
"capabilities": {
"batch": {
"supported": true
},
"citations": {
"supported": true
},
"code_execution": {
"supported": true
},
"context_management": {
"clear_thinking_20251015": {
"supported": true
},
"clear_tool_uses_20250919": {
"supported": true
},
"compact_20260112": {
"supported": true
},
"supported": true
},
"effort": {
"high": {
"supported": true
},
"low": {
"supported": true
},
"max": {
"supported": true
},
"medium": {
"supported": true
Cut at 300 lines. The page has the rest.
api/models/list First recorded · 337 lines, first recorded
## List Models ### Query Parameters ### Header Parameters ### Returns ### Example #### Response
The first capture of this source. The page was already there, and this is what it said.
---
title: List Models
url: https://platform.claude.com/docs/en/api/models/list
---
## List Models
**get** `/v1/models`
List available models.
The Models API response can be used to determine which models are available for use in the API. More recently released models are listed first.
### Query Parameters
- `after_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately after this object.
- `before_id: optional string`
ID of the object to use as a cursor for pagination. When provided, returns the page of results immediately before this object.
- `limit: optional number`
Number of items to return per page.
Defaults to `20`. Ranges from `1` to `1000`.
### Header Parameters
- `"anthropic-beta": optional array of AnthropicBeta`
Optional header to specify the beta version(s) you want to use.
- `string`
- `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 30 more`
- `"message-batches-2024-09-24"`
- `"prompt-caching-2024-07-31"`
- `"computer-use-2024-10-22"`
- `"computer-use-2025-01-24"`
- `"pdfs-2024-09-25"`
- `"token-counting-2024-11-01"`
- `"token-efficient-tools-2025-02-19"`
- `"output-128k-2025-02-19"`
- `"files-api-2025-04-14"`
- `"mcp-client-2025-04-04"`
- `"mcp-client-2025-11-20"`
- `"dev-full-thinking-2025-05-14"`
- `"interleaved-thinking-2025-05-14"`
- `"code-execution-2025-05-22"`
- `"extended-cache-ttl-2025-04-11"`
- `"context-1m-2025-08-07"`
- `"context-management-2025-06-27"`
- `"model-context-window-exceeded-2025-08-26"`
- `"skills-2025-10-02"`
- `"fast-mode-2026-02-01"`
- `"output-300k-2026-03-24"`
- `"user-profiles-2026-03-24"`
- `"advisor-tool-2026-03-01"`
- `"managed-agents-2026-04-01"`
- `"cache-diagnosis-2026-04-07"`
- `"dreaming-2026-04-21"`
- `"thinking-token-count-2026-05-13"`
- `"server-side-fallback-2026-06-01"`
- `"server-side-fallback-2026-07-01"`
- `"fallback-credit-2026-06-01"`
- `"fallback-credit-2026-07-01"`
- `"agent-memory-2026-07-22"`
- `"mid-conversation-tool-changes-2026-07-01"`
### Returns
- `data: array of ModelInfo`
- `id: string`
Unique model identifier.
- `capabilities: ModelCapabilities or null`
Model capability information.
- `batch: CapabilitySupport`
Whether the model supports the Batch API.
- `supported: boolean`
Whether this capability is supported by the model.
- `citations: CapabilitySupport`
Whether the model supports citation generation.
- `code_execution: CapabilitySupport`
Whether the model supports code execution tools.
- `context_management: ContextManagementCapability`
Context management support and available strategies.
- `clear_thinking_20251015: CapabilitySupport or null`
Indicates whether a capability is supported.
- `clear_tool_uses_20250919: CapabilitySupport or null`
Indicates whether a capability is supported.
- `compact_20260112: CapabilitySupport or null`
Indicates whether a capability is supported.
- `supported: boolean`
Whether this capability is supported by the model.
- `effort: EffortCapability`
Effort (reasoning_effort) support and available levels.
- `high: CapabilitySupport`
Whether the model supports high effort level.
- `low: CapabilitySupport`
Whether the model supports low effort level.
- `max: CapabilitySupport`
Whether the model supports max effort level.
- `medium: CapabilitySupport`
Whether the model supports medium effort level.
- `supported: boolean`
Whether this capability is supported by the model.
- `xhigh: CapabilitySupport or null`
Indicates whether a capability is supported.
- `image_input: CapabilitySupport`
Whether the model accepts image content blocks.
- `pdf_input: CapabilitySupport`
Whether the model accepts PDF content blocks.
- `structured_outputs: CapabilitySupport`
Whether the model supports structured output / JSON mode / strict tool schemas.
- `thinking: ThinkingCapability`
Thinking capability and supported type configurations.
- `supported: boolean`
Whether this capability is supported by the model.
- `types: ThinkingTypes`
Supported thinking type configurations.
- `adaptive: CapabilitySupport`
Whether the model supports thinking with type 'adaptive' (auto).
- `enabled: CapabilitySupport`
Whether the model supports thinking with type 'enabled'.
- `created_at: string`
RFC 3339 datetime string representing the time at which the model was released. May be set to an epoch value if the release date is unknown.
- `display_name: string`
A human-readable name for the model.
- `max_input_tokens: number or null`
Maximum input context window size in tokens for this model.
- `max_tokens: number or null`
Maximum value for the `max_tokens` parameter when using this model.
- `type: "model"`
Object type.
For Models, this is always `"model"`.
- `"model"`
- `first_id: string or null`
First ID in the `data` list. Can be used as the `before_id` for the previous page.
- `has_more: boolean`
Indicates if there are more results in the requested page direction.
- `last_id: string or null`
Last ID in the `data` list. Can be used as the `after_id` for the next page.
### Example
```http
curl https://api.anthropic.com/v1/models \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_API_KEY"
```
#### Response
```json
{
"data": [
{
"id": "claude-opus-4-6",
"capabilities": {
"batch": {
"supported": true
},
"citations": {
"supported": true
},
"code_execution": {
"supported": true
},
"context_management": {
"clear_thinking_20251015": {
"supported": true
},
"clear_tool_uses_20250919": {
"supported": true
},
"compact_20260112": {
"supported": true
},
"supported": true
},
"effort": {
"high": {
"supported": true
},
"low": {
"supported": true
},
"max": {
"supported": true
},
"medium": {
"supported": true
},
"supported": true,
Cut at 300 lines. The page has the rest.
api/models/retrieve First recorded · 308 lines, first recorded
## Get a Model ### Path Parameters ### Header Parameters ### Returns ### Example #### Response
The first capture of this source. The page was already there, and this is what it said.
---
title: Get a Model
url: https://platform.claude.com/docs/en/api/models/retrieve
---
## Get a Model
**get** `/v1/models/{model_id}`
Get a specific model.
The Models API response can be used to determine information about a specific model or resolve a model alias to a model ID.
### Path Parameters
- `model_id: string`
Model identifier or alias.
### Header Parameters
- `"anthropic-beta": optional array of AnthropicBeta`
Optional header to specify the beta version(s) you want to use.
- `string`
- `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 30 more`
- `"message-batches-2024-09-24"`
- `"prompt-caching-2024-07-31"`
- `"computer-use-2024-10-22"`
- `"computer-use-2025-01-24"`
- `"pdfs-2024-09-25"`
- `"token-counting-2024-11-01"`
- `"token-efficient-tools-2025-02-19"`
- `"output-128k-2025-02-19"`
- `"files-api-2025-04-14"`
- `"mcp-client-2025-04-04"`
- `"mcp-client-2025-11-20"`
- `"dev-full-thinking-2025-05-14"`
- `"interleaved-thinking-2025-05-14"`
- `"code-execution-2025-05-22"`
- `"extended-cache-ttl-2025-04-11"`
- `"context-1m-2025-08-07"`
- `"context-management-2025-06-27"`
- `"model-context-window-exceeded-2025-08-26"`
- `"skills-2025-10-02"`
- `"fast-mode-2026-02-01"`
- `"output-300k-2026-03-24"`
- `"user-profiles-2026-03-24"`
- `"advisor-tool-2026-03-01"`
- `"managed-agents-2026-04-01"`
- `"cache-diagnosis-2026-04-07"`
- `"dreaming-2026-04-21"`
- `"thinking-token-count-2026-05-13"`
- `"server-side-fallback-2026-06-01"`
- `"server-side-fallback-2026-07-01"`
- `"fallback-credit-2026-06-01"`
- `"fallback-credit-2026-07-01"`
- `"agent-memory-2026-07-22"`
- `"mid-conversation-tool-changes-2026-07-01"`
### Returns
- `ModelInfo object { id, capabilities, created_at, 4 more }`
- `id: string`
Unique model identifier.
- `capabilities: ModelCapabilities or null`
Model capability information.
- `batch: CapabilitySupport`
Whether the model supports the Batch API.
- `supported: boolean`
Whether this capability is supported by the model.
- `citations: CapabilitySupport`
Whether the model supports citation generation.
- `code_execution: CapabilitySupport`
Whether the model supports code execution tools.
- `context_management: ContextManagementCapability`
Context management support and available strategies.
- `clear_thinking_20251015: CapabilitySupport or null`
Indicates whether a capability is supported.
- `clear_tool_uses_20250919: CapabilitySupport or null`
Indicates whether a capability is supported.
- `compact_20260112: CapabilitySupport or null`
Indicates whether a capability is supported.
- `supported: boolean`
Whether this capability is supported by the model.
- `effort: EffortCapability`
Effort (reasoning_effort) support and available levels.
- `high: CapabilitySupport`
Whether the model supports high effort level.
- `low: CapabilitySupport`
Whether the model supports low effort level.
- `max: CapabilitySupport`
Whether the model supports max effort level.
- `medium: CapabilitySupport`
Whether the model supports medium effort level.
- `supported: boolean`
Whether this capability is supported by the model.
- `xhigh: CapabilitySupport or null`
Indicates whether a capability is supported.
- `image_input: CapabilitySupport`
Whether the model accepts image content blocks.
- `pdf_input: CapabilitySupport`
Whether the model accepts PDF content blocks.
- `structured_outputs: CapabilitySupport`
Whether the model supports structured output / JSON mode / strict tool schemas.
- `thinking: ThinkingCapability`
Thinking capability and supported type configurations.
- `supported: boolean`
Whether this capability is supported by the model.
- `types: ThinkingTypes`
Supported thinking type configurations.
- `adaptive: CapabilitySupport`
Whether the model supports thinking with type 'adaptive' (auto).
- `enabled: CapabilitySupport`
Whether the model supports thinking with type 'enabled'.
- `created_at: string`
RFC 3339 datetime string representing the time at which the model was released. May be set to an epoch value if the release date is unknown.
- `display_name: string`
A human-readable name for the model.
- `max_input_tokens: number or null`
Maximum input context window size in tokens for this model.
- `max_tokens: number or null`
Maximum value for the `max_tokens` parameter when using this model.
- `type: "model"`
Object type.
For Models, this is always `"model"`.
- `"model"`
### Example
```http
curl https://api.anthropic.com/v1/models/$MODEL_ID \
-H 'anthropic-version: 2023-06-01' \
-H "X-Api-Key: $ANTHROPIC_API_KEY"
```
#### Response
```json
{
"id": "claude-opus-4-6",
"capabilities": {
"batch": {
"supported": true
},
"citations": {
"supported": true
},
"code_execution": {
"supported": true
},
"context_management": {
"clear_thinking_20251015": {
"supported": true
},
"clear_tool_uses_20250919": {
"supported": true
},
"compact_20260112": {
"supported": true
},
"supported": true
},
"effort": {
"high": {
"supported": true
},
"low": {
"supported": true
},
"max": {
"supported": true
},
"medium": {
"supported": true
},
"supported": true,
"xhigh": {
"supported": true
}
},
"image_input": {
"supported": true
},
"pdf_input": {
"supported": true
},
"structured_outputs": {
"supported": true
},
"thinking": {
"supported": true,
"types": {
"adaptive": {
"supported": true
},
"enabled": {
"supported": true
}
}
}
Cut at 300 lines. The page has the rest.
api/overview First recorded · 193 lines, first recorded
## Prerequisites ## Available APIs ## Authentication ### Getting API keys ## Client SDKs ## Claude API vs cloud platforms ### Claude API ### Cloud platform APIs ## Request and response format ### Request size limits ### Response headers ## Pagination ## Rate limits and availability ### Rate limits ### Availability ## Next steps
The first capture of this source. The page was already there, and this is what it said.
---
title: API overview
url: https://platform.claude.com/docs/en/api/overview
description: Understand the Claude API's available endpoints, authentication headers, client SDKs, pagination, rate limits, and cloud platform access options.
---
The Claude API is a RESTful API at `https://api.anthropic.com` that provides programmatic access to Claude models and Claude Managed Agents.
<Note>
**New to Claude?** For direct model access, start with [Get started](https://platform.claude.com/docs/en/get-started) and [Working with Messages](https://platform.claude.com/docs/en/build-with-claude/working-with-messages). For managed agent infrastructure, see the [Claude Managed Agents quickstart](https://platform.claude.com/docs/en/managed-agents/quickstart).
</Note>
## Prerequisites
To use the Claude API, you'll need:
* A [Claude Console account](https://platform.claude.com)
* An [API key](https://platform.claude.com/settings/keys), or a configured [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) rule
For step-by-step setup instructions, see [Get started](https://platform.claude.com/docs/en/get-started).
## Available APIs
The Claude API includes the following APIs:
**General Availability:**
* **[Messages API](https://platform.claude.com/docs/en/api/messages/create)**: Send messages to Claude for conversational interactions (`POST /v1/messages`)
* **[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`)
* **[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`)
* **[Models API](https://platform.claude.com/docs/en/api/models/list)**: List available Claude models and their details (`GET /v1/models`)
**Beta:**
* **[Files API](https://platform.claude.com/docs/en/api/beta/files/upload)**: Upload and manage files for use across multiple API calls (`POST /v1/files`, `GET /v1/files`)
* **[Skills API](https://platform.claude.com/docs/en/api/skills/create-skill)**: Create and manage custom agent skills (`POST /v1/skills`, `GET /v1/skills`)
* **[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`)
* **[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`)
* **[Environments API](https://platform.claude.com/docs/en/managed-agents/environments)**: Configure sandbox templates for agent sessions (`POST /v1/environments`, `GET /v1/environments`)
For 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).
## Authentication
For details on both authentication methods and when to use each, see [Authentication](https://platform.claude.com/docs/en/manage-claude/authentication). All requests to the Claude API must include these headers:
| Header | Value | Required |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| `x-api-key` | Your API key from Console | One of `x-api-key` or `Authorization` |
| `Authorization` | `Bearer <token>`, where `<token>` is 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) | One of `x-api-key` or `Authorization` |
| `anthropic-version` | API version (for example, `2023-06-01`) | Yes |
| `content-type` | `application/json` | Yes |
If you are using the [Client SDKs](https://platform.claude.com/docs/en/api/overview#client-sdks), the SDK will send these headers automatically. For API versioning details, see [API versions](https://platform.claude.com/docs/en/api/versioning).
When accessing Claude through a [cloud platform](https://platform.claude.com/docs/en/api/overview#claude-api-vs-cloud-platforms), authentication is integrated with the cloud provider's IAM system. See the platform-specific documentation for supported credential types, required headers, and authentication options.
### Getting API keys
The API is made available through the web [Console](https://platform.claude.com/). You can use the [Workbench](https://platform.claude.com/playground) to try out the API in the browser and then generate API keys in [Account Settings](https://platform.claude.com/settings/keys). You choose each key's [expiration](https://platform.claude.com/docs/en/manage-claude/authentication#key-expiration) when you create it. Use [workspaces](https://platform.claude.com/settings/workspaces) to segment your API keys and [control spend](https://platform.claude.com/docs/en/api/rate-limits) by use case.
## Client SDKs
Anthropic provides official SDKs that simplify API integration by handling authentication, request formatting, error handling, and more.
**Benefits:**
* Automatic header management (`x-api-key`, `anthropic-version`, `content-type`)
* Type-safe request and response handling
* Built-in retry logic and error handling
* Streaming support
* Request timeouts and connection management
For a list of client SDKs, see [Client SDKs](https://platform.claude.com/docs/en/cli-sdks-libraries/overview).
## Claude API vs cloud platforms
Claude is available through the direct Claude API and through cloud platforms. Choose based on your infrastructure, feature availability, compliance requirements, and pricing preferences.
### Claude API
* **Direct access** to the latest models and features
* **Anthropic billing and support**
* **Best for:** New integrations, full feature access, direct relationship with Anthropic
### Cloud platform APIs
Access Claude through AWS, Google Cloud, or Microsoft Azure:
* **Integrated** with cloud provider billing and IAM
* **Feature availability varies by platform:** Anthropic-operated platforms include [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws) and [Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry); partner-operated platforms include Amazon Bedrock and Google Cloud. See each platform's page for feature availability and timing.
* **Best for:** Existing cloud commitments, specific compliance requirements, consolidated cloud billing
| Platform | Provider | Documentation |
| ---------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| Agent Platform | Google Cloud | [Claude on Google Cloud](https://platform.claude.com/docs/en/build-with-claude/claude-on-vertex-ai) |
| Amazon Bedrock | AWS | [Claude in Amazon Bedrock](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock) |
| Claude Platform on AWS | AWS (Anthropic-operated) | [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws) |
| Microsoft Foundry | Microsoft Azure (Anthropic-operated) | [Claude in Microsoft Foundry](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry) |
<Note>
Claude Managed Agents is available through the direct Claude API and [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws). For feature availability across platforms, see the [Features overview](https://platform.claude.com/docs/en/build-with-claude/overview).
</Note>
## Request and response format
### Request size limits
| Endpoint | Maximum request size |
| --------------------------------------------------------------------------------------------- | -------------------- |
| Messages, Token Counting | 32 MB |
| [Message Batches API](https://platform.claude.com/docs/en/build-with-claude/batch-processing) | 256 MB |
| [Files API](https://platform.claude.com/docs/en/build-with-claude/files) | 500 MB |
| Sessions, Agents, Environments | 32 MB |
If you exceed these limits, you'll receive a 413 `request_too_large` error.
<Note>
Partner-operated platforms have their own request size limits: Bedrock limits requests to 20 MB, and Google Cloud limits requests to 30 MB. Claude Platform on AWS uses the same limits as the direct Claude API. Consult your platform's documentation for current values.
</Note>
### Response headers
The Claude API includes the following headers in its responses:
| Header | Description |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `request-id` | A globally unique identifier for the request, such as `req_018EeWyXxfu5pfWkrYcMdjWG`. Include it when you contact support about a specific request. See [Request ID](https://platform.claude.com/docs/en/api/errors#request-id). |
| `anthropic-organization-id` | The ID of the organization that the API key or access token used in the request belongs to. |
| `anthropic-workspace-id` | The `wrkspc_`-prefixed ID of the [workspace](https://platform.claude.com/docs/en/manage-claude/workspaces) that the API key or access token resolved to, such as `wrkspc_01JwQvzr7rXLA5AGx3HKfFUJ`, including when that is your organization's Default Workspace. Absent when the credential doesn't resolve to a workspace (for example, on Admin API requests) or the request fails before authentication completes. See [Identify the workspace behind an API response](https://platform.claude.com/docs/en/manage-claude/workspaces#identify-the-workspace-behind-an-api-response). |
For the rate limit headers, see [Response headers](https://platform.claude.com/docs/en/api/rate-limits#response-headers) in Rate limits. For examples that read a response header by name with each SDK, see [Identify the workspace behind an API response](https://platform.claude.com/docs/en/manage-claude/workspaces#identify-the-workspace-behind-an-api-response).
<Note>
Claude Platform on AWS adds an AWS request ID (`x-amzn-requestid`) alongside the standard `request-id` header. See [Request IDs](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#request-ids) for the dual-ID handling pattern.
</Note>
## Pagination
List endpoints return results in pages. Most newer list endpoints use the `page` and `next_page` cursor scheme described in this section. Some use a different scheme; see the note at the end of this section. Use the `limit` query parameter to control the page size and the `page` query parameter to fetch an adjacent page. Each response includes a `data` array alongside cursor fields for navigating between pages.
| Name | Location | Description |
| ----------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `limit` | Query parameter | Maximum number of items to return per page. |
| `page` | Query parameter | Opaque cursor from a previous response. Pass a `next_page` or `prev_page` value here to fetch the adjacent page. |
| `order` | Query parameter | Sort direction for the results (`asc` or `desc`), on list endpoints that support sorting. A `page` cursor is only valid with the `order` it was created with. |
| `next_page` | Response field | Cursor for the next page, or `null` if there are no more results. |
| `prev_page` | Response field | Cursor for the previous page on endpoints that support backward pagination (currently `GET /v1/sessions`), or `null` if you are on the first page. Other list endpoints omit the field. |
To 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).
Every SDK provides an auto-paginating iterator that follows `next_page` for you. In Python and TypeScript, you get it by iterating the list result directly. The other SDKs provide the iterator through a separate method. 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 language-specific details.
<Note>
Some list endpoints use a different cursor scheme. The [Message Batches API](https://platform.claude.com/docs/en/build-with-claude/batch-processing), the [Files API](https://platform.claude.com/docs/en/build-with-claude/files), 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`. Some endpoints that use the `page` scheme, such as `GET /v1/skills`, also return a `has_more` Boolean alongside `next_page`. See the reference page for each endpoint for its exact pagination fields.
</Note>
## Rate limits and availability
### Rate limits
The 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:
* **Spend limits**: Maximum monthly cost for API usage
* **Rate limits**: Maximum number of requests per minute (RPM) and tokens per minute (TPM)
You can view your rate limits on the [Rate limits](https://platform.claude.com/settings/limits) page and your spend limits on the [Billing](https://platform.claude.com/settings/billing) page in the Console. For higher rate limits or a higher monthly spend cap, use **Request rate limit increase** on the Rate limits page.
For 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).
### Availability
The Claude API is available in [many countries and regions](https://platform.claude.com/docs/en/api/supported-regions) worldwide. Check the supported regions page to confirm availability in your location.
## Next steps
<CardGroup cols={2}>
<Card title="Messages API reference" icon="book" href="https://platform.claude.com/docs/en/api/messages/create">
Complete API specification for direct model interactions
</Card>
<Card title="Claude Managed Agents reference" icon="brain" href="https://platform.claude.com/docs/en/managed-agents/sessions">
Agents, Sessions, and Environments endpoints
</Card>
<Card title="Client SDKs" icon="code" href="https://platform.claude.com/docs/en/cli-sdks-libraries/overview">
Python, TypeScript, C#, Go, Java, PHP, and Ruby
</Card>
<Card title="Rate limits" icon="gauge" href="https://platform.claude.com/docs/en/api/rate-limits">
Usage tiers, requesting higher limits, and the token bucket algorithm
</Card>
</CardGroup>
api/rate-limits First recorded · 272 lines, first recorded
## About rate limits ## Spend limits ## Rate limits ### Cache-aware ITPM ### Message Batches API ### Managed Agents ### Fast mode rate limits ### Monitoring your rate limits in the Console ## Requesting higher limits ## Setting lower limits for Workspaces ## Response headers
The first capture of this source. The page was already there, and this is what it said.
---
title: Rate limits
url: https://platform.claude.com/docs/en/api/rate-limits
description: To mitigate misuse and manage capacity on the API, limits are in place on how much an organization can use the Claude API.
---
<Note>
**[Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws):** The rate limits on this page apply to Claude Platform on AWS, but billing and limit management differ. Billing is through AWS Marketplace (not Anthropic credit purchases). Organizations on Claude Platform on AWS are placed on the Start tier and do not move between usage tiers automatically. To request higher limits, contact your Anthropic account representative or [Anthropic support](https://support.claude.com); the **Request rate limit increase** flow is not available. Per-workspace rate limit configuration and [fast mode](https://platform.claude.com/docs/en/build-with-claude/fast-mode) are not available on Claude Platform on AWS. For details, 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).
</Note>
There are two types of limits:
1. **Spend limits** set a maximum monthly cost an organization can incur for API usage.
2. **Rate limits** set the maximum number of API requests an organization can make over a defined period of time.
The API enforces service-configured limits at the organization level, but you may also set user-configurable limits for your organization's workspaces.
## About rate limits
* Limits are designed to prevent API abuse, while minimizing impact on common customer usage patterns.
* Limits are defined by **usage tier**. Organizations are placed on a tier automatically based on usage history and account standing and can move to a higher tier over time as they use the API.
* New organizations and organizations with limited usage history may start in the Evaluation tier, with limits below the standard limits shown on this page while account history is established. These starting limits are part of how Anthropic prevents fraud and abuse, and they increase automatically as your organization builds usage history.
* Limits are set at the organization level. You can see your organization's tier and current limits on the [Rate limits](https://platform.claude.com/settings/limits) page in the [Claude Console](https://platform.claude.com/).
* You might hit rate limits over shorter time intervals. For instance, a rate of 60 requests per minute (RPM) might be enforced as 1 request per second. Short bursts of requests can exceed the limit and trigger rate limit errors.
* The following limits are the standard limits for each tier. If you need higher limits, see [Requesting higher limits](https://platform.claude.com/docs/en/api/rate-limits#requesting-higher-limits).
* The API uses the [token bucket algorithm](https://en.wikipedia.org/wiki/Token_bucket) to do rate limiting. This means that your capacity is continuously replenished up to your maximum limit, rather than being reset at fixed intervals.
* All limits described here represent maximum allowed usage, not guaranteed minimums. These limits are intended to reduce unintentional overspend and ensure fair distribution of resources among users.
## Spend limits
<Note>
**[Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws):** Spend limits work differently on Claude Platform on AWS. See [Spend limits on Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws#spend-limits) for how spend caps and self-set spend limits apply to your organization.
</Note>
Each of the Start, Build, and Scale tiers carries a monthly spend cap, which is the maximum your organization can spend on the API each calendar month. Once you reach your tier's spend cap, API usage pauses until the next month unless you request a higher limit. You can view your organization's monthly spend cap and set your own limit on the [Billing](https://platform.claude.com/settings/billing) page.
| Usage tier | Monthly spend cap |
| ---------- | ----------------- |
| Start | $500 USD |
| Build | $1,000 USD |
| Scale | $200,000 USD |
Organizations on the Custom tier have no monthly spend cap; limits are arranged with their account team.
You can also set your own spend limit below your tier's cap to control costs:
<Steps>
<Step title="Navigate to the Billing page">
Go to [Settings > Billing](https://platform.claude.com/settings/billing) in the Claude Console.
</Step>
<Step title="Open the spend limit editor">
In the **Spend limits** section, click **Adjust limit** (or **Set limit** if no limit is currently set).
</Step>
<Step title="Adjust your spend limit">
Enter a new value. Your spend limit cannot exceed your current tier's cap.
</Step>
</Steps>
## Rate limits
The 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, along with a `retry-after` header indicating how long to wait.
<Note>
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.
</Note>
### Cache-aware ITPM
Many 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.
ITPM 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.
Here's what counts toward ITPM:
* `input_tokens` (tokens after the last cache breakpoint) ✓ **Count toward ITPM**
* `cache_creation_input_tokens` (tokens being written to cache) ✓ **Count toward ITPM**
* `cache_read_input_tokens` (tokens read from cache) ✗ **Do NOT count toward ITPM** for most models
<Note>
The `input_tokens` field only represents tokens that appear **after your last cache breakpoint**, not all input tokens in your request. To calculate total input tokens:
```text wrap
total_input_tokens = cache_read_input_tokens + cache_creation_input_tokens + input_tokens
```
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.
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.
</Note>
**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.
<Note>
Claude Haiku 3.5 (marked with † in the following rate limit tables) also counts `cache_read_input_tokens` toward ITPM rate limits.
For all models without the † marker, cached input tokens do not count toward rate limits and are billed at a reduced rate (10% of base input token 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).
</Note>
To 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) to tune your caching strategy.
OTPM 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.
Rate limits are applied separately for each model; therefore you can use different models up to their respective limits simultaneously. You can check your current rate limits and behavior on the [Rate limits](https://platform.claude.com/settings/limits) page in the Claude Console, or read the configured limits programmatically with the [Rate Limits API](https://platform.claude.com/docs/en/manage-claude/rate-limits-api).
<Note>
Rate limits are currently shared across all `inference_geo` values. Requests with `inference_geo: "us"` and `inference_geo: "global"` draw from the same rate limit pool.
</Note>
<Tabs>
<Tab title="Start tier">
| Model | Maximum requests per minute (RPM) | Maximum input tokens per minute (ITPM) | Maximum output tokens per minute (OTPM) |
| ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | -------------------------------------- | --------------------------------------- |
| Claude Fable 5 | 1,000 | 500,000 | 100,000 |
| Claude Opus 5 | 1,000 | 2,000,000 | 400,000 |
| Claude Opus 4.x\* | 1,000 | 2,000,000 | 400,000 |
| Claude Sonnet 5 | 1,000 | 2,000,000 | 400,000 |
| Claude Sonnet 4.x\*\* | 1,000 | 2,000,000 | 400,000 |
| Claude Haiku 4.5 | 1,000 | 2,000,000 | 400,000 |
| Claude Haiku 3.5 ([retired, except on Bedrock and Google Cloud](https://platform.claude.com/docs/en/about-claude/model-deprecations)) | 1,000 | 100,000† | 20,000 |
</Tab>
<Tab title="Build tier">
| Model | Maximum requests per minute (RPM) | Maximum input tokens per minute (ITPM) | Maximum output tokens per minute (OTPM) |
| ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | -------------------------------------- | --------------------------------------- |
| Claude Fable 5 | 2,000 | 1,500,000 | 300,000 |
| Claude Opus 5 | 5,000 | 5,000,000 | 1,000,000 |
| Claude Opus 4.x\* | 5,000 | 5,000,000 | 1,000,000 |
| Claude Sonnet 5 | 5,000 | 5,000,000 | 1,000,000 |
| Claude Sonnet 4.x\*\* | 5,000 | 5,000,000 | 1,000,000 |
| Claude Haiku 4.5 | 5,000 | 5,000,000 | 1,000,000 |
| Claude Haiku 3.5 ([retired, except on Bedrock and Google Cloud](https://platform.claude.com/docs/en/about-claude/model-deprecations)) | 2,000 | 200,000† | 40,000 |
</Tab>
<Tab title="Scale tier">
| Model | Maximum requests per minute (RPM) | Maximum input tokens per minute (ITPM) | Maximum output tokens per minute (OTPM) |
| ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | -------------------------------------- | --------------------------------------- |
| Claude Fable 5 | 4,000 | 4,000,000 | 800,000 |
| Claude Opus 5 | 10,000 | 10,000,000 | 2,000,000 |
| Claude Opus 4.x\* | 10,000 | 10,000,000 | 2,000,000 |
| Claude Sonnet 5 | 10,000 | 10,000,000 | 2,000,000 |
| Claude Sonnet 4.x\*\* | 10,000 | 10,000,000 | 2,000,000 |
| Claude Haiku 4.5 | 10,000 | 10,000,000 | 2,000,000 |
| Claude Haiku 3.5 ([retired, except on Bedrock and Google Cloud](https://platform.claude.com/docs/en/about-claude/model-deprecations)) | 4,000 | 400,000† | 80,000 |
</Tab>
<Tab title="Custom tier">
If you need limits higher than the Scale tier, contact sales through the [Rate limits](https://platform.claude.com/settings/limits) page in the Claude Console.
</Tab>
</Tabs>
*\* Opus rate limit is a total limit that applies to combined traffic across Claude Opus 4.8, Opus 4.7, Opus 4.6, and Opus 4.5. Claude Opus 5 has a separate rate limit and is not part of this combined bucket.*
*\*\* Sonnet 4.x rate limit is a total limit that applies to combined traffic across Sonnet 4.6 and Sonnet 4.5. Claude Sonnet 5 has a separate rate limit and is not part of this combined bucket.*
*† Limit counts `cache_read_input_tokens` toward ITPM usage.*
### Message Batches API
The 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.
<Tabs>
<Tab title="Start tier">
| Maximum requests per minute (RPM) | Maximum batch requests in processing queue | Maximum batch requests per batch |
| --------------------------------- | ------------------------------------------ | -------------------------------- |
| 1,000 | 200,000 | 100,000 |
</Tab>
<Tab title="Build tier">
| Maximum requests per minute (RPM) | Maximum batch requests in processing queue | Maximum batch requests per batch |
| --------------------------------- | ------------------------------------------ | -------------------------------- |
| 2,000 | 300,000 | 100,000 |
</Tab>
<Tab title="Scale tier">
| Maximum requests per minute (RPM) | Maximum batch requests in processing queue | Maximum batch requests per batch |
| --------------------------------- | ------------------------------------------ | -------------------------------- |
| 4,000 | 500,000 | 100,000 |
</Tab>
<Tab title="Custom tier">
If you need limits higher than the Scale tier, contact sales through the [Rate limits](https://platform.claude.com/settings/limits) page in the Claude Console.
</Tab>
</Tabs>
### Managed Agents
[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.
| Operation | Limit |
| ------------------------------------------------------------------ | ------------------------- |
| Create endpoints (for example, agents, sessions, and environments) | 300 requests per minute |
| Read endpoints (for example, retrieve, list, and stream) | 1,200 requests per minute |
### Fast mode rate limits
When using [fast mode](https://platform.claude.com/docs/en/build-with-claude/fast-mode) (research preview) with `speed: "fast"` on Claude Opus 5 or Opus 4.8, dedicated rate limits apply that are separate from standard Opus rate limits. When fast mode rate limits are exceeded, the API returns a `429` error with a `retry-after` header. Fast mode is not available on Claude Opus 4.7 (requests return an error) or Claude Opus 4.6 (requests to `claude-opus-4-6` with `speed: "fast"` run at standard speed). See [Fast mode](https://platform.claude.com/docs/en/build-with-claude/fast-mode#supported-models).
The response includes `anthropic-fast-*` headers that indicate your fast mode rate limit status. See [Fast mode rate limits](https://platform.claude.com/docs/en/build-with-claude/fast-mode#rate-limits) for details on these headers.
### Monitoring your rate limits in the Console
You can monitor your rate limit usage on the [Usage](https://platform.claude.com/usage) page of the [Claude Console](https://platform.claude.com/).
In 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):
* The **Rate Limit - Input Tokens** chart includes:
* Hourly maximum uncached input tokens per minute
* Your current input tokens per minute rate limit
* The cache rate for your input tokens (that is, the percentage of input tokens read from the cache)
* The **Rate Limit - Output Tokens** chart includes:
* Hourly maximum output tokens per minute
* Your current output tokens per minute rate limit
## Requesting higher limits
To request higher rate limits or a higher monthly spend cap, use **Request rate limit increase** on the [Rate limits](https://platform.claude.com/settings/limits) page. Anthropic support can also raise limits; for urgent needs, contact [Anthropic support](https://support.claude.com).
<Note>
**[Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws):** The **Request rate limit 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).
</Note>
## Setting lower limits for Workspaces
For more about workspaces, see [Workspaces](https://platform.claude.com/docs/en/manage-claude/workspaces).
To protect Workspaces in your Organization from potential overuse, you can set custom spend and rate limits per Workspace.
Example: 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.
Note:
* You can't set limits on the default Workspace.
* If not set, Workspace limits match the Organization's limit.
* Workspace limits are set per limiter type (such as requests per minute, input tokens per minute, or output tokens per minute).
* Organization-wide limits always apply, even if Workspace limits add up to more.
To 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).
## Response headers
The API response includes headers that show you the rate limit enforced, current usage, and when the limit will be reset.
The following headers are returned:
| Header | Description |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `retry-after` | The number of seconds to wait until you can retry the request. Earlier retries will fail. |
| `anthropic-ratelimit-requests-limit` | The maximum number of requests allowed within any rate limit period. |
| `anthropic-ratelimit-requests-remaining` | The number of requests remaining before being rate limited. |
| `anthropic-ratelimit-requests-reset` | The time when the request rate limit will be fully replenished, provided in RFC 3339 format. |
| `anthropic-ratelimit-tokens-limit` | The maximum number of tokens allowed within any rate limit period. |
| `anthropic-ratelimit-tokens-remaining` | The number of tokens remaining (rounded to the nearest thousand) before being rate limited. |
| `anthropic-ratelimit-tokens-reset` | The time when the token rate limit will be fully replenished, provided in RFC 3339 format. |
| `anthropic-ratelimit-input-tokens-limit` | The maximum number of input tokens allowed within any rate limit period. |
| `anthropic-ratelimit-input-tokens-remaining` | The number of input tokens remaining (rounded to the nearest thousand) before being rate limited. |
| `anthropic-ratelimit-input-tokens-reset` | The time when the input token rate limit will be fully replenished, provided in RFC 3339 format. |
| `anthropic-ratelimit-output-tokens-limit` | The maximum number of output tokens allowed within any rate limit period. |
| `anthropic-ratelimit-output-tokens-remaining` | The number of output tokens remaining (rounded to the nearest thousand) before being rate limited. |
| `anthropic-ratelimit-output-tokens-reset` | The time when the output token rate limit will be fully replenished, provided in RFC 3339 format. |
| `anthropic-priority-input-tokens-limit` | The maximum number of Priority Tier input tokens allowed within any rate limit period. (Priority Tier only) |
| `anthropic-priority-input-tokens-remaining` | The number of Priority Tier input tokens remaining (rounded to the nearest thousand) before being rate limited. (Priority Tier only) |
| `anthropic-priority-input-tokens-reset` | The time when the Priority Tier input token rate limit will be fully replenished, provided in RFC 3339 format. (Priority Tier only) |
| `anthropic-priority-output-tokens-limit` | The maximum number of Priority Tier output tokens allowed within any rate limit period. (Priority Tier only) |
| `anthropic-priority-output-tokens-remaining` | The number of Priority Tier output tokens remaining (rounded to the nearest thousand) before being rate limited. (Priority Tier only) |
| `anthropic-priority-output-tokens-reset` | The time when the Priority Tier output token rate limit will be fully replenished, provided in RFC 3339 format. (Priority Tier only) |
The `anthropic-ratelimit-tokens-*` headers display the values for the most restrictive limit currently in effect. For instance, if you have exceeded the Workspace per-minute token limit, the headers will contain the Workspace per-minute token rate limit values. If Workspace limits do not apply, the headers will return the total tokens remaining, where total is the sum of input and output tokens. This approach ensures that you have visibility into the most relevant constraint on your current API usage. To see which Workspace a request counted against, read the `anthropic-workspace-id` [response header](https://platform.claude.com/docs/en/api/overview#response-headers), which carries the ID of the Workspace that your API key or access token resolved to.
api/service-tiers First recorded · 234 lines, first recorded
## Standard Tier ## Priority Tier ## How requests get assigned tiers ## Using service tiers ## Existing Priority Tier commitments ### Supported models
The first capture of this source. The page was already there, and this is what it said.
---
title: Service tiers
url: https://platform.claude.com/docs/en/api/service-tiers
description: Different tiers of service allow you to balance availability, performance, and predictable costs based on your application's needs.
---
<Warning>
Priority Tier capacity commitments are no longer available for purchase. Organizations with an existing commitment can continue to use Priority Tier through their contract end date, and this page remains available as a reference for them. If you need guaranteed capacity, [contact sales](https://claude.com/contact-sales).
</Warning>
Anthropic offers three service tiers:
* **Priority Tier:** Available only to organizations with an existing capacity commitment
* **Standard:** Default tier for both piloting and scaling everyday use cases
* **Batch:** Best for asynchronous workflows that can wait or benefit from being outside your normal capacity
## Standard Tier
The standard tier is the default service tier for all API requests. The API prioritizes these requests alongside all other requests with best-effort availability.
## Priority Tier
The API prioritizes requests in this tier over all other requests. This prioritization helps minimize ["server overloaded" errors](https://platform.claude.com/docs/en/api/errors#http-errors), even during peak times.
For more information, see [Existing Priority Tier commitments](https://platform.claude.com/docs/en/api/service-tiers#existing-priority-tier-commitments).
## How requests get assigned tiers
When handling a request, Anthropic decides to assign a request to Priority Tier in the following scenarios:
* Your organization has sufficient Priority Tier capacity **input** tokens per minute
* Your organization has sufficient Priority Tier capacity **output** tokens per minute
Anthropic counts usage against Priority Tier capacity as follows:
**Input tokens**
* Cache reads as 0.1 tokens per token read from the cache
* Cache writes as 1.25 tokens per token written to the cache with a 5 minute TTL
* Cache writes as 2.00 tokens per token written to the cache with a 1 hour TTL
* 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
* All other input tokens are 1 token per token
**Output tokens**
* 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, output tokens are 1.1 tokens per token
* All other output tokens are 1 token per token
Otherwise, requests proceed at standard tier.
<Note>
These burndown rates reflect the relative pricing of each token type. For example, US-only inference is priced at 1.1x on Claude 4.6 and later models, so each token consumed with `inference_geo: "us"` draws down 1.1 tokens from your Priority Tier capacity.
</Note>
<Note>
Requests assigned Priority Tier pull from both the Priority Tier capacity and the regular rate limits. If servicing the request would exceed the rate limits, the request is declined.
</Note>
## Using service tiers
You can control which service tiers can be used for a request by setting the `service_tier` parameter:
<CodeGroup>
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-opus-4-8",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "Hello, Claude!"}],
"service_tier": "auto"
}'
```
```bash CLI
ant messages create \
--transform usage.service_tier \
--raw-output <<'YAML'
model: claude-opus-4-8
max_tokens: 1024
messages:
- role: user
content: Hello, Claude!
service_tier: auto # Automatically use Priority Tier when available, fallback to standard
YAML
```
```python Python
client = anthropic.Anthropic()
message = client.messages.create(
model="claude-opus-4-8",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello, Claude!"}],
service_tier="auto", # Automatically use Priority Tier when available, fallback to standard
)
print(message.usage.service_tier)
```
```typescript TypeScript
const client = new Anthropic();
const message = await client.messages.create({
model: "claude-opus-4-8",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello, Claude!" }],
service_tier: "auto" // Automatically use Priority Tier when available, fallback to standard
});
console.log(message.usage.service_tier);
```
```csharp C#
AnthropicClient client = new();
var message = await client.Messages.Create(new MessageCreateParams
{
Model = Model.ClaudeOpus4_8,
MaxTokens = 1024,
Messages = [new() { Role = Role.User, Content = "Hello, Claude!" }],
ServiceTier = ServiceTier.Auto, // Automatically use Priority Tier when available, fallback to standard
});
Console.WriteLine(message.Usage.ServiceTier);
```
```go Go
client := anthropic.NewClient()
message, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus4_8,
MaxTokens: 1024,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Hello, Claude!")),
},
// Automatically use Priority Tier when available, fallback to standard
ServiceTier: anthropic.MessageNewParamsServiceTierAuto,
})
if err != nil {
log.Fatal(err)
}
fmt.Println(message.Usage.ServiceTier)
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_4_8)
.maxTokens(1024L)
.addUserMessage("Hello, Claude!")
// Automatically use Priority Tier when available, fallback to standard
.serviceTier(MessageCreateParams.ServiceTier.AUTO)
.build();
Message message = client.messages().create(params);
IO.println(message.usage().serviceTier().orElseThrow());
```
```php PHP
$client = new Client();
$message = $client->messages->create(
model: 'claude-opus-4-8',
maxTokens: 1024,
messages: [['role' => 'user', 'content' => 'Hello, Claude!']],
serviceTier: 'auto', // Automatically use Priority Tier when available, fallback to standard
);
echo $message->usage->serviceTier;
```
```ruby Ruby
client = Anthropic::Client.new
message = client.messages.create(
model: "claude-opus-4-8",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello, Claude!" }],
service_tier: :auto # Automatically use Priority Tier when available, fallback to standard
)
puts(message.usage.service_tier)
```
</CodeGroup>
The `service_tier` parameter accepts the following values:
* `"auto"` (default) - Uses the Priority Tier capacity if available, falling back to your other capacity if not
* `"standard_only"` - Only use standard tier capacity, useful if you don't want to use your Priority Tier capacity
The response `usage` object also includes the service tier assigned to the request:
```json
{
"usage": {
"input_tokens": 410,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 0,
"output_tokens": 585,
"service_tier": "priority"
}
}
```
This allows you to determine which service tier was assigned to the request.
When requesting `service_tier="auto"` with a model with a Priority Tier commitment, these response headers provide insights:
```text wrap
anthropic-priority-input-tokens-limit: 10000
anthropic-priority-input-tokens-remaining: 9618
anthropic-priority-input-tokens-reset: 2025-01-12T23:11:59Z
anthropic-priority-output-tokens-limit: 10000
anthropic-priority-output-tokens-remaining: 6000
anthropic-priority-output-tokens-reset: 2025-01-12T23:12:21Z
```
You can use the presence of these headers to detect if your request was eligible for Priority Tier, even if it was over the limit.
## Existing Priority Tier commitments
A Priority Tier commitment consists of:
* A number of input tokens per minute
* A number of output tokens per minute
* A commitment duration (1, 3, 6, or 12 months)
* A specific model version
Priority Tier targets 99.5% uptime with prioritized computational resources. Requests beyond your committed capacity automatically fall back to standard tier.
### Supported models
Priority Tier is supported on all available Claude models except Claude Mythos 5, [Claude Mythos Preview](https://anthropic.com/glasswing), Claude Opus 5, and Claude Sonnet 5.
Check the [Models overview](https://platform.claude.com/docs/en/about-claude/models/overview) for more details on available models.
api/supported-regions First recorded · 181 lines, first recorded
The first capture of this source. The page was already there, and this is what it said.
--- title: Supported regions url: https://platform.claude.com/docs/en/api/supported-regions description: "Here are the countries, regions, and territories we can currently support access from:" --- * Albania * Algeria * Andorra * Angola * Antigua and Barbuda * Argentina * Armenia * Australia * Austria * Azerbaijan * Bahamas * Bahrain * Bangladesh * Barbados * Belgium * Belize * Benin * Bhutan * Bolivia * Bosnia and Herzegovina * Botswana * Brazil * Brunei * Bulgaria * Burkina Faso * Burundi * Cabo Verde * Cambodia * Cameroon * Canada * Chad * Chile * Colombia * Comoros * Congo, Republic of the * Costa Rica * Côte d'Ivoire * Croatia * Cyprus * Czechia (Czech Republic) * Denmark * Djibouti * Dominica * Dominican Republic * Ecuador * Egypt * El Salvador * Equatorial Guinea * Estonia * Eswatini * Fiji * Finland * France * Gabon * Gambia * Georgia * Germany * Ghana * Greece * Grenada * Guatemala * Guinea * Guinea-Bissau * Guyana * Haiti * Holy See (Vatican City) * Honduras * Hungary * Iceland * India * Indonesia * Iraq * Ireland * Israel * Italy * Jamaica * Japan * Jordan * Kazakhstan * Kenya * Kiribati * Kuwait * Kyrgyzstan * Laos * Latvia * Lebanon * Lesotho * Liberia * Liechtenstein * Lithuania * Luxembourg * Madagascar * Malawi * Malaysia * Maldives * Malta * Marshall Islands * Mauritania * Mauritius * Mexico * Micronesia * Moldova * Monaco * Mongolia * Montenegro * Morocco * Mozambique * Namibia * Nauru * Nepal * Netherlands * New Zealand * Niger * Nigeria * North Macedonia * Norway * Oman * Pakistan * Palau * Palestine * Panama * Papua New Guinea * Paraguay * Peru * Philippines * Poland * Portugal * Qatar * Romania * Rwanda * Saint Kitts and Nevis * Saint Lucia * Saint Vincent and the Grenadines * Samoa * San Marino * Sao Tome and Principe * Saudi Arabia * Senegal * Serbia * Seychelles * Sierra Leone * Singapore * Slovakia * Slovenia * Solomon Islands * South Africa * South Korea * Spain * Sri Lanka * Suriname * Sweden * Switzerland * Taiwan * Tajikistan * Tanzania * Thailand * Timor-Leste, Democratic Republic of * Togo * Tonga * Trinidad and Tobago * Tunisia * Turkey * Turkmenistan * Tuvalu * Uganda * Ukraine (except Crimea, Donetsk, and Luhansk regions) * United Arab Emirates * United Kingdom * United States of America * Uruguay * Uzbekistan * Vanuatu * Vietnam * Zambia * Zimbabwe
api/versioning First recorded · 35 lines, first recorded
## Version history
The first capture of this source. The page was already there, and this is what it said.
---
title: Versions
url: https://platform.claude.com/docs/en/api/versioning
description: "When making API requests, you must send an `anthropic-version` request header. For example, `anthropic-version: 2023-06-01`. If you are using the [client SDKs](https://platform.claude.com/docs/en/cli-sdks-libraries/overview), this is handled for you automatically."
---
For any given version with the Messages API, Anthropic preserves:
* Existing input parameters
* Existing output parameters
However, Anthropic may do the following:
* Add additional optional inputs
* Add additional values to the output
* Change conditions for specific error types
* Add new variants to enum-like output values (for example, streaming event types)
Generally, if you are using the API as documented in this reference, Anthropic will not break your usage.
## Version history
Anthropic recommends using the latest API version whenever possible. Previous versions are considered deprecated and may be unavailable for new users.
* `2023-06-01`
* New format for [streaming](https://platform.claude.com/docs/en/build-with-claude/streaming) server-sent events (SSE):
* Completions are incremental. For example, `" Hello"`, `" my"`, `" name"`, `" is"`, `" Claude." `instead of `" Hello"`, `" Hello my"`, `" Hello my name"`, `" Hello my name is"`, `" Hello my name is Claude."`.
* All events are [named events](https://developer.mozilla.org/en-US/Web/API/Server-sent%5Fevents/Using%5Fserver-sent%5Fevents#named%5Fevents), rather than [data-only events](https://developer.mozilla.org/en-US/Web/API/Server-sent%5Fevents/Using%5Fserver-sent%5Fevents#data-only%5Fmessages).
* Removed unnecessary `data: [DONE]` event.
* Removed legacy `exception` and `truncated` values in responses.
* `2023-01-01`: Initial release.
build-with-claude/batch-processing First recorded · 1887 lines, first recorded
# Message Batches API ## How the Message Batches API works ### Batch limitations ### Supported models ### What can be batched ## Pricing ## How to use the Message Batches API ### Prepare and create your batch ### Tracking your batch #### Polling for Message Batch completion ### Listing all Message Batches ### Retrieving batch results ### Canceling a Message Batch ### Using prompt caching with Message Batches ### Server tools and the agentic loop ### Extended output (beta) ### Best practices for effective batching ### Troubleshooting common issues ## Batch storage and privacy ## Data retention ## FAQ ## Next steps
The first capture of this source. The page was already there, and this is what it said.
---
title: Batch processing
url: https://platform.claude.com/docs/en/build-with-claude/batch-processing
description: Process large volumes of Messages requests asynchronously with the Message Batches API, cutting costs by 50% and increasing throughput.
---
Batch 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:
* You need to process large volumes of data
* Immediate responses are not required
* You want to optimize for cost efficiency
* You're running large-scale evaluations or analyses
The Message Batches API is Anthropic's first implementation of this pattern.
<Note>
For how zero data retention (ZDR) applies to this feature, see [API and data retention](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention).
</Note>
# Message Batches API
The Message Batches API is a powerful, cost-effective way to asynchronously process large volumes of [Messages](https://platform.claude.com/docs/en/api/messages/create) requests. This approach is well-suited to tasks that do not require immediate responses, with most batches finishing in less than 1 hour while reducing costs by 50% and increasing throughput.
You can [explore the API reference directly](https://platform.claude.com/docs/en/api/messages/batches/create), in addition to this guide.
## How the Message Batches API works
When you send a request to the Message Batches API:
1. The system creates a new Message Batch with the provided Messages requests.
2. The batch is then processed asynchronously, with each request handled independently.
3. You can poll for the status of the batch and retrieve results when processing has ended for all requests.
This is especially useful for bulk operations that don't require immediate results, such as:
* Large-scale evaluations: Process thousands of test cases efficiently.
* Content moderation: Analyze large volumes of user-generated content asynchronously.
* Data analysis: Generate insights or summaries for large datasets.
* Bulk content generation: Create large amounts of text for various purposes (for example, product descriptions, article summaries).
### Batch limitations
* A Message Batch is limited to either 100,000 Message requests or 256 MB in size, whichever is reached first.
* 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.
* 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.
* Batches are scoped to a [Workspace](https://platform.claude.com/settings/workspaces). You may view all batches (and their results) that were created within the Workspace that your API key belongs to.
* 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.
* Because of high throughput and concurrent processing, batches may go slightly over your Workspace's configured [spend limit](https://platform.claude.com/settings/billing).
* 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.
### Supported models
All [active models](https://platform.claude.com/docs/en/about-claude/models/overview) support the Message Batches API.
### What can be batched
Almost any request you can make to the Messages API can be included in a batch. This includes:
* Vision
* Tool use, including all [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)
* System messages
* Multi-turn conversations
* Extended thinking
* Most beta features
Because each request in the batch is processed independently, you can mix different types of requests within a single batch.
A small number of Messages API parameters are **not** supported in batch requests. Including any of these returns a validation error:
| Parameter | Why |
| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `stream: true` | Batch results come back as a single file, not a stream. |
| `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. |
| `store` / `previous_thread_event_id` (Threads) | Threads are stateful; batch requests are not. |
| `cache_hint` / `context_hint` | These routing hints apply to synchronous request scheduling only. |
| `max_tokens: 0` | See [Batch limitations](https://platform.claude.com/docs/en/build-with-claude/batch-processing#batch-limitations). |
| `research_preview_2026_02: "active"` | Research preview mode is not available on the batch path. |
<Tip>
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.
</Tip>
## Pricing
The Batches API offers significant cost savings. All usage is charged at 50% of the standard API prices.
| Model | Batch input | Batch output |
| ------------------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------- |
| Claude Fable 5 | $5 / MTok | $25 / MTok |
| Claude Mythos 5 ([limited availability](https://anthropic.com/glasswing)) | $5 / MTok | $25 / MTok |
| Claude Opus 5 | $2.50 / MTok | $12.50 / MTok |
| Claude Opus 4.8 | $2.50 / MTok | $12.50 / MTok |
| Claude Opus 4.7 | $2.50 / MTok | $12.50 / MTok |
| Claude Opus 4.6 | $2.50 / MTok | $12.50 / MTok |
| Claude Opus 4.5 | $2.50 / MTok | $12.50 / MTok |
| Claude Opus 4.1 ([retired, except on Bedrock and Google Cloud](https://platform.claude.com/docs/en/about-claude/model-deprecations)) | $7.50 / MTok | $37.50 / MTok |
| Claude Opus 4 ([retired, except on Google Cloud](https://platform.claude.com/docs/en/about-claude/model-deprecations)) | $7.50 / MTok | $37.50 / MTok |
| Claude Sonnet 5 | $1 / MTok | $5 / MTok |
| Claude Sonnet 4.6 | $1.50 / MTok | $7.50 / MTok |
| Claude Sonnet 4.5 | $1.50 / MTok | $7.50 / MTok |
| Claude Sonnet 4 ([retired, except on Bedrock and Google Cloud](https://platform.claude.com/docs/en/about-claude/model-deprecations)) | $1.50 / MTok | $7.50 / MTok |
| Claude Haiku 4.5 | $0.50 / MTok | $2.50 / MTok |
| Claude Haiku 3.5 ([retired, except on Bedrock and Google Cloud](https://platform.claude.com/docs/en/about-claude/model-deprecations)) | $0.40 / MTok | $2 / MTok |
## How to use the Message Batches API
### Prepare and create your batch
A Message Batch is composed of a list of requests to create a Message. The shape of an individual request comprises:
* A unique `custom_id` for identifying the Messages request. Must be 1 to 64 characters and contain only alphanumeric characters, hyphens, and underscores (matching `^[a-zA-Z0-9_-]{1,64}$`).
* A `params` object with the standard [Messages API](https://platform.claude.com/docs/en/api/messages/create) parameters
You can [create a batch](https://platform.claude.com/docs/en/api/messages/batches/create) by passing this list into the `requests` parameter:
<CodeGroup>
```bash cURL
curl https://api.anthropic.com/v1/messages/batches \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--data \
'{
"requests": [
{
"custom_id": "my-first-request",
"params": {
"model": "claude-opus-5",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Hello, world"}
]
}
},
{
"custom_id": "my-second-request",
"params": {
"model": "claude-opus-5",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Hi again, friend"}
]
}
}
]
}'
```
```bash CLI
ant messages:batches create <<'YAML'
requests:
- custom_id: my-first-request
params:
model: claude-opus-5
max_tokens: 1024
messages:
- role: user
content: Hello, world
- custom_id: my-second-request
params:
model: claude-opus-5
max_tokens: 1024
messages:
- role: user
content: Hi again, friend
YAML
```
```python Python
from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request
client = anthropic.Anthropic()
message_batch = client.messages.batches.create(
requests=[
Request(
custom_id="my-first-request",
params=MessageCreateParamsNonStreaming(
model="claude-opus-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": "Hello, world",
}
],
),
),
Request(
custom_id="my-second-request",
params=MessageCreateParamsNonStreaming(
model="claude-opus-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": "Hi again, friend",
}
],
),
),
]
)
print(message_batch)
```
```typescript TypeScript
const client = new Anthropic();
const messageBatch = await client.messages.batches.create({
requests: [
{
custom_id: "my-first-request",
params: {
model: "claude-opus-5",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello, world" }]
}
},
{
custom_id: "my-second-request",
params: {
model: "claude-opus-5",
max_tokens: 1024,
messages: [{ role: "user", content: "Hi again, friend" }]
}
}
]
});
console.log(messageBatch);
```
```csharp C#
using Anthropic;
using Anthropic.Models.Messages;
using Anthropic.Models.Messages.Batches;
AnthropicClient client = new();
var batch = await client.Messages.Batches.Create(new BatchCreateParams
{
Requests =
[
new()
{
CustomID = "my-first-request",
Params = new()
{
Model = Model.ClaudeOpus5,
MaxTokens = 1024,
Messages =
[
new() { Role = Role.User, Content = "Hello, world" }
]
}
},
new()
{
CustomID = "my-second-request",
Params = new()
{
Model = Model.ClaudeOpus5,
MaxTokens = 1024,
Messages =
[
new() { Role = Role.User, Content = "Hi again, friend" }
]
}
}
]
});
Console.WriteLine(batch);
```
```go Go
client := anthropic.NewClient()
batch, _ := client.Messages.Batches.New(context.Background(),
anthropic.MessageBatchNewParams{
Requests: []anthropic.MessageBatchNewParamsRequest{
{
CustomID: "my-first-request",
Params: anthropic.MessageBatchNewParamsRequestParams{
Model: anthropic.ModelClaudeOpus5,
MaxTokens: 1024,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(
anthropic.NewTextBlock("Hello, world"),
),
},
},
},
{
CustomID: "my-second-request",
Params: anthropic.MessageBatchNewParamsRequestParams{
Model: anthropic.ModelClaudeOpus5,
Cut at 300 lines. The page has the rest.