Loop no n8n: como usar o Loop Over Items no fluxo

Veja quando o n8n já repete o trabalho sozinho, quando usar o Loop Over Items, como configurar Batch Size, saídas e Reset, e um exemplo de envio em lotes com Wait.

Por Redação Eleven Host · @robson.direitodigital · 29 de outubro de 2026 · 8 min de leitura

O loop no n8n muitas vezes já acontece sozinho, porque, em geral, cada nó roda uma vez para cada item que recebe. O Loop Over Items (antigo Split in Batches) serve para processar em lotes, por exemplo para respeitar o limite de requisições de uma API.

Este guia mostra quando o n8n repete o trabalho por conta própria, quando vale montar o loop, como configurar o nó (Batch Size, as saídas e o Reset) e um exemplo que envia os itens de pouco em pouco, com uma pausa entre as voltas. Ele segue a documentação do n8n sobre o nó Loop Over Items, a página "Looping in n8n" e o nó HTTP Request.

O n8n já faz loop sozinho

A página "Looping in n8n" explica que os nós recebem uma quantidade variável de itens, processam esses itens e devolvem os resultados. Em geral, um nó roda uma vez para cada item que chega. Se uma planilha entrega 50 linhas, o nó seguinte já trata as 50, uma a uma, sem você desenhar uma volta no fluxo.

Por isso a própria documentação avisa que, dependendo do que você quer fazer, muitas vezes você não precisa do nó Loop Over Items. Antes de montar um loop, rode o fluxo com alguns itens de teste e olhe quantas execuções cada nó fez.

A documentação lista exceções, ou seja, nós e operações que não rodam item a item e pedem que você monte o loop:

• CrateDB, MongoDB e TimescaleDB: executam uma vez para inserir e atualizar.
• Microsoft SQL: executa uma vez para inserir, atualizar e apagar.
• QuestDB: executa uma vez para inserir.
• Nó Code no modo Run Once for All Items. O guia Code no n8n: como usar JavaScript no seu fluxo explica os dois modos.
• Nó Execute Workflow no modo Run Once for All Items.
• HTTP Request: a paginação (buscar a página 2, a 3 e assim por diante) fica por sua conta.
• Redis, operação Info: executa só uma vez, não importa quantos itens cheguem.
• RSS Read: executa uma vez para o endereço pedido.

Quando usar o Loop Over Items

Segundo a documentação, o nó ajuda a percorrer os dados em voltas quando for preciso. Ele guarda os dados que chegaram e, a cada volta, devolve uma quantidade fixa deles. A página lista três situações em que ele é útil:

1. repetir o trabalho até processar os itens, de um jeito controlado;
2. lidar com as exceções da lista acima;
3. dividir os pedidos a uma API em lotes, para não estourar o limite de requisições (o "rate limit").

O terceiro caso aparece quando você chama APIs. Se a API que você chama aceita poucas requisições por minuto, mandar 500 itens de uma vez pode gerar o erro 429 Too Many Requests. Dividir em lotes e pôr uma pausa entre eles é o caminho que a documentação sugere.

Existe também uma alternativa sem loop para quem só chama API. O nó HTTP Request tem a opção Batching, com os campos Items per Batch (quantos itens entram em cada lote) e Batch Interval (o tempo de espera entre os lotes, em milissegundos; 0 significa sem intervalo). Pela documentação, 1000 corresponde a um segundo.

Quer um n8n para montar seus fluxos? O n8n Essencial sai a partir de R$ 19,90/mês. Ver planos de n8n

Como configurar o Loop Over Items

O nó tem um parâmetro principal, duas saídas e uma opção avançada.

Batch Size

Em Batch Size você informa quantos itens devem sair em cada volta. Para tratar um item por vez, a documentação manda usar Batch Size igual a 1. Com um valor maior, cada volta devolve um lote com essa quantidade de itens.

As saídas loop e done

• loop: a cada volta, o lote da vez sai por aqui. Ligue nesta saída os nós que fazem o trabalho (enviar, gravar, chamar uma API) e, no fim deles, ligue a última seta de volta na entrada do Loop Over Items.
• done: quando os itens acabam, o nó junta o que foi processado e devolve tudo por esta saída. Ligue aqui o que deve rodar uma única vez no final, como um aviso de que o trabalho terminou.

