Guia técnico: criando até 100 instâncias de Cloudflare Workflows com createBatch() e Wrangler 4.148.0+

O Cloudflare Workflows (abre em nova aba) ganhou em 8 de outubro de 2026, segundo o changelog oficial, uma forma nova do método createBatch(): um objeto de opções que cria até 100 instâncias de um Workflow em uma única chamada. A forma antiga, que recebia um array direto, continua funcionando, mas foi marcada como obsoleta. Este guia mostra o caminho completo para adotar a nova sintaxe, desde a versão correta do Wrangler até a interpretação do resultado e o diagnóstico dos erros.

A mudança importa na prática. Criar instâncias em loop, uma chamada create() por vez, é o padrão que a própria documentação de boas práticas desaconselha: cada requisição conta contra o limite de criação de instâncias e aumenta a chance de esbarrar em rate limit. Com createBatch(), a chamada inteira é tratada pela API como uma única criação para fins de limite, embora cada instância individual do lote ainda conte contra a taxa de criação, como esclarece a página de regras do Workflows. Menos requisições, menos atrito, e um contrato de retorno mais honesto: o que não foi criado aparece em um array errors, em vez de ser simplesmente omitido.

Para que serve e quem precisa disso

O createBatch() serve para qualquer cenário em que um Worker precisa disparar muitas execuções do mesmo Workflow de uma vez: processar um lote de pedidos, gerar relatórios por cliente, enfileirar reprocessamento de arquivos, dividir um job de IA em partes independentes. Se o seu código chama create() dentro de um for, este é o caso de uso.

O resultado esperado é um objeto WorkflowBatchCreateResult com dois campos: created, com as instâncias efetivamente criadas na ordem do input, e errors, com cada entrada que falhou, identificada pela posição no array de entrada, além de um código e uma mensagem. IDs duplicados ou já existentes não derrubam a chamada; viram entradas em errors.

Pré-requisitos técnicos

Sobre o custo: a documentação de limits não cobra por chamada de createBatch(); o que limita é a taxa de criação de instâncias. No plano Workers Free, a taxa máxima é de 100 criações de instâncias por segundo; no Workers Paid, 300 por segundo por conta e 100 por segundo por Workflow. Os limites de execução (instâncias concorrentes, fila e execuções diárias) também variam por plano e são independentes do tamanho do lote.

Passo a passo: criar lotes com createBatch()

1. Atualize o Wrangler para 4.148.0 ou superior

Verifique a versão instalada e atualize o pacote no seu projeto:

npx wrangler --version
npm install -D wrangler@latest

A versão precisa ser 4.148.0 ou maior. Sem isso, o desenvolvimento local não reconhece a forma de objeto e os tipos gerados por wrangler types ficam desatualizados.

2. Regenere os tipos

npx wrangler types

Isso atualiza o arquivo de tipos do ambiente (por padrão, worker-configuration.d.ts), incluindo a assinatura nova:

createBatch(options: WorkflowBatchCreateOptions): Promise<WorkflowBatchCreateResult>

Sinal de sucesso: o editor passa a aceitar env.MY_WORKFLOW.createBatch({ count: 10 }) sem erro de tipo, e a forma antiga com array direto deve exibir aviso de deprecação, se a versão dos tipos estiver correta.

3. Escolha a forma do lote: count ou instances

A API aceita exatamente uma das duas, nunca ambas na mesma chamada. Usar count e instances juntos é um erro.

Forma compartilhada com count: cria N instâncias idênticas, com parâmetros e retenção iguais, e um ID gerado automaticamente para cada uma. É o caminho quando as instâncias só diferem pelo ID, como no exemplo do changelog:

let { created, errors } = await env.MY_WORKFLOW.createBatch({
  count: 10,
  params: { report: "daily" },
});

O count deve ser um inteiro de 1 a 100. O params é opcional, assim como retention, que aceita successRetention e errorRetention.

Forma individual com instances: cada entrada define o próprio ID e as próprias opções, usando os mesmos WorkflowInstanceCreateOptions de create():

let { created, errors } = await env.MY_WORKFLOW.createBatch({
  instances: [
    { id: "order-1", params: { orderId: 1 } },
    { id: "order-2", params: { orderId: 2 } },
  ],
});

O array instances deve ter de 1 a 100 entradas. Os IDs não são obrigatórios: se você omitir o id de uma entrada, a instância recebe um ID gerado, igual ao comportamento de create().

4. Trate o resultado com created e errors

Não assuma que tudo foi criado. O retorno é um objeto, e é por ele que você confere o que aconteceu:

const result = await env.MY_WORKFLOW.createBatch({
  instances: [/* até 100 entradas */],
});

for (const instance of result.created) {
  console.log("criada:", instance.id);
}

for (const error of result.errors) {
  console.log(`falhou na posição ${error.index}`, error.code, error.message);
}

Cada item de errors traz index (a posição da entrada no input), id quando a entrada tinha um, além de code e message. A ordem de created segue a ordem do input.

5. Faça a chamada de dentro do Worker

