Loop Over Items: processando listas grandes sem travar o fluxo
Como usar o Loop Over Items no n8n para processar listas grandes em lotes, controlando o ritmo e evitando estourar limite de API.
Resumo por IA
Resumo gerado por IA, revisado pela redação.
Loop Over Items processa listas grandes em lotes, em vez de todos os itens de uma vez — o que evita travamento, estouro de limite de API e consumo excessivo de memória quando o fluxo lida com centenas ou milhares de registros.
Adicione ao Google NotíciasPor que o n8n normalmente não precisa de loop explícito
Na maioria dos casos, você não precisa construir um loop manualmente: os nodes do n8n já processam automaticamente cada item recebido, um de cada vez, sem exigir configuração especial. Se um node recebe cinco itens, ele executa a operação cinco vezes sozinho.
Quando o loop explícito é necessário
O Loop Over Items entra quando você precisa de controle sobre o ritmo do processamento — por exemplo, para não estourar o limite de requisições de uma API, processando 50 itens, esperando um pouco, processando os próximos 50.
Como configurar
Adicione o node Loop Over Items (Split in Batches) no ponto do fluxo onde a lista grande chega.
Defina o tamanho do lote — quantos itens processar por vez.
Conecte a saída "loop" ao processamento que deve rodar em cada lote.
Conecte o final desse processamento de volta à entrada do próprio Loop Over Items, fechando o ciclo.
Conecte a saída "done" ao que deve rodar só depois que todos os lotes terminarem.
Combine o loop com um node Wait entre lotes, quando a preocupação for limite de requisições de API. Processar 50 itens, esperar alguns segundos, processar os próximos 50 — isso mantém o fluxo dentro do limite que a maioria das APIs impõe.
Loop até uma condição, com IF
Outra forma de loop existe para quando o critério de parada não é "processei todos os itens", mas uma condição específica: conectar a saída de um node de volta a um node anterior, com um IF checando quando parar. Útil para cenários como "continue tentando até a resposta ser positiva".
O risco de loop sem controle
Sempre defina um critério de parada claro. Um loop mal configurado, sem condição de saída correta, pode rodar indefinidamente, consumindo execuções e, em casos de chamada de API, gerando bloqueio por excesso de requisições. Teste sempre com um conjunto pequeno de dados antes de rodar com a lista completa.
A maioria dos casos não precisa de loop manual — os nodes já processam item por item sozinhos. Use o Loop Over Items quando precisar controlar o ritmo, processando em lotes com pausa entre eles.
Perguntas frequentes
Quando preciso usar o Loop Over Items no n8n?
Quando precisar controlar o ritmo do processamento de uma lista grande, geralmente para não estourar limite de requisições de uma API — processando em lotes, com pausa entre eles.
O n8n já processa listas automaticamente sem loop?
Sim, na maioria dos casos. Os nodes processam cada item recebido automaticamente, um de cada vez, sem precisar de configuração especial de loop.
Como evitar que um loop rode para sempre?
Definindo um critério de parada claro, seja processar todos os itens de uma lista finita ou uma condição verificada por um node IF. Sempre teste com um conjunto pequeno de dados antes de rodar com o volume completo.
Este tutorial faz parte do guia Curso de n8n do zero ao avançado: o guia completo em português. Veja também: Node, trigger e workflow: o vocabulário do n8n em 10 minutos · A estrutura de dados do n8n: por que tudo é um array com json · Item linking no n8n: como ele decide qual item vai pra saída · Execuções passo a passo: como achar onde o fluxo do n8n quebrou · A Canvas UI do n8n 2.0: o que mudou e como se orientar · n8n Cloud ou self-hosted: a decisão que define seu custo e sua liberdade
