---
title: Processamento em lote
url: https://platform.claude.com/docs/pt-BR/build-with-claude/batch-processing
description: Processe grandes volumes de solicitações de Messages de forma assíncrona com a Message Batches API, reduzindo custos em 50 por cento e aumentando o throughput.
featureMetadata:
status: stable
zdr:
eligibility: not-eligible
note: Retenção de 29 dias; armazenamento assíncrono necessário.
supportedModels:
- claude-fable-5-2
- claude-mythos-5-2
- claude-fable-5-1
- claude-mythos-5-1
- claude-fable-5
- claude-mythos-5
- claude-mythos-preview
- claude-opus-5-5
- claude-opus-5
- claude-sonnet-5-5
- claude-sonnet-5
- claude-haiku-5-5
- claude-haiku-4-5-20251001
- claude-opus-4-8
- claude-opus-4-7
- claude-opus-4-6
- claude-sonnet-4-6
- claude-opus-4-5-20251101
- claude-sonnet-4-5-20250929
supportedPlatforms:
Claude API: stable
Claude Platform on AWS: stable
Claude Models on Google Cloud (Anthropic managed): stable
---
O “batch processing” (processamento em lote) é uma abordagem poderosa para lidar com grandes volumes de solicitações de forma eficiente. Em vez de processar solicitações uma de cada vez com respostas imediatas, o processamento em lote permite que você envie várias solicitações juntas para processamento assíncrono. Esse padrão é particularmente útil quando:
* Você precisa processar grandes volumes de dados
* Respostas imediatas não são necessárias
* Você deseja otimizar a eficiência de custos
* Você está executando avaliações ou análises em larga escala
A Message Batches API implementa esse padrão.
# Message Batches API
A Message Batches API é uma forma poderosa e econômica de processar de forma assíncrona grandes volumes de solicitações de [Messages](https://platform.claude.com/docs/pt-BR/api/messages/create). Essa abordagem é adequada para tarefas que não exigem respostas imediatas, com a maioria dos lotes sendo concluída em menos de 1 hora, reduzindo custos em 50 por cento e aumentando o “throughput” (vazão).
Além deste guia, você pode [explorar a referência da API diretamente](https://platform.claude.com/docs/pt-BR/api/messages/batches/create).
## Como a Message Batches API funciona
Quando você envia uma solicitação para a Message Batches API:
1. O sistema cria um novo lote de mensagens com as solicitações de Messages fornecidas.
2. O lote é então processado de forma assíncrona, com cada solicitação tratada de forma independente.
3. Você pode consultar o status do lote e recuperar os resultados quando o processamento tiver terminado para todas as solicitações.
Isso é especialmente útil para operações em massa que não exigem resultados imediatos, como:
* Avaliações em larga escala: processe milhares de casos de teste de forma eficiente.
* Moderação de conteúdo: analise grandes volumes de conteúdo gerado por usuários de forma assíncrona.
* Análise de dados: gere insights ou resumos para grandes conjuntos de dados.
* Geração de conteúdo em massa: crie grandes quantidades de texto para diversos fins (por exemplo, descrições de produtos, resumos de artigos).
### Limitações de lotes
* Um lote de mensagens é limitado a 100.000 solicitações de Message ou 256 MB de tamanho, o que for atingido primeiro.
* O sistema processa cada lote o mais rápido possível, com a maioria dos lotes sendo concluída em até 1 hora. Você pode acessar os resultados do lote quando todas as mensagens tiverem sido concluídas ou após 24 horas, o que ocorrer primeiro. Os lotes expiram se o processamento não for concluído em 24 horas.
* Os resultados do lote ficam disponíveis por 29 dias após a criação. Depois disso, você ainda pode visualizar o lote, mas seus resultados não estão mais disponíveis para download.
* Os lotes têm escopo em um [Workspace no Claude Console](https://platform.claude.com/settings/workspaces). Você pode visualizar todos os lotes (e seus resultados) que foram criados no Workspace em que sua solicitação é executada.
* Os “rate limits” (limites de taxa) se aplicam tanto às solicitações HTTP da Batches API quanto ao número de solicitações dentro de um lote aguardando processamento. Consulte [Limites de taxa da Message Batches API](https://platform.claude.com/docs/pt-BR/api/rate-limits#message-batches-api). Além disso, o processamento pode ficar mais lento com base na demanda atual e no volume de suas solicitações. Nesse caso, você poderá ver mais solicitações expirando após 24 horas.
* Devido ao alto throughput e ao processamento simultâneo, os lotes podem ultrapassar ligeiramente o [limite de gastos](https://platform.claude.com/docs/pt-BR/manage-claude/workspaces#setting-workspace-limits) configurado no Claude Console para o seu Workspace.
* Cada solicitação em lote deve ter [`max_tokens`](https://platform.claude.com/docs/pt-BR/api/messages/create#create.max_tokens) de pelo menos `1`. `max_tokens: 0` ([pré-aquecimento do cache](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#pre-warming-the-cache)) não é suportado dentro de um lote, porque uma entrada de cache efêmera gravada durante o processamento do lote provavelmente expiraria antes da execução da solicitação subsequente.
### Modelos suportados
Todos os [modelos ativos](https://platform.claude.com/docs/pt-BR/models/overview) suportam a Message Batches API.
### O que pode ser processado em lote
Quase qualquer solicitação que você pode fazer à Messages API pode ser incluída em um lote. Isso inclui:
* Visão
* Uso de ferramentas, incluindo todas as [ferramentas de servidor](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/server-tools) (pesquisa na web, web fetch, execução de código, conectores MCP, advisor e pesquisa de ferramentas)
* Mensagens do sistema
* Conversas com múltiplos turnos
* Pensamento estendido
* A maioria dos recursos beta
Como cada solicitação no lote é processada de forma independente, você pode misturar diferentes tipos de solicitações em um único lote.
Um pequeno número de parâmetros da Messages API **não** é suportado em solicitações em lote. Incluir qualquer um deles retorna um erro de validação:
| Parâmetro | Motivo |
| ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `stream: true` | Os resultados do lote retornam como um único arquivo, não como um stream. |
| `speed` ([Modo rápido](https://platform.claude.com/docs/pt-BR/build-with-claude/fast-mode)) | O modo rápido ajusta a latência síncrona, o que não se aplica ao processamento assíncrono em lote. |
| `fallbacks` ([Fallback no lado do servidor](https://platform.claude.com/docs/pt-BR/build-with-claude/refusals-and-fallback#server-side-fallback)) | O fallback no lado do servidor não se aplica a lotes. Para tentar novamente solicitações recusadas, consulte [Recusas em Message Batches](https://platform.claude.com/docs/pt-BR/build-with-claude/refusals-and-fallback#refusals-in-message-batches). |
| `max_tokens: 0` | Consulte [Limitações de lotes](https://platform.claude.com/docs/pt-BR/build-with-claude/batch-processing#batch-limitations). |
Como os lotes podem levar mais de 5 minutos para serem processados, considere usar a [duração de cache de 1 hora](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#1-hour-cache-duration) com o “prompt caching” (cache de prompt) para obter melhores taxas de acerto de cache ao processar lotes com contexto compartilhado.
## Preços
A Batches API oferece economias de custo significativas. Todo o uso é cobrado a 50 por cento dos preços padrão da API.
| Model | Batch input | Batch output |
| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------- | :------------ |
| Claude Fable 5.2 | $4 / MTok | $20 / MTok |
| Claude Mythos 5.2 ([limited availability](https://support.claude.com/en/articles/14604842)) | $4 / MTok | $20 / MTok |
| Claude Fable 5.1 | $5 / MTok | $25 / MTok |
| Claude Mythos 5.1 ([limited availability](https://support.claude.com/en/articles/14604842)) | $5 / MTok | $25 / MTok |
| Claude Fable 5 | $5 / MTok | $25 / MTok |
| Claude Mythos 5 ([limited availability](https://support.claude.com/en/articles/14604842)) | $5 / MTok | $25 / MTok |
| Claude Opus 5.5 | $2 / MTok | $10 / 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 Claude Models on Google Cloud (Google managed) and Bedrock](https://platform.claude.com/docs/pt-BR/about-claude/model-deprecations)) | $7.50 / MTok | $37.50 / MTok |
| Claude Opus 4 ([retired, except on Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/pt-BR/about-claude/model-deprecations)) | $7.50 / MTok | $37.50 / MTok |
| Claude Sonnet 5.5 | $1 / MTok | $5 / 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 Claude Models on Google Cloud (Google managed) and Bedrock](https://platform.claude.com/docs/pt-BR/about-claude/model-deprecations)) | $1.50 / MTok | $7.50 / MTok |
| Claude Haiku 5.5 (for prompts up to 100,000 tokens) | $0.05 / MTok | $0.25 / MTok |
| Claude Haiku 5.5 (for prompts over 100,000 tokens) | $0.25 / MTok | $1.25 / MTok |
| Claude Haiku 4.5 | $0.50 / MTok | $2.50 / MTok |
* **MTok:** Million tokens. $5 / MTok is $5 for every million tokens.
* **Limited access:** Available only to organizations verified through Anthropic’s verification programs, such as the [Cyber Verification Program](https://support.claude.com/en/articles/14604842). To request access, apply to the program that covers your use case.
* **Retired:** May still be available on other cloud platforms. See [Model deprecations](https://platform.claude.com/docs/pt-BR/about-claude/model-deprecations) for more.
## Como usar a Message Batches API
### Prepare e crie seu lote
Um lote de mensagens é composto por uma lista de solicitações para criar uma Message. A estrutura de uma solicitação individual inclui:
* Um [`custom_id`](https://platform.claude.com/docs/pt-BR/api/messages/batches/create#create.requests.custom_id) exclusivo para identificar a solicitação de Messages. Deve ter de 1 a 64 caracteres e conter apenas caracteres alfanuméricos, hifens e sublinhados (correspondendo a `^[a-zA-Z0-9_-]{1,64}$`).
* Um objeto [`params`](https://platform.claude.com/docs/pt-BR/api/messages/batches/create#create.requests.params) com os parâmetros padrão da [Messages API](https://platform.claude.com/docs/pt-BR/api/messages/create)
Você pode [criar um lote](https://platform.claude.com/docs/pt-BR/api/messages/batches/create) passando essa lista para o parâmetro `requests`:
```bash cURL
curl https://api.anthropic.com/v1/messages/batches \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-H "content-type: application/json" \
-d '{
"requests": [
{
"custom_id": "my-first-request",
"params": {
"model": "claude-opus-5-5",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Hello, world"}
]
}
},
{
"custom_id": "my-second-request",
"params": {
"model": "claude-opus-5-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-5
max_tokens: 1024
messages:
- role: user
content: Hello, world
- custom_id: my-second-request
params:
model: claude-opus-5-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-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": "Hello, world",
}
],
),
),
Request(
custom_id="my-second-request",
params=MessageCreateParamsNonStreaming(
model="claude-opus-5-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-5",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello, world" }]
}
},
{
custom_id: "my-second-request",
params: {
model: "claude-opus-5-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_5,
MaxTokens = 1024,
Messages = [new UserMessageParam { Content = "Hello, world" }]
}
},
new()
{
CustomID = "my-second-request",
Params = new()
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
Messages = [new UserMessageParam { 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_5,
MaxTokens: 1024,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(
anthropic.NewTextBlock("Hello, world"),
),
},
},
},
{
CustomID: "my-second-request",
Params: anthropic.MessageBatchNewParamsRequestParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(
anthropic.NewTextBlock("Hi again, friend"),
),
},
},
},
},
})
fmt.Println(batch.ID)
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
BatchCreateParams params = BatchCreateParams.builder()
.addRequest(
BatchCreateParams.Request.builder()
.customId("my-first-request")
.params(
BatchCreateParams.Request.Params.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.addUserMessage("Hello, world")
.build()
)
.build()
)
.addRequest(
BatchCreateParams.Request.builder()
.customId("my-second-request")
.params(
BatchCreateParams.Request.Params.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.addUserMessage("Hi again, friend")
.build()
)
.build()
)
.build();
MessageBatch messageBatch = client.messages().batches().create(params);
System.out.println(messageBatch);
```
```php PHP
$client = new Client();
$batch = $client->messages->batches->create(
requests: [
[
'custom_id' => 'my-first-request',
'params' => [
'model' => 'claude-opus-5-5',
'max_tokens' => 1024,
'messages' => [
['role' => 'user', 'content' => 'Hello, world']
]
]
],
[
'custom_id' => 'my-second-request',
'params' => [
'model' => 'claude-opus-5-5',
'max_tokens' => 1024,
'messages' => [
['role' => 'user', 'content' => 'Hi again, friend']
]
]
]
],
);
echo $batch->id;
```
```ruby Ruby
client = Anthropic::Client.new
batch = client.messages.batches.create(
requests: [
{
custom_id: "my-first-request",
params: {
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 1024,
messages: [
{ role: "user", content: "Hello, world" }
]
}
},
{
custom_id: "my-second-request",
params: {
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 1024,
messages: [
{ role: "user", content: "Hi again, friend" }
]
}
}
]
)
puts batch
```
Neste exemplo, duas solicitações separadas são agrupadas em lote para processamento assíncrono. Cada solicitação tem um `custom_id` exclusivo e contém os parâmetros padrão que você usaria em uma chamada da Messages API.
**Teste suas solicitações em lote com a Messages API**
A API valida o objeto `params` de cada solicitação de mensagem de forma assíncrona e retorna os erros de validação quando o processamento de todo o lote termina. Para verificar se você está construindo sua entrada corretamente, verifique primeiro a estrutura da sua solicitação com a [Messages API](https://platform.claude.com/docs/pt-BR/api/messages/create).
Quando um lote é criado pela primeira vez, a resposta tem um status de processamento `in_progress`.
```json Output
{
"id": "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
"type": "message_batch",
"processing_status": "in_progress",
"request_counts": {
"processing": 2,
"succeeded": 0,
"errored": 0,
"canceled": 0,
"expired": 0
},
"ended_at": null,
"created_at": "2024-09-24T18:37:24.100435Z",
"expires_at": "2024-09-25T18:37:24.100435Z",
"cancel_initiated_at": null,
"results_url": null
}
```
### Acompanhando seu lote
O campo [`processing_status`](https://platform.claude.com/docs/pt-BR/api/messages/batches/retrieve#message_batch.processing_status) do lote de mensagens indica o estágio de processamento em que o lote se encontra. Ele começa como `in_progress` e, em seguida, é atualizado para `ended` quando todas as solicitações no lote terminam de ser processadas e os resultados estão prontos. Você pode monitorar o estado do seu lote visitando o [Console](https://platform.claude.com/settings/workspaces/default/batches) ou usando o endpoint de recuperação.
(See the `messages/batches/retrieve` method in [the API reference](https://platform.claude.com/docs/pt-BR/api/messages/batches/retrieve).)
#### “Polling” (consulta periódica) da conclusão do lote de mensagens
Para consultar um lote de mensagens, você precisará do seu `id`, que é fornecido na resposta ao criar um lote ou ao listar lotes. Você pode implementar um loop de polling que verifica o status do lote periodicamente até que o processamento termine:
```bash cURL
# Verifique o status; repita até que processing_status seja "ended"
curl "https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21"
```
```bash CLI
# Verifique o status; repita até que processing_status seja "ended"
ant messages:batches retrieve --message-batch-id "$MESSAGE_BATCH_ID"
```
```python Python
import time
client = anthropic.Anthropic()
MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"
message_batch = None
while True:
message_batch = client.messages.batches.retrieve(MESSAGE_BATCH_ID)
if message_batch.processing_status == "ended":
break
print(f"Batch {MESSAGE_BATCH_ID} is still processing...")
time.sleep(60)
print(message_batch)
```
```typescript TypeScript
const client = new Anthropic();
const messageBatchId = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d";
let messageBatch;
while (true) {
messageBatch = await client.messages.batches.retrieve(messageBatchId);
if (messageBatch.processing_status === "ended") {
break;
}
console.log(`Batch ${messageBatchId} is still processing... waiting`);
await new Promise((resolve) => setTimeout(resolve, 60_000));
}
console.log(messageBatch);
```
```csharp C#
AnthropicClient client = new();
string messageBatchId = Environment.GetEnvironmentVariable("MESSAGE_BATCH_ID");
MessageBatch messageBatch = null;
while (true)
{
messageBatch = await client.Messages.Batches.Retrieve(messageBatchId);
if (messageBatch.ProcessingStatus == "ended")
{
break;
}
Console.WriteLine($"Batch {messageBatchId} is still processing...");
await Task.Delay(60000);
}
Console.WriteLine(messageBatch);
```
```go Go
client := anthropic.NewClient()
messageBatchID := os.Getenv("MESSAGE_BATCH_ID")
var messageBatch *anthropic.MessageBatch
for {
var err error
messageBatch, err = client.Messages.Batches.Get(context.TODO(), messageBatchID, anthropic.MessageBatchGetParams{})
if err != nil {
log.Fatal(err)
}
if messageBatch.ProcessingStatus == "ended" {
break
}
fmt.Printf("Batch %s is still processing...\n", messageBatchID)
time.Sleep(60 * time.Second)
}
fmt.Println(messageBatch)
```
```java Java
import com.anthropic.models.messages.batches.MessageBatch;
// ...
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
String messageBatchId = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d";
MessageBatch messageBatch = null;
while (true) {
messageBatch = client.messages().batches().retrieve(messageBatchId);
if (messageBatch.processingStatus().equals(MessageBatch.ProcessingStatus.ENDED)) {
break;
}
System.out.println("Batch " + messageBatchId + " is still processing...");
Thread.sleep(60000);
}
System.out.println(messageBatch);
```
```php PHP
$client = new Client();
$messageBatchId = getenv('MESSAGE_BATCH_ID');
$messageBatch = null;
while (true) {
$messageBatch = $client->messages->batches->retrieve(
messageBatchID: $messageBatchId,
);
if ($messageBatch->processingStatus === 'ended') {
break;
}
echo "Batch {$messageBatchId} is still processing...\n";
sleep(60);
}
echo json_encode($messageBatch, JSON_PRETTY_PRINT);
```
```ruby Ruby
client = Anthropic::Client.new
message_batch_id = ENV["MESSAGE_BATCH_ID"]
message_batch = nil
loop do
message_batch = client.messages.batches.retrieve(message_batch_id)
break if message_batch.processing_status == :ended
puts "Batch #{message_batch_id} is still processing..."
sleep 60
end
puts message_batch
```
### Listando todos os lotes de mensagens
Você pode listar todos os lotes de mensagens no seu Workspace usando o [endpoint de listagem](https://platform.claude.com/docs/pt-BR/api/messages/batches/list). Os resultados são paginados. O SDK busca páginas adicionais conforme necessário:
```bash cURL
# Busca uma página. Enquanto o has_more da resposta for true, passe seu
# last_id como after_id para buscar a próxima página. (Os SDKs e a CLI
# fazem a paginação automaticamente.)
curl -s "https://api.anthropic.com/v1/messages/batches?limit=20" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21"
```
```bash CLI
# Busca automaticamente mais páginas conforme necessário
ant messages:batches list --limit 20
```
```python Python
client = anthropic.Anthropic()
# Busca automaticamente mais páginas conforme necessário.
for message_batch in client.messages.batches.list(limit=20):
print(message_batch)
```
```typescript TypeScript
const client = new Anthropic();
// Busca automaticamente mais páginas conforme necessário.
for await (const messageBatch of client.messages.batches.list({
limit: 20
})) {
console.log(messageBatch);
}
```
```csharp C#
AnthropicClient client = new();
var parameters = new BatchListParams
{
Limit = 20
};
// Busca automaticamente mais páginas conforme necessário
var page = await client.Messages.Batches.List(parameters);
await foreach (var messageBatch in page.Paginate())
{
Console.WriteLine(messageBatch);
}
```
```go Go
client := anthropic.NewClient()
// Busca automaticamente mais páginas conforme necessário
iter := client.Messages.Batches.ListAutoPaging(context.TODO(), anthropic.MessageBatchListParams{
Limit: anthropic.Int(20),
})
for iter.Next() {
messageBatch := iter.Current()
fmt.Println(messageBatch)
}
if err := iter.Err(); err != nil {
log.Fatal(err)
}
```
```java Java
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Busca automaticamente mais páginas conforme necessário
for (MessageBatch messageBatch : client
.messages()
.batches()
.list(BatchListParams.builder()
.limit(20)
.build())
.autoPager()) {
System.out.println(messageBatch);
}
```
```php PHP
$client = new Client();
// Busca automaticamente mais páginas conforme necessário
foreach ($client->messages->batches->list(limit: 20)->pagingEachItem() as $messageBatch) {
echo $messageBatch->id . "\n";
}
```
```ruby Ruby
client = Anthropic::Client.new
# Busca automaticamente mais páginas conforme necessário
client.messages.batches.list(limit: 20).auto_paging_each do |message_batch|
puts message_batch
end
```
### Recuperando os resultados do lote
Quando o processamento do lote termina, cada solicitação de Messages no lote tem um resultado. Existem quatro tipos de resultado:
| Tipo de resultado | Descrição |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `succeeded` | A solicitação foi bem-sucedida. Inclui o resultado da mensagem. |
| `errored` | A solicitação encontrou um erro e uma mensagem não foi criada. Os erros possíveis incluem solicitações inválidas e erros internos do servidor. Você não é cobrado por essas solicitações. |
| `canceled` | O usuário cancelou o lote antes que esta solicitação pudesse ser enviada ao modelo. Você não é cobrado por essas solicitações. |
| `expired` | O lote atingiu sua expiração de 24 horas antes que esta solicitação pudesse ser enviada ao modelo. Você não é cobrado por essas solicitações. |
O objeto `request_counts` do lote contabiliza as solicitações ainda em processamento e as solicitações de cada tipo de resultado.
(See `message_batch.request_counts` on `messages/batches/retrieve` in [the API reference](https://platform.claude.com/docs/pt-BR/api/messages/batches/retrieve#message_batch.request_counts).)
Os resultados do lote ficam disponíveis para download na propriedade [`results_url`](https://platform.claude.com/docs/pt-BR/api/messages/batches/retrieve#message_batch.results_url) do lote de mensagens e, se as permissões da sua organização permitirem, no Console. Como os resultados podem ser grandes, [faça streaming dos resultados](https://platform.claude.com/docs/pt-BR/api/messages/batches/results) em vez de baixá-los todos de uma vez.
```bash cURL
# Faz o streaming dos resultados .jsonl do lote, um resultado por linha.
# Para tratamento por resultado (novas tentativas, erros de validação), use o Anthropic SDK.
curl "https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d/results" \
-H "anthropic-version: 2026-10-21" \
-H "x-api-key: $ANTHROPIC_API_KEY"
```
```bash CLI
# Imprime um resultado por linha, por exemplo `{"custom_id":"test-1","result":{"type":"succeeded",…}}`.
# Para tratamento por resultado (novas tentativas, erros de validação), use os exemplos
# do Anthropic SDK nas outras abas.
ant messages:batches results \
--message-batch-id msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d \
--format jsonl
```
```python Python
client = anthropic.Anthropic()
# Faz streaming do arquivo de resultados em blocos eficientes em memória, processando um por vez
for result in client.messages.batches.results(
"msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
):
outcome = result.result
match outcome.type:
case "succeeded":
print(f"Success! {result.custom_id}")
case "errored":
if outcome.error.error.type == "invalid_request_error":
# O corpo da requisição deve ser corrigido antes de reenviar a requisição
print(f"Validation error {result.custom_id}")
else:
# A requisição pode ser repetida diretamente
print(f"Server error {result.custom_id}")
case "expired":
print(f"Request expired {result.custom_id}")
```
```typescript TypeScript
const client = new Anthropic();
// Faz streaming do arquivo de resultados em partes eficientes em memória, processando uma de cada vez
for await (const result of await client.messages.batches.results(
"msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"
)) {
switch (result.result.type) {
case "succeeded":
console.log(`Success! ${result.custom_id}`);
break;
case "errored":
if (result.result.error.error.type === "invalid_request_error") {
// O corpo da requisição deve ser corrigido antes de reenviar a requisição
console.log(`Validation error: ${result.custom_id}`);
} else {
// A requisição pode ser repetida diretamente
console.log(`Server error: ${result.custom_id}`);
}
break;
case "expired":
console.log(`Request expired: ${result.custom_id}`);
break;
}
}
```
```csharp C#
AnthropicClient client = new();
await foreach (var result in client.Messages.Batches.ResultsStreaming("msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"))
{
switch (result.Result.Type.Raw())
{
case "succeeded":
Console.WriteLine($"Success! {result.CustomID}");
break;
case "errored":
if (result.Result.TryPickErrored(out var errored)
&& errored.Error.Error.Type.Raw() == "invalid_request_error")
{
Console.WriteLine($"Validation error: {result.CustomID}");
}
else
{
Console.WriteLine($"Server error: {result.CustomID}");
}
break;
case "expired":
Console.WriteLine($"Request expired: {result.CustomID}");
break;
}
}
```
```go Go
client := anthropic.NewClient()
stream := client.Messages.Batches.ResultsStreaming(context.TODO(), "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d", anthropic.MessageBatchResultsParams{})
for stream.Next() {
result := stream.Current()
switch variant := result.Result.AsAny().(type) {
case anthropic.MessageBatchSucceededResult:
fmt.Printf("Success! %s\n", result.CustomID)
case anthropic.MessageBatchErroredResult:
fmt.Printf("Error: %s - %s\n", result.CustomID, variant.Error.Error.Message)
case anthropic.MessageBatchExpiredResult:
fmt.Printf("Request expired: %s\n", result.CustomID)
}
}
if err := stream.Err(); err != nil {
log.Fatal(err)
}
```
```java Java
import com.anthropic.core.http.StreamResponse;
import com.anthropic.models.messages.batches.BatchResultsParams;
import com.anthropic.models.messages.batches.MessageBatchIndividualResponse;
// ...
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
// Faz streaming do arquivo de resultados em blocos eficientes em memória, processando um por vez
try (
StreamResponse streamResponse = client
.messages()
.batches()
.resultsStreaming(
BatchResultsParams.builder()
.messageBatchId("msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d")
.build()
)
) {
streamResponse
.stream()
.forEach(result -> {
switch (result.result().type().value()) {
case SUCCEEDED -> System.out.println("Success! " + result.customId());
case ERRORED -> {
if (result.result().asErrored().error().error().isInvalidRequestError()) {
// O corpo da requisição deve ser corrigido antes de reenviar a requisição
System.out.println("Validation error: " + result.customId());
} else {
// A requisição pode ser repetida diretamente
System.out.println("Server error: " + result.customId());
}
}
case EXPIRED -> System.out.println("Request expired: " + result.customId());
}
});
}
```
```php PHP
use Anthropic\Messages\Batches\MessageBatchErroredResult;
use Anthropic\Messages\Batches\MessageBatchExpiredResult;
use Anthropic\Messages\Batches\MessageBatchSucceededResult;
$client = new Client();
foreach ($client->messages->batches->resultsStream(messageBatchID: 'msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d') as $result) {
switch (true) {
case $result->result instanceof MessageBatchSucceededResult:
echo "Success! {$result->customID}\n";
break;
case $result->result instanceof MessageBatchErroredResult:
if ($result->result->error->error->type === 'invalid_request_error') {
echo "Validation error: {$result->customID}\n";
} else {
echo "Server error: {$result->customID}\n";
}
break;
case $result->result instanceof MessageBatchExpiredResult:
echo "Request expired: {$result->customID}\n";
break;
}
}
```
```ruby Ruby
client = Anthropic::Client.new
client.messages.batches.results_streaming("msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d").each do |result|
outcome = result.result
case outcome
when Anthropic::Models::Messages::MessageBatchSucceededResult
puts "Success! #{result.custom_id}"
when Anthropic::Models::Messages::MessageBatchErroredResult
if outcome.error.error.type == :invalid_request_error
puts "Validation error: #{result.custom_id}"
else
puts "Server error: #{result.custom_id}"
end
when Anthropic::Models::Messages::MessageBatchExpiredResult
puts "Request expired: #{result.custom_id}"
end
end
```
Os resultados estão no formato `.jsonl`, em que cada linha é um objeto JSON válido que representa o resultado de uma única solicitação no lote de mensagens. Para cada resultado transmitido via streaming, você pode fazer algo diferente dependendo do seu `custom_id` e do tipo de resultado. Aqui está um exemplo de conjunto de resultados:
```jsonl .jsonl file
{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-opus-5-5","content":[{"type":"text","text":"Hello again! It's nice to see you. How can I assist you today? Is there anything specific you'd like to chat about or any questions you have?"}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":11,"output_tokens":36}}}}
{"custom_id":"my-first-request","result":{"type":"succeeded","message":{"id":"msg_01FqfsLoHwgeFbguDgpz48m7","type":"message","role":"assistant","model":"claude-opus-5-5","content":[{"type":"text","text":"Hello! How can I assist you today? Feel free to ask me any questions or let me know if there's anything you'd like to chat about."}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":10,"output_tokens":34}}}}
```
Se o seu resultado tiver um erro, seu `result.error` será definido com a [estrutura de erro](https://platform.claude.com/docs/pt-BR/api/errors#error-shapes) padrão.
Os resultados do lote usam a versão da API da requisição que criou o lote.
**Os resultados do lote podem não corresponder à ordem de entrada**
Os resultados do lote podem ser retornados em qualquer ordem e podem não corresponder à ordem das solicitações quando o lote foi criado. No exemplo anterior, o resultado da segunda solicitação do lote é retornado antes do primeiro. Para associar corretamente os resultados às solicitações correspondentes, sempre use o campo `custom_id`.
### Cancelando um lote de mensagens
Você pode cancelar um lote de mensagens que está em processamento usando o [endpoint de cancelamento](https://platform.claude.com/docs/pt-BR/api/messages/batches/cancel). Imediatamente após o cancelamento, o `processing_status` do lote é `canceling`. Você pode usar a mesma técnica de polling descrita anteriormente para aguardar até que o cancelamento seja finalizado. Lotes cancelados terminam com o status `ended` e podem conter resultados parciais para solicitações que foram processadas antes do cancelamento.
```bash cURL
curl -X POST https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/cancel \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21"
```
```bash CLI
ant messages:batches cancel --message-batch-id "$MESSAGE_BATCH_ID"
```
```python Python
client = anthropic.Anthropic()
MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"
message_batch = client.messages.batches.cancel(
MESSAGE_BATCH_ID,
)
print(message_batch)
```
```typescript TypeScript
const client = new Anthropic();
const messageBatch = await client.messages.batches.cancel(MESSAGE_BATCH_ID);
console.log(messageBatch);
```
```csharp C#
AnthropicClient client = new();
string messageBatchId = Environment.GetEnvironmentVariable("MESSAGE_BATCH_ID");
var messageBatch = await client.Messages.Batches.Cancel(messageBatchId);
Console.WriteLine(messageBatch);
```
```go Go
client := anthropic.NewClient()
messageBatchID := os.Getenv("MESSAGE_BATCH_ID")
messageBatch, err := client.Messages.Batches.Cancel(context.TODO(), messageBatchID, anthropic.MessageBatchCancelParams{})
if err != nil {
log.Fatal(err)
}
fmt.Println(messageBatch)
```
```java Java
import com.anthropic.models.messages.batches.*;
// ...
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageBatch messageBatch = client
.messages()
.batches()
.cancel("msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d");
System.out.println(messageBatch);
```
```php PHP
$client = new Client();
$messageBatch = $client->messages->batches->cancel(
messageBatchID: 'msgbatch_example_id',
);
echo $messageBatch;
```
```ruby Ruby
client = Anthropic::Client.new
message_batch_id = ENV.fetch("MESSAGE_BATCH_ID")
message_batch = client.messages.batches.cancel(message_batch_id)
puts message_batch
```
A resposta mostra o lote em um estado `canceling`:
```json Output
{
"id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
"type": "message_batch",
"processing_status": "canceling",
"request_counts": {
"processing": 2,
"succeeded": 0,
"errored": 0,
"canceled": 0,
"expired": 0
},
"ended_at": null,
"created_at": "2024-09-24T18:37:24.100435Z",
"expires_at": "2024-09-25T18:37:24.100435Z",
"cancel_initiated_at": "2024-09-24T18:39:03.114875Z",
"results_url": null
}
```
### Usando cache de prompt com Message Batches
A Message Batches API suporta cache de prompt, permitindo que você potencialmente reduza custos e tempo de processamento para solicitações em lote. Os descontos de preço do cache de prompt e dos Message Batches podem ser acumulados, proporcionando economias de custo ainda maiores quando ambos os recursos são usados juntos. No entanto, como as solicitações em lote são processadas de forma assíncrona e simultânea, os acertos de cache são fornecidos com base no melhor esforço. Os usuários normalmente observam taxas de acerto de cache que variam de 30 por cento a 98 por cento, dependendo de seus padrões de tráfego.
Para maximizar a probabilidade de acertos de cache em suas solicitações em lote:
1. Inclua blocos `cache_control` idênticos em cada solicitação de Message dentro do seu lote.
2. Mantenha um fluxo constante de solicitações para evitar que as entradas de cache expirem após seu tempo de vida de 5 minutos.
3. Estruture suas solicitações para compartilhar o máximo possível de conteúdo em cache.
Exemplo de implementação de cache de prompt em um lote:
```bash cURL
curl https://api.anthropic.com/v1/messages/batches \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-H "content-type: application/json" \
-d '{
"requests": [
{
"custom_id": "my-first-request",
"params": {
"model": "claude-opus-5-5",
"max_tokens": 1024,
"system": [
{
"type": "text",
"text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
},
{
"type": "text",
"text": "",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [
{"role": "user", "content": "Analyze the major themes in Pride and Prejudice."}
]
}
},
{
"custom_id": "my-second-request",
"params": {
"model": "claude-opus-5-5",
"max_tokens": 1024,
"system": [
{
"type": "text",
"text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
},
{
"type": "text",
"text": "",
"cache_control": {"type": "ephemeral"}
}
],
"messages": [
{"role": "user", "content": "Write a summary of Pride and Prejudice."}
]
}
}
]
}'
```
```bash CLI
ant messages:batches create <<'YAML'
requests:
- custom_id: my-first-request
params:
model: claude-opus-5-5
max_tokens: 1024
system:
- type: text
text: >
You are an AI assistant tasked with analyzing literary works. Your
goal is to provide insightful commentary on themes, characters, and
writing style.
- type: text
text: ""
cache_control:
type: ephemeral
messages:
- role: user
content: Analyze the major themes in Pride and Prejudice.
- custom_id: my-second-request
params:
model: claude-opus-5-5
max_tokens: 1024
system:
- type: text
text: >
You are an AI assistant tasked with analyzing literary works. Your
goal is to provide insightful commentary on themes, characters, and
writing style.
- type: text
text: ""
cache_control:
type: ephemeral
messages:
- role: user
content: Write a summary of Pride and Prejudice.
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-5",
max_tokens=1024,
system=[
{
"type": "text",
"text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n",
},
{
"type": "text",
"text": "",
"cache_control": {"type": "ephemeral"},
},
],
messages=[
{
"role": "user",
"content": "Analyze the major themes in Pride and Prejudice.",
}
],
),
),
Request(
custom_id="my-second-request",
params=MessageCreateParamsNonStreaming(
model="claude-opus-5-5",
max_tokens=1024,
system=[
{
"type": "text",
"text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n",
},
{
"type": "text",
"text": "",
"cache_control": {"type": "ephemeral"},
},
],
messages=[
{
"role": "user",
"content": "Write a summary of Pride and Prejudice.",
}
],
),
),
]
)
```
```typescript TypeScript
const client = new Anthropic();
const messageBatch = await client.messages.batches.create({
requests: [
{
custom_id: "my-first-request",
params: {
model: "claude-opus-5-5",
max_tokens: 1024,
system: [
{
type: "text",
text: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
},
{
type: "text",
text: "",
cache_control: { type: "ephemeral" }
}
],
messages: [
{ role: "user", content: "Analyze the major themes in Pride and Prejudice." }
]
}
},
{
custom_id: "my-second-request",
params: {
model: "claude-opus-5-5",
max_tokens: 1024,
system: [
{
type: "text",
text: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
},
{
type: "text",
text: "",
cache_control: { type: "ephemeral" }
}
],
messages: [{ role: "user", content: "Write a summary of Pride and Prejudice." }]
}
}
]
});
```
```csharp C#
using Anthropic;
using Anthropic.Models.Messages;
using Anthropic.Models.Messages.Batches;
AnthropicClient client = new()
{
ApiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY")
};
var messageBatch = await client.Messages.Batches.Create(new BatchCreateParams
{
Requests =
[
new()
{
CustomID = "my-first-request",
Params = new()
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
System = new List
{
new()
{
Text = "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
},
new()
{
Text = "",
CacheControl = new()
}
},
Messages =
[
new UserMessageParam { Content = "Analyze the major themes in Pride and Prejudice." }
]
}
},
new()
{
CustomID = "my-second-request",
Params = new()
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 1024,
System = new List
{
new()
{
Text = "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
},
new()
{
Text = "",
CacheControl = new()
}
},
Messages =
[
new UserMessageParam { Content = "Write a summary of Pride and Prejudice." }
]
}
}
]
});
```
```go Go
client := anthropic.NewClient()
messageBatch, err := client.Messages.Batches.New(context.TODO(), anthropic.MessageBatchNewParams{
Requests: []anthropic.MessageBatchNewParamsRequest{
{
CustomID: "my-first-request",
Params: anthropic.MessageBatchNewParamsRequestParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
System: []anthropic.TextBlockParam{
{
Text: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n",
},
{
Text: "",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Analyze the major themes in Pride and Prejudice.")),
},
},
},
{
CustomID: "my-second-request",
Params: anthropic.MessageBatchNewParamsRequestParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 1024,
System: []anthropic.TextBlockParam{
{
Text: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n",
},
{
Text: "",
CacheControl: anthropic.NewCacheControlEphemeralParam(),
},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Write a summary of Pride and Prejudice.")),
},
},
},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(messageBatch)
```
```java Java
import com.anthropic.models.messages.CacheControlEphemeral;
// ...
import com.anthropic.models.messages.batches.*;
// ...
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
BatchCreateParams createParams = BatchCreateParams.builder()
.addRequest(
BatchCreateParams.Request.builder()
.customId("my-first-request")
.params(
BatchCreateParams.Request.Params.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.systemOfTextBlockParams(
List.of(
TextBlockParam.builder()
.text(
"You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
)
.build(),
TextBlockParam.builder()
.text("")
.cacheControl(CacheControlEphemeral.builder().build())
.build()
)
)
.addUserMessage("Analyze the major themes in Pride and Prejudice.")
.build()
)
.build()
)
.addRequest(
BatchCreateParams.Request.builder()
.customId("my-second-request")
.params(
BatchCreateParams.Request.Params.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(1024)
.systemOfTextBlockParams(
List.of(
TextBlockParam.builder()
.text(
"You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
)
.build(),
TextBlockParam.builder()
.text("")
.cacheControl(CacheControlEphemeral.builder().build())
.build()
)
)
.addUserMessage("Write a summary of Pride and Prejudice.")
.build()
)
.build()
)
.build();
MessageBatch messageBatch = client.messages().batches().create(createParams);
```
```php PHP
$client = new Client();
$messageBatch = $client->messages->batches->create(
requests: [
[
'custom_id' => 'my-first-request',
'params' => [
'model' => 'claude-opus-5-5',
'max_tokens' => 1024,
'system' => [
[
'type' => 'text',
'text' => 'You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n'
],
[
'type' => 'text',
'text' => '',
'cache_control' => ['type' => 'ephemeral']
]
],
'messages' => [
['role' => 'user', 'content' => 'Analyze the major themes in Pride and Prejudice.']
]
]
],
[
'custom_id' => 'my-second-request',
'params' => [
'model' => 'claude-opus-5-5',
'max_tokens' => 1024,
'system' => [
[
'type' => 'text',
'text' => 'You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n'
],
[
'type' => 'text',
'text' => '',
'cache_control' => ['type' => 'ephemeral']
]
],
'messages' => [
['role' => 'user', 'content' => 'Write a summary of Pride and Prejudice.']
]
]
]
],
);
```
```ruby Ruby
client = Anthropic::Client.new
message_batch = client.messages.batches.create(
requests: [
{
custom_id: "my-first-request",
params: {
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 1024,
system: [
{
type: "text",
text: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
},
{
type: "text",
text: "",
cache_control: { type: "ephemeral" }
}
],
messages: [
{ role: "user", content: "Analyze the major themes in Pride and Prejudice." }
]
}
},
{
custom_id: "my-second-request",
params: {
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 1024,
system: [
{
type: "text",
text: "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n"
},
{
type: "text",
text: "",
cache_control: { type: "ephemeral" }
}
],
messages: [
{ role: "user", content: "Write a summary of Pride and Prejudice." }
]
}
}
]
)
```
Neste exemplo, ambas as solicitações no lote incluem mensagens do sistema idênticas e o texto completo de Orgulho e Preconceito marcado com `cache_control` para aumentar a probabilidade de acertos de cache.
### Ferramentas de servidor e o loop agêntico
Todas as [ferramentas de servidor](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/server-tools) (pesquisa na web, web fetch, execução de código, conectores MCP, advisor e pesquisa de ferramentas) funcionam em solicitações em lote. O worker de lote executa o mesmo “agentic loop” (loop agêntico) no lado do servidor que a Messages API síncrona.
Como não há uma conexão aberta a ser mantida, o loop de lote pode executar **mais iterações em um turno** do que uma solicitação síncrona antes de retornar `stop_reason: "pause_turn"`. Se um resultado de lote retornar com `pause_turn`, o turno não foi concluído; você pode continuá-lo enviando o conteúdo pausado do assistente em uma solicitação subsequente (em lote ou síncrona), exatamente como mostrado no [padrão de continuação pause\_turn](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/server-tools#the-server-side-loop-and-pause-turn).
O worker de lote também limita o `web_search` para cada organização, de modo que o processamento em lote altamente simultâneo não esgote o limite de taxa de pesquisa na web da sua organização. O lote tenta novamente as solicitações limitadas automaticamente; você não precisa lidar com isso por conta própria, mas lotes muito grandes de pesquisa na web podem levar mais tempo para serem concluídos.
### Saída estendida (beta)
O cabeçalho beta `output-300k-2026-03-24` eleva o limite de `max_tokens` para 300.000 em solicitações em lote que usam Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5.5, Claude Sonnet 5, Claude Sonnet 4.6 ou Claude Haiku 5.5. Inclua o cabeçalho para gerar saídas muito mais longas do que o limite padrão de 128k de `max_tokens` em um único turno.
A saída estendida está disponível apenas na Message Batches API, não na Messages API síncrona. Ela está disponível na Claude API e na Claude Platform on AWS.
Use a saída estendida para geração de textos longos, como rascunhos do tamanho de livros e documentação técnica, extração exaustiva de dados estruturados, grandes estruturas de geração de código e longas cadeias de raciocínio.
Uma única geração de 300k tokens pode levar mais de uma hora para ser concluída, portanto planeje seus envios de lote levando em conta a janela de processamento de 24 horas. O preço padrão de lote (50 por cento dos preços padrão da API) se aplica.
```bash cURL
curl https://api.anthropic.com/v1/messages/batches \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2026-10-21" \
-H "anthropic-beta: output-300k-2026-03-24" \
-H "content-type: application/json" \
-d '{
"requests": [
{
"custom_id": "long-form-request",
"params": {
"model": "claude-opus-5-5",
"max_tokens": 300000,
"messages": [
{"role": "user", "content": "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices."}
]
}
}
]
}'
```
```bash CLI
ant beta:messages:batches create --beta output-300k-2026-03-24 <<'YAML'
requests:
- custom_id: long-form-request
params:
model: claude-opus-5-5
max_tokens: 300000
messages:
- role: user
content: >-
Write a comprehensive technical guide to building distributed
systems, covering architecture patterns, consistency models,
fault tolerance, and operational best practices.
YAML
```
```python Python
from anthropic.types.beta.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.beta.messages.batch_create_params import Request
client = anthropic.Anthropic()
message_batch = client.beta.messages.batches.create(
betas=["output-300k-2026-03-24"],
requests=[
Request(
custom_id="long-form-request",
params=MessageCreateParamsNonStreaming(
model="claude-opus-5-5",
max_tokens=300_000,
messages=[
{
"role": "user",
"content": "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices.",
}
],
),
),
],
)
print(message_batch)
```
```typescript TypeScript
const client = new Anthropic();
const messageBatch = await client.beta.messages.batches.create({
betas: ["output-300k-2026-03-24"],
requests: [
{
custom_id: "long-form-request",
params: {
model: "claude-opus-5-5",
max_tokens: 300000,
messages: [
{
role: "user",
content:
"Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices."
}
]
}
}
]
});
console.log(messageBatch);
```
```csharp C#
using Anthropic;
using Anthropic.Models.Beta.Messages;
using Anthropic.Models.Beta.Messages.Batches;
using Model = Anthropic.Models.Messages.Model;
AnthropicClient client = new();
var batch = await client.Beta.Messages.Batches.Create(new BatchCreateParams
{
Betas = ["output-300k-2026-03-24"],
Requests =
[
new()
{
CustomID = "long-form-request",
Params = new()
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 300_000,
Messages =
[
new BetaUserMessageParam { Content = "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices." }
]
}
}
]
});
Console.WriteLine(batch);
```
```go Go
client := anthropic.NewClient()
batch, err := client.Beta.Messages.Batches.New(context.Background(),
anthropic.BetaMessageBatchNewParams{
Betas: []anthropic.AnthropicBeta{"output-300k-2026-03-24"},
Requests: []anthropic.BetaMessageBatchNewParamsRequest{
{
CustomID: "long-form-request",
Params: anthropic.BetaMessageBatchNewParamsRequestParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 300_000,
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(
anthropic.NewBetaTextBlock("Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices."),
),
},
},
},
},
})
if err != nil {
panic(err)
}
fmt.Println(batch.ID)
```
```java Java
import com.anthropic.models.beta.messages.batches.*;
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
BatchCreateParams params = BatchCreateParams.builder()
.addBeta("output-300k-2026-03-24")
.addRequest(
BatchCreateParams.Request.builder()
.customId("long-form-request")
.params(
BatchCreateParams.Request.Params.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(300_000L)
.addUserMessage("Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices.")
.build()
)
.build()
)
.build();
BetaMessageBatch messageBatch = client.beta().messages().batches().create(params);
IO.println(messageBatch);
}
```
```php PHP
$client = new Client();
$batch = $client->beta->messages->batches->create(
betas: ['output-300k-2026-03-24'],
requests: [
[
'custom_id' => 'long-form-request',
'params' => [
'model' => 'claude-opus-5-5',
'max_tokens' => 300_000,
'messages' => [
['role' => 'user', 'content' => 'Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices.']
]
]
]
],
);
echo $batch->id;
```
```ruby Ruby
client = Anthropic::Client.new
batch = client.beta.messages.batches.create(
betas: ["output-300k-2026-03-24"],
requests: [
{
custom_id: "long-form-request",
params: {
model: Anthropic::Model::CLAUDE_OPUS_5_5,
max_tokens: 300_000,
messages: [
{ role: "user", content: "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices." }
]
}
}
]
)
puts batch
```
### Práticas recomendadas para um processamento em lote eficaz
Para usar a Batches API de forma eficaz:
* Monitore regularmente o status de processamento do lote e implemente uma lógica de novas tentativas apropriada para solicitações com falha.
* Use valores de `custom_id` significativos para associar facilmente os resultados às solicitações, pois a ordem não é garantida.
* Considere dividir conjuntos de dados muito grandes em vários lotes para melhor gerenciamento.
* Faça um teste de uma única estrutura de solicitação com a Messages API para evitar erros de validação.
### Solução de problemas comuns
Se você observar um comportamento inesperado:
* Verifique se o tamanho total da solicitação em lote não excede 256 MB. Se o tamanho da solicitação for muito grande, você poderá receber um erro 413 `request_too_large`.
* Verifique se você está usando [modelos suportados](https://platform.claude.com/docs/pt-BR/build-with-claude/batch-processing#supported-models) para todas as solicitações no lote.
* Certifique-se de que cada solicitação no lote tenha um `custom_id` exclusivo.
* Certifique-se de que se passaram menos de 29 dias desde o horário `created_at` do lote (não o `ended_at` do processamento). Após 29 dias, os resultados não estão mais disponíveis para download.
* Confirme que o lote não foi cancelado.
Observe que a falha de uma solicitação em um lote não afeta o processamento das outras solicitações.
## Armazenamento e privacidade de lotes
* **Isolamento de Workspace:** os lotes são isolados dentro do Workspace em que são criados. Eles só podem ser acessados por solicitações de API nesse mesmo Workspace ou por usuários com permissão para visualizar lotes do Workspace no Console.
* **Disponibilidade de resultados:** os resultados do lote ficam disponíveis por 29 dias após a criação do lote, oferecendo tempo suficiente para recuperação e processamento.
## Perguntas frequentes
Os lotes podem levar até 24 horas para serem processados, mas muitos são concluídos antes. O tempo real de processamento depende do tamanho do lote, da demanda atual e do volume de suas solicitações. É possível que um lote expire e não seja concluído em 24 horas.
Consulte [Modelos suportados](https://platform.claude.com/docs/pt-BR/build-with-claude/batch-processing#supported-models) para ver a lista de modelos suportados.
Sim, a Message Batches API suporta quase todos os recursos disponíveis na Messages API, incluindo a maioria dos recursos beta. Um pequeno número de parâmetros (`stream`, `speed`, `fallbacks` e `max_tokens: 0`) não é suportado. Consulte [O que pode ser processado em lote](https://platform.claude.com/docs/pt-BR/build-with-claude/batch-processing#what-can-be-batched) para ver a lista completa.
A Message Batches API oferece um desconto de 50 por cento em todo o uso em comparação com os preços padrão da API. Isso se aplica a tokens de entrada, tokens de saída e quaisquer tokens especiais. Para mais informações sobre preços, visite [Preços](https://claude.com/pricing#anthropic-api).
Não, depois que um lote é enviado, ele não pode ser modificado. Se precisar fazer alterações, cancele o lote atual e envie um novo. Observe que o cancelamento pode não ter efeito imediato.
A Message Batches API tem limites de taxa baseados em solicitações HTTP, além de limites no número de solicitações que precisam ser processadas. Consulte [Limites de taxa da Message Batches API](https://platform.claude.com/docs/pt-BR/api/rate-limits#message-batches-api). O uso da Batches API não afeta os limites de taxa da Messages API.
Ao recuperar os resultados, cada solicitação tem um campo `result` indicando se ela teve `succeeded`, `errored`, foi `canceled` ou `expired`. Para resultados `errored`, informações adicionais sobre o erro são fornecidas. Veja o objeto de resposta de erro na [referência da API](https://platform.claude.com/docs/pt-BR/api/messages/batches/create).
A Message Batches API foi projetada com fortes medidas de privacidade e separação de dados:
1. Os lotes e seus resultados são isolados dentro do Workspace em que foram criados. Isso significa que eles só podem ser acessados por solicitações de API nesse mesmo Workspace.
2. Cada solicitação dentro de um lote é processada de forma independente, sem vazamento de dados entre solicitações.
3. Os resultados ficam disponíveis apenas por um tempo limitado (29 dias) e seguem a [política de retenção de dados](https://support.claude.com/en/articles/7996866-how-long-do-you-store-personal-data) da Anthropic.
4. O download de resultados de lotes no Console pode ser desativado no nível da organização ou por workspace.
Sim, é possível usar cache de prompt com a Message Batches API. No entanto, como as solicitações assíncronas em lote podem ser processadas simultaneamente e em qualquer ordem, os acertos de cache são fornecidos com base no melhor esforço.
## Disponibilidade
Processamento em lote está disponível em todos os modelos.
### Suporte da API
#### [Messages API](https://platform.claude.com/docs/pt-BR/build-with-claude/working-with-messages)
* Disponibilidade: Disponível
| Status | Plataformas de nuvem |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Disponível | Claude API, [Claude Platform on AWS](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-platform-on-aws), [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-models-on-google-cloud/anthropic-managed) |
#### [Managed Agents](https://platform.claude.com/docs/pt-BR/managed-agents/overview)
* Disponibilidade: Não disponível
### Tratamento de dados
[Visão geral do tratamento de dados](https://platform.claude.com/docs/pt-BR/manage-claude/api-and-data-retention#feature-eligibility)
| Item | Retenção zero de dados | HIPAA |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| Status | Não elegível | Não elegível |
| Detalhes | Retenção de 29 dias; armazenamento assíncrono necessário. [Saiba mais](https://platform.claude.com/docs/pt-BR/build-with-claude/batch-processing#data-retention) | — |
Endpoints aplicáveis:
* `/v1/messages/batches`
O processamento em lote armazena dados de solicitação e resposta por até 29 dias após a criação do lote. Você pode excluir um lote de mensagens a qualquer momento após o processamento usando o endpoint [`DELETE /v1/messages/batches/{batch_id}`](https://platform.claude.com/docs/pt-BR/api/messages/batches/delete). Para excluir um lote em andamento, cancele-o primeiro. O processamento assíncrono requer armazenamento no lado do servidor tanto das entradas quanto das saídas até a conclusão do lote e a recuperação dos resultados.
## Próximos passos
Obtenha citações naturais para aplicações RAG fornecendo resultados de pesquisa com atribuição de fonte.
Reduza custos e latência armazenando em cache prefixos de prompt compartilhados entre solicitações em um lote.