O "batch processing" (processamento em lote) é uma abordagem poderosa para lidar com grandes volumes de requisições de forma eficiente. Em vez de processar requisições uma de cada vez com respostas imediatas, o processamento em lote permite que você envie várias requisiçõ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ê quer otimizar a eficiência de custos
• Você está executando avaliações ou análises em larga escala

A Message Batches API é a primeira implementação desse padrão pela Anthropic.

Message Batches API

A Message Batches API é uma forma poderosa e econômica de processar de forma assíncrona grandes volumes de requisições de Messages. Essa abordagem é adequada para tarefas que não exigem respostas imediatas, com a maioria dos lotes sendo concluída em menos de 1 hora, ao mesmo tempo em que reduz os custos em 50% e aumenta a taxa de transferência.

Você pode explorar a referência da API diretamente, além deste guia.

Como a Message Batches API funciona

Quando você envia uma requisição para a Message Batches API:

1. O sistema cria um novo Message Batch com as requisições de Messages fornecidas.
2. O lote é então processado de forma assíncrona, com cada requisiçã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 requisiçõ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 Message Batch é limitado a 100.000 requisiçõ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 poderá visualizar o Batch, mas seus resultados não estarão mais disponíveis para download.
• Os lotes têm escopo de um Workspace. Você pode visualizar todos os lotes (e seus resultados) que foram criados dentro do Workspace em que sua requisição é executada.
• Os "rate limits" (limites de taxa) se aplicam tanto às requisições HTTP da Batches API quanto ao número de requisições dentro de um lote aguardando processamento. Consulte limites de taxa da Message Batches API. Além disso, o processamento pode ser desacelerado com base na demanda atual e no seu volume de requisições. Nesse caso, você pode ver mais requisições expirando após 24 horas.
• Devido à alta taxa de transferência e ao processamento concorrente, os lotes podem ultrapassar ligeiramente o limite de gastos configurado do seu Workspace.
• Cada requisição em lote deve ter max_tokens de pelo menos 1. max_tokens: 0 (pré-aquecimento do cache) não é suportado dentro de um lote, porque uma entrada de cache efêmera gravada durante o processamento do lote provavelmente expiraria antes que a requisição subsequente fosse executada.

Modelos suportados

Todos os modelos ativos suportam a Message Batches API.

O que pode ser processado em lote

Quase qualquer requisição que você pode fazer à Messages API pode ser incluída em um lote. Isso inclui:

• Visão
• "Tool use" (uso de ferramentas), incluindo todas as ferramentas de servidor (busca na web, busca de conteúdo web, execução de código, conectores MCP, advisor e busca de ferramentas)
• Mensagens de sistema
• Conversas de múltiplos turnos
• "Extended thinking" (pensamento estendido)
• A maioria dos recursos beta

Como cada requisição no lote é processada de forma independente, você pode misturar diferentes tipos de requisições em um único lote.

Um pequeno número de parâmetros da Messages API não é suportado em requisições em lote. Incluir qualquer um deles retorna um erro de validação:

Preços

A Batches API oferece economias de custo significativas. Todo o uso é cobrado a 50% dos preços padrão da API.

Model	Batch tokens
Name	Input	Output
Claude Fable 5.1For demanding reasoning and long-horizon agentic work	$5 / MTok	$25 / MTok
Claude Opus 5.5For long-running agentic coding and knowledge work	$2 / MTok	$10 / MTok
Claude Sonnet 5.5The best combination of speed and intelligence	$1 / MTok	$5 / MTok
Claude Haiku 4.5The fastest model with near-frontier intelligence	$0.50 / MTok	$2.50 / MTok
Additional models
Claude Mythos 5.1	$5 / MTok	$25 / MTok
Claude Fable 5	$5 / MTok	$25 / MTok
Claude Mythos 5	$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	$7.50 / MTok	$37.50 / MTok
Claude Opus 4	$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	$1.50 / MTok	$7.50 / MTok
Claude Haiku 3.5	$0.40 / MTok	$2 / MTok

Como usar a Message Batches API

Prepare e crie seu lote

Um Message Batch é composto por uma lista de requisições para criar uma Message. O formato de uma requisição individual compreende:

• Um custom_id único para identificar a requisição de Messages. Deve ter de 1 a 64 caracteres e conter apenas caracteres alfanuméricos, hífens e sublinhados (correspondendo a ^[a-zA-Z0-9_-]{1,64}$).
• Um objeto params com os parâmetros padrão da Messages API

Você pode criar um lote passando essa lista no parâmetro requests:

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)

Neste exemplo, duas requisições separadas são agrupadas em lote para processamento assíncrono. Cada requisição tem um custom_id único e contém os parâmetros padrão que você usaria para uma chamada à Messages API.

Quando um lote é criado pela primeira vez, a resposta tem um status de processamento in_progress.

{
  "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 do Message Batch indica o estágio de processamento em que o lote se encontra. Ele começa como in_progress, depois é atualizado para ended quando todas as requisições no lote tiverem terminado de ser processadas e os resultados estiverem prontos. Você pode monitorar o estado do seu lote visitando o Console ou usando o endpoint de recuperação.

Consultando a conclusão do Message Batch

Para consultar um Message Batch, 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 tenha terminado:

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)

Listando todos os Message Batches

Você pode listar todos os Message Batches no seu Workspace usando o endpoint de listagem. A API suporta paginação, buscando automaticamente páginas adicionais conforme necessário:

client = anthropic.Anthropic()