O createBatch() é um método da API de Workers, chamado a partir de um Worker que tem o binding do Workflow. Um esqueleto funcional:

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const result = await env.MY_WORKFLOW.createBatch({
      count: 50,
      params: { report: "daily" },
    });

    return Response.json({
      criadas: result.created.length,
      falhas: result.errors.length,
    });
  },
};

O motivo de concentrar tudo numa chamada: a página de regras do Workflows recomenda explicitamente o batch para reduzir o número de requisições à API e evitar os rate limits de criação que um loop de create() tende a atingir.

6. Planeje a manutenção do código legado

Se o projeto usa a forma de array, migre com cuidado, porque a semântica muda. Um código que hoje ignora o retorno da forma antiga pode estar perdendo instâncias por IDs duplicados sem perceber. Ao migrar:

1. Substitua a chamada por { instances: [...] }.
2. Passe a ler created em vez do retorno direto.
3. Adicione tratamento para errors, ao menos em log.
4. Rode npx wrangler types de novo para eliminar qualquer divergência de tipos.

Como verificar que o lote funcionou

A verificação tem duas camadas: a resposta da chamada e o estado das instâncias.

1. Confira os tamanhos dos arrays. A soma de created.length e errors.length deve ser igual ao número de instâncias pedidas (ou ao count, na forma compartilhada). Se a soma fecha, nenhuma entrada ficou em limbo.
2. Confira a ordem. O created preserva a ordem do input. Se você pediu order-1 e order-2, e só a primeira foi criada por ID duplicado, o errors deve apontar index: 1 com o código correspondente.
3. Confira os códigos de erro. Dois códigos são documentados na Workers API: 10405 indica que já existe uma instância com aquele ID (dentro da retenção); 10415 indica que uma entrada anterior no mesmo lote já usou esse ID, e nesse caso apenas a primeira entrada com o ID é criada.
4. Observe as instâncias. Em desenvolvimento local, o wrangler dev mantém o painel de instâncias de Workflow, onde cada instância criada aparece com seu ID e status de execução. Em produção, o dashboard do Cloudflare lista as instâncias do Workflow.
5. Teste com um ID já existente de propósito. Dispare um lote com um ID que você sabe que está dentro da retenção. O comportamento correto da forma de objeto é: a chamada retorna normalmente, sem exceção, e o ID aparece em errors com código 10405. Se a chamada lançar exceção nesse cenário, você está na forma de array, não na de objeto.

Erros comuns e soluções

Chamar com count e instances juntos

A API não permite os dois na mesma chamada. A solução é escolher: count para instâncias idênticas com ID gerado, instances para controle individual. Se precisar dos dois comportamentos, faça duas chamadas.

Passar mais de 100 entradas ou count fora do intervalo

O intervalo documentado é de 1 a 100, tanto para count (que deve ser inteiro) quanto para instances. Acima disso, divida o lote em chamadas de até 100. Ao dividir, lembre que cada instância individual do lote ainda conta contra a taxa de criação do plano: 100 criações por segundo no Free, 300 por segundo por conta no Paid, com um teto adicional de 100 por segundo por Workflow no plano pago.

Receber uma exceção antes de qualquer criação

Este é um comportamento documentado que surpreende: se qualquer entrada do lote tiver opções inválidas, como um ID malformado ou uma duração de retenção inaceitável, a chamada lança exceção e nenhuma instância do lote é criada. A validação é atômica. A solução é validar as entradas antes de enviar, especialmente IDs (limite de 100 caracteres, segundo a página de Limits) e retenções, se as entradas vêm de dados externos.

Esperar exceção para ID duplicado e ela não vem

Quem migra de create() espera throw quando o ID existe. Na forma de objeto de createBatch(), isso não acontece por design: a entrada vai para errors com código 10405. A solução é trocar o bloco try/catch por verificação de errors após a chamada.

Não ver algumas instâncias que "deveriam" existir

Dois suspeitos usuais. Primeiro, a forma de array antiga, que pula silenciosamente IDs duplicados sem reportar nada; migre para o objeto. Segundo, IDs repetidos dentro do próprio lote: com a forma de objeto, a primeira entrada com o ID é criada e as repetições viram errors com código 10415. Gere IDs únicos no lado de quem monta o lote.

Tipos desatualizados no editor

Se o TypeScript reclama de createBatch({ count: ... }), quase sempre é o Wrangler abaixo de 4.148.0 ou os tipos não regenerados. Atualize o pacote e rode npx wrangler types.

Erros, retenção e os limites por plano

Uma tabela ajuda a situar o lote dentro dos limites de conta. Os valores vêm da página de Limits do Workflows:

A retenção explica um detalhe que gera bug intermitente: um ID só pode ser reutilizado depois que a instância anterior sai da janela de retenção, que vai de 3 dias no Free a 30 dias no Paid. Um lote noturno que usa IDs fixos como "daily-report" vai falhar com 10405 no segundo dia dentro da mesma janela. Prefira IDs com sufixo de data, ou aceite o erro como sinal de que o job anterior ainda está retido.

Perguntas frequentes