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 MessagesPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar.. 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 diretamentePré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar..

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. 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. 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 configurado no Claude Console para o seu Workspace.
• Cada solicitação em lote deve ter max_tokensPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar. 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 da execução da solicitação subsequente.

Modelos suportados

Todos os modelos ativos 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 (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:

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.

Modelo	Tokens em lote
Nome	Entrada	Saída
Claude Fable 5.2For demanding reasoning and long-horizon agentic work	US$ 4 / MTok	US$ 20 / MTok
Claude Opus 5.5For long-running agentic coding and knowledge work	US$ 2 / MTok	US$ 10 / MTok
Claude Sonnet 5.5The best combination of speed and intelligence	US$ 1 / MTok	US$ 5 / MTok
Claude Haiku 5.5For high-volume, latency-sensitive tasks such as classification, extraction, and routing	US$ 0,05 / MTokpara prompts de até 100.000 tokens	US$ 0,25 / MTok
	US$ 0,25 / MTokpara prompts acima de 100.000 tokens	US$ 1,25 / MTok
Modelos adicionais
Claude Mythos 5.2	US$ 4 / MTok	US$ 20 / MTok
Claude Fable 5.1	US$ 5 / MTok	US$ 25 / MTok
Claude Mythos 5.1	US$ 5 / MTok	US$ 25 / MTok
Claude Fable 5	US$ 5 / MTok	US$ 25 / MTok
Claude Mythos 5	US$ 5 / MTok	US$ 25 / MTok
Claude Opus 5	US$ 2,50 / MTok	US$ 12,50 / MTok
Claude Opus 4.8	US$ 2,50 / MTok	US$ 12,50 / MTok
Claude Opus 4.7	US$ 2,50 / MTok	US$ 12,50 / MTok
Claude Opus 4.6	US$ 2,50 / MTok	US$ 12,50 / MTok
Claude Opus 4.5	US$ 2,50 / MTok	US$ 12,50 / MTok
Claude Opus 4.1	US$ 7,50 / MTok	US$ 37,50 / MTok
Claude Opus 4	US$ 7,50 / MTok	US$ 37,50 / MTok
Claude Sonnet 5	US$ 1 / MTok	US$ 5 / MTok
Claude Sonnet 4.6	US$ 1,50 / MTok	US$ 7,50 / MTok
Claude Sonnet 4.5	US$ 1,50 / MTok	US$ 7,50 / MTok
Claude Sonnet 4	US$ 1,50 / MTok	US$ 7,50 / MTok
Claude Haiku 4.5	US$ 0,50 / MTok	US$ 2,50 / MTok

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_idPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar. 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 paramsPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar. com os parâmetros padrão da Messages APIPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar.

Você pode criar um lotePré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar. passando essa lista para o 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 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.

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_statusPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar. 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 ou usando o endpoint de recuperação.

“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:

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 lotes de mensagens

Você pode listar todos os lotes de mensagens no seu Workspace usando o endpoint de listagemPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar.. Os resultados são paginados. O SDK busca 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 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:

O objeto request_counts do lote contabiliza as solicitações ainda em processamento e as solicitações de cada tipo de resultado.

Os resultados do lote ficam disponíveis para download na propriedade results_urlPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar. 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 resultadosPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar. 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 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:

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

Os resultados do lote usam a versão da API da requisição que criou o lote.

Cancelando um lote de mensagens

Você pode cancelar um lote de mensagens que está em processamento usando o endpoint de cancelamentoPré-visualização disponível com links para a referência da API — pressione Tab até o foco entrar no cartão, Escape para voltar.. 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.

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 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:

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

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.

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.

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)

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

Próximos passos