O 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ê deseja 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, reduzindo custos em 50% e aumentando o throughput.

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 de todas as requisições tiver terminado.

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 propósitos (por exemplo, descrições de produtos, resumos de artigos).

Limitações de lote

• 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 forem concluídas ou após 24 horas, o que ocorrer primeiro. Os lotes expiram se o processamento não for concluído em até 24 horas.
• Os resultados do lote ficam disponíveis por 29 dias após a criação. Depois disso, você ainda poderá visualizar o lote, mas seus resultados não estarão mais disponíveis para download.
• Os lotes têm escopo limitado a um Workspace. Você pode visualizar todos os lotes (e seus resultados) que foram criados dentro do Workspace ao qual sua chave de API pertence.
• 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 ao alto throughput e ao processamento concorrente, os lotes podem exceder ligeiramente o limite de gastos configurado do seu Workspace.
• Cada requisição em lote deve ter max_tokens de pelo menos . () não é suportado dentro de um lote, já que uma entrada de cache efêmera gravada durante o processamento do lote provavelmente expiraria antes da execução da requisição subsequente.

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
• 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 multi-turno
• 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 de lote. Incluir qualquer um destes retorna um erro de validação:

Preços

A Batches API oferece economia significativa de custos. Todo o uso é cobrado a 50% dos preços padrão da API.

Como usar a Message Batches API

Preparar e criar seu lote

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

• 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 underscores (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:

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 terá 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 está. Ele começa como in_progress e depois é atualizado para ended quando todas as requisições no lote terminaram 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 para conclusão do Message Batch

Para fazer polling de 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 termine:

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:

Recuperando resultados do lote

Quando o processamento do lote termina, cada requisição de Messages no lote tem um resultado. Existem 4 tipos de resultado:

Você verá uma visão geral dos seus resultados com o request_counts do lote, que mostra 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.

Os resultados estão no formato .jsonl, onde 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 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-4-8","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-4-8","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 no momento 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 acima para aguardar até que o cancelamento seja finalizado. Lotes cancelados terminam com um status ended e podem conter resultados parciais para requisições que foram processadas antes do cancelamento.

A resposta mostrará 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 requisições em lote. Os descontos de preço do cache de prompt e do Message Batches podem ser acumulados, proporcionando economia de custos ainda maior 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 variando de 30% a 98%, dependendo de seus padrões de tráfego.

Para maximizar a probabilidade de acertos de cache em suas requisições de 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:

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 de 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 a ser mantida, 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 foi concluído; 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 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 aumenta o limite de max_tokens para 300.000 em requisições de lote usando Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6 ou Claude Sonnet 4.6. Inclua o cabeçalho para gerar saídas muito mais longas do que o limite padrão (64k a 128k dependendo do modelo) em um único turno.

Use a saída estendida para geração de conteúdo longo, 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, então 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).

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 retry apropriada para requisições com falha.
• Use valores de custom_id significativos para corresponder facilmente resultados com 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 de execução de um único formato de requisição com a Messages API para evitar erros de validação.

Solução de problemas comuns

Se estiver experimentando comportamento inesperado:

• Verifique se o tamanho total da requisição de 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.
• Certifique-se de que cada requisição no lote tenha um custom_id único.
• Certifique-se de que se passaram 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 se passaram, os resultados não estarão mais visíveis.
• Confirme que o lote não foi cancelado.

Observe que a falha de uma requisição em um lote não afeta o processamento de outras requisições.

Armazenamento de lote e privacidade

• Isolamento de Workspace: os lotes são isolados dentro do Workspace em que são criados. Eles só podem ser acessados por chaves de API associadas a esse 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 message batch 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 de entradas quanto de 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