Segundo a página "Looping", o nó para de executar depois que os itens recebidos foram divididos em lotes. Por isso você não precisa de um nó IF para encerrar a volta. Se mais adiante quiser tomar decisões dentro do fluxo, use o nó IF para isso.

A opção Reset

A documentação descreve o Reset assim: se estiver ligado, o nó reinicia com os dados de entrada recém-inicializados a cada volta. Use quando quiser que o nó trate os dados que chegam como um conjunto novo. Com o Reset ligado, é possível escrever uma expressão, e o resultado dela determina quando o nó reinicia o processamento dos itens.

Expressões úteis

A documentação traz duas expressões para acompanhar o loop:

{{$("Loop Over Items").context["noItemsLeft"]}}

{{$("Loop Over Items").context["currentRunIndex"];}}

A primeira devolve false enquanto ainda há itens e true quando acabaram. A segunda devolve o número da volta atual.

Exemplo: enviar de pouco em pouco com Wait

Este fluxo é uma montagem nossa a partir do que a documentação descreve: lotes mais uma pausa, para respeitar o limite de uma API. Os nomes e valores são fictícios. Siga a ordem:

1. Comece com um gatilho. Para testar, use o gatilho manual. Para rodar em horários marcados, veja o guia Agendar fluxo no n8n: como usar o Schedule Trigger.
2. Adicione um nó que leia as linhas a processar, por exemplo o Google Sheets, como no guia n8n com Google Sheets: como conectar e automatizar planilhas.
3. Adicione o nó Loop Over Items e deixe Batch Size igual a 1.
4. Na saída loop, ligue o nó que faz o trabalho, por exemplo um HTTP Request que envia um item para a API. O guia HTTP Request no n8n: como chamar uma API no fluxo mostra como configurar esse nó.
5. Depois do HTTP Request, adicione o nó Wait e defina uma pausa de alguns segundos.
6. Ligue a saída do Wait de volta na entrada do Loop Over Items. É essa seta que fecha a volta.
7. Na saída done, ligue um aviso de fim, como uma mensagem ou um registro.
8. Execute com poucos itens de teste e acompanhe volta por volta.

Quantos segundos de pausa usar depende do limite de cada API. Veja o limite na documentação da API que você chama e ajuste o Wait a partir dele.

Em cada volta o fluxo envia um item, espera e volta ao Loop Over Items, que entrega o próximo. Quando os itens acabam, o nó passa pela saída done.

Erros comuns

• Loop desnecessário: se o nó seguinte já roda para cada item, o Loop Over Items só deixa o fluxo mais longo. Teste primeiro sem ele.
• Seta de volta esquecida: sem ligar o fim do trabalho de volta ao Loop Over Items, o fluxo pode processar só o primeiro lote. Confira se a última seta da saída loop chega à entrada do nó.
• Trabalho ligado na saída errada: o que faz o envio vai na saída loop. O que deve rodar uma vez no final vai na done.
• Reset sem condição de parada: se a condição não chegar a ser verdadeira, o fluxo fica preso num loop sem fim.
• Paginação confundida com loop: no HTTP Request, a paginação é por sua conta. A opção Pagination do nó serve para resultados grandes demais para a API entregar de uma vez.
• Pausa curta para o limite da API: se a API ainda recusar pedidos, aumente o Wait ou diminua o tamanho do lote, depois de conferir o limite na documentação dela.

Para montar e testar seus loops, veja o n8n Essencial a partir de R$ 19,90/mês e confira na loja o que cada plano inclui. Conhecer o n8n

Perguntas frequentes

Preciso do Loop Over Items para repetir um nó para cada item?

Em geral, não. Segundo a documentação, os nós rodam uma vez para cada item que chega, e muitas vezes você não precisa do Loop Over Items. Ele é útil nas exceções da lista, para repetir de forma controlada e para dividir pedidos a uma API em lotes.

O que o Batch Size faz?

Define quantos itens saem em cada volta do loop. Para tratar um item por vez, a documentação indica o valor 1.

Qual a diferença entre as saídas loop e done?

A saída loop entrega o lote da vez a cada volta. A saída done entrega, quando os itens acabam, tudo o que foi processado junto.

Como evito estourar o limite de uma API?

Divida os itens em lotes com o Loop Over Items e ponha um nó Wait entre as voltas, como sugere a documentação. O tempo de pausa depende do limite de cada API. Para chamadas simples, o nó HTTP Request também tem a opção Batching, com intervalo em milissegundos.