# Busca automaticamente mais páginas conforme necessário.
for message_batch in client.messages.batches.list(limit=20):
    print(message_batch)

Recuperando resultados do lote

Quando o processamento do lote tiver terminado, cada requisição de Messages no lote terá um resultado. Existem quatro tipos de resultado:

O request_counts do lote mostra uma visão geral dos seus resultados, indicando quantas requisições atingiram cada um desses quatro estados.

Os resultados do lote estão disponíveis para download na propriedade results_url do Message Batch e, se a permissão da organização permitir, no Console. Devido ao tamanho potencialmente grande dos resultados, é recomendado fazer streaming dos resultados em vez de baixá-los todos de uma vez.

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}")

Os resultados estão no formato .jsonl, em que cada linha é um objeto JSON válido representando o resultado de uma única requisição no Message Batch. 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:

{"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 o formato de erro padrão.

Cancelando um Message Batch

Você pode cancelar um Message Batch que está sendo processado usando o endpoint de cancelamento. Imediatamente após o cancelamento, o processing_status de um lote será canceling. Você pode usar a mesma técnica de polling descrita anteriormente para aguardar até que o cancelamento seja finalizado. Os lotes cancelados terminam com um status ended e podem conter resultados parciais para requisições que foram processadas antes do cancelamento.

client = anthropic.Anthropic()

MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"

message_batch = client.messages.batches.cancel(
    MESSAGE_BATCH_ID,
)
print(message_batch)

A resposta mostra o lote em um estado canceling:

{
  "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 "prompt caching" (cache de prompt), permitindo que você potencialmente reduza custos e tempo de processamento para requisiçõ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 requisições em lote são processadas de forma assíncrona e concorrente, os acertos de cache são fornecidos com base no melhor esforço. Os usuários normalmente experimentam taxas de acerto de cache que variam de 30% a 98%, dependendo de seus padrões de tráfego.

Para maximizar a probabilidade de acertos de cache em suas requisições em lote:

1. Inclua blocos cache_control idênticos em cada requisição de Message dentro do seu lote.
2. Mantenha um fluxo constante de requisições para evitar que as entradas de cache expirem após seu tempo de vida de 5 minutos.
3. Estruture suas requisições para compartilhar o máximo possível de conteúdo em cache.

Exemplo de implementação de cache de prompt em um lote:

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": "<the entire contents of Pride and Prejudice>",
                        "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": "<the entire contents of Pride and Prejudice>",
                        "cache_control": {"type": "ephemeral"},
                    },
                ],
                messages=[
                    {
                        "role": "user",
                        "content": "Write a summary of Pride and Prejudice.",
                    }
                ],
            ),
        ),
    ]
)

Neste exemplo, ambas as requisições no lote incluem mensagens de 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 (busca na web, busca de conteúdo web, execução de código, conectores MCP, advisor e busca de ferramentas) funcionam em requisições em lote. O worker de lote executa o mesmo loop agêntico do lado do servidor que a Messages API síncrona.

Como não há conexão aberta para manter, o loop de lote executa mais iterações por turno do que uma requisição síncrona antes de retornar stop_reason: "pause_turn". Se um resultado de lote retornar com pause_turn, o turno não terminou; você pode continuá-lo enviando o conteúdo pausado do assistente em uma requisição subsequente (em lote ou síncrona) exatamente como mostrado no padrão de continuação de pause_turn.

O worker de lote adicionalmente limita web_search por organização para que o processamento em lote altamente concorrente não esgote o limite de taxa de busca na web da sua organização. O lote tenta novamente as requisições limitadas automaticamente; você não precisa lidar com isso por conta própria, mas lotes muito grandes de busca 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 ou Claude Sonnet 4.6. 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.

Use a saída estendida para geração de conteúdo longo, como rascunhos com extensão de livro 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 tendo em mente a janela de processamento de 24 horas. Aplica-se o preço padrão de lote (50% dos preços padrão da API).

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)

Melhores práticas para processamento em lote eficaz

Para aproveitar ao máximo a Batches API:

• Monitore o status de processamento do lote regularmente e implemente lógica de repetição apropriada para requisições com falha.
• Use valores de custom_id significativos para corresponder facilmente os resultados às requisições, já que a ordem não é garantida.
• Considere dividir conjuntos de dados muito grandes em vários lotes para melhor gerenciamento.
• Faça um teste com um único formato de requisição na Messages API para evitar erros de validação.

Solução de problemas comuns

Se estiver enfrentando comportamento inesperado:

• Verifique se o tamanho total da requisição do lote não excede 256 MB. Se o tamanho da requisição for muito grande, você pode receber um erro 413 request_too_large.
• Verifique se você está usando modelos suportados para todas as requisições no lote.
• Garanta que cada requisição no lote tenha um custom_id único.
• Garanta que tenham passado menos de 29 dias desde o horário created_at do lote (não o horário ended_at do processamento). Se mais de 29 dias tiverem passado, os resultados não poderão mais ser visualizados.
• Confirme que o lote não foi cancelado.

Observe que a falha de uma requisição em um lote não afeta o processamento das outras requisiçõ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 requisiçõ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, permitindo tempo suficiente para recuperação e processamento.

Retenção de dados

O processamento em lote armazena dados de requisiçã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}. Para excluir um lote em andamento, cancele-o primeiro. O processamento assíncrono requer armazenamento do lado do servidor tanto das entradas quanto das saídas até a conclusão do lote e a recuperação dos resultados.

Para elegibilidade de ZDR em todos os recursos, consulte API e retenção de dados.

Perguntas frequentes

Próximos passos