Boucles dans n8n : le node Loop Over Items (et quand vous n'en avez pas besoin)

Quand j’ai commencé n8n , je venais du code. Et dans le code, dès qu’on a une liste de choses à traiter, le réflexe est immédiat : on écrit une boucle. for chaque élément, fais ceci. Alors la première fois que j’ai eu 50 lignes à envoyer vers une API, j’ai cherché le node « boucle », je l’ai posé, j’ai galéré à le câbler, et j’ai fini par obtenir un workflow qui tournait… mais bien plus compliqué qu’il n’aurait dû l’être.

Le déclic est arrivé le jour où j’ai compris une chose que personne ne dit au début : dans n8n, la plupart des nodes bouclent déjà tout seuls. Le node Loop Over Items existe, il est utile, mais neuf fois sur dix ce n’est pas lui qu’il vous faut. Ce guide vous explique le bon modèle mental, le test simple pour savoir si vous avez besoin d’une boucle, les rares cas où elle devient indispensable, et les pièges qui font tourner un workflow en rond.

Le modèle mental à intégrer : n8n boucle déjà pour vous

Dans n8n, la donnée qui circule entre les nodes n’est pas « une chose », c’est une liste de choses. On appelle chaque élément un item. Un node qui récupère 50 lignes d’un Google Sheets ne sort pas un gros bloc : il sort 50 items, alignés les uns derrière les autres.

Regardez maintenant le node suivant. La quasi-totalité des nodes n8n s’exécutent une fois par item, automatiquement. Vous branchez un HTTP Request derrière vos 50 lignes ? Il part 50 fois, un appel par ligne, sans que vous ayez rien à câbler. Vous mettez un node Notion pour créer une page ? Il crée 50 pages. La boucle est déjà là, invisible, intégrée au moteur.

Ce que vous posez	Ce que vous croyez qu’il faut	Ce qui se passe vraiment
50 items → HTTP Request	Une boucle autour du HTTP Request	Le HTTP Request part 50 fois tout seul
50 items → Set (Edit Fields)	Boucler pour modifier chaque ligne	Le node modifie chaque item en une passe
50 items → Notion (create)	Une boucle de création	50 pages créées, une par item

Ce fonctionnement porte un nom : l’exécution item-based. C’est ce qui distingue n8n de la logique d’un script classique, et c’est ce qui déroute les gens qui arrivent avec des réflexes de développeur. Une fois qu’on l’a intégré, la moitié des « comment je fais une boucle ? » disparaissent : la réponse est « vous ne la faites pas, elle est déjà faite ».

Le test simple : avez-vous besoin d’une boucle ?

Puisque n8n itère par défaut, la bonne question devient : ai-je une raison de casser ce comportement automatique ? La plupart du temps, non. Pour trancher, une seule chose à se demander : les items ont-ils besoin d’être traités par paquets, ou l’un après l’autre en tenant compte des précédents ?

• Si chaque item est indépendant et peut être traité en même temps que les autres → pas de boucle. Laissez n8n faire.
• Si les items doivent partir par lots espacés dans le temps, ou si le traitement de l’un dépend de ce qui s’est passé avant → là, le node Loop Over Items a un rôle.

Deux nodes utilitaires renforcent encore ce « pas de boucle par défaut », et beaucoup de débutants les sous-estiment :

• Le node Filter ne garde que les items qui matchent une condition. S’il n’en reste aucun, la chaîne s’arrête proprement. Vous n’avez pas besoin d’un IF en amont pour vérifier « est-ce qu’il y a des items ? ».
• Le node Loop Over Items lui-même ne fait rien sur une entrée vide. S’il reçoit zéro item, il ne s’exécute pas et n’émet pas d’erreur. Là encore, inutile de le protéger par un garde-fou « au cas où la liste serait vide ».

Quand Loop Over Items est le bon outil

Le node existe pour de bonnes raisons, simplement pas celles qu’on imagine au début. Son vrai nom technique est Split in Batches, et il fait exactement ça : il découpe votre liste en paquets et vous les sert un par un, avec un rebouclage. Quatre situations le rendent indispensable.

1. Espacer les appels à une API qui rationne. C’est le cas numéro un. Beaucoup d’API refusent qu’on les cogne trop vite (60 requêtes par minute, par exemple). Si vous lâchez 500 items d’un coup sur un HTTP Request, vous vous faites jeter avec des erreurs 429 Too Many Requests. La parade : découper en lots de 20, traiter un lot, attendre quelques secondes, passer au suivant. Le node Loop Over Items est fait pour ce rythme.

2. Accumuler un état au fil des passages. Si vous devez construire un total, une liste consolidée ou un compteur qui grossit à chaque tour, il vous faut un endroit où le traitement d’un lot « voit » ce que les précédents ont produit. La boucle explicite donne cette structure.

3. Traiter des éléments dans un ordre imposé. Certaines opérations doivent se faire séquentiellement : créer un dossier avant d’y déposer des fichiers, insérer un client avant ses factures. Quand l’ordre compte et qu’une étape dépend de la précédente, la boucle cadre ce déroulé.

4. Isoler chaque lot dans un sous-workflow. Sur de gros volumes, on aime parfois envoyer chaque paquet vers un sous-workflow dédié, pour maîtriser la mémoire et repartir « propre » à chaque tour. Loop Over Items sert alors de distributeur.

Votre besoin	Loop Over Items ?
Traiter une liste d’items indépendants	Non — n8n itère déjà
Filtrer puis agir sur ce qui reste	Non — Filter suffit
Envoyer des appels par lots espacés (rate limit)	Oui
Accumuler un total / une liste au fil des tours	Oui
Respecter un ordre où B dépend de A	Oui
Découper un gros volume par paquets	Oui

Poser le node : batch size, rebouclage et l’output « done »

Une fois que vous avez une vraie raison de boucler, la mécanique est simple, à condition de comprendre le câblage, c’est là que la plupart des gens se perdent.

Vous posez le node Loop Over Items. Un seul réglage compte au départ : Batch Size (le nombre d’items servis à chaque tour). Par défaut il vaut 1, donc un item à la fois. Pour du batch d’API, montez-le à 10 ou 20 selon ce que l’API tolère.

Le node a deux sorties, et c’est le point qui déroute :

Sortie	Ce qu’elle contient	Où la brancher
loop	Le lot courant (un paquet d’items)	Vers le traitement (HTTP Request, etc.) puis retour au node
done	Rien à faire — tous les lots sont passés	Vers la suite du workflow (notification, résumé…)

Le câblage correct ressemble à ça : la sortie loop part vers vos nodes de traitement, et le dernier node de traitement revient se brancher sur le node Loop Over Items lui-même. C’est ce fil de retour qui crée la boucle. Le node distribue alors le lot suivant, et ainsi de suite. Quand il n’y a plus de lot, il bascule automatiquement sur la sortie done, vous n’avez rien à déclencher pour ça : il le fait seul.

Les pièges qui font tourner en rond

Quatre erreurs reviennent en boucle, sans mauvais jeu de mots. Les connaître vous épargne des heures de débogage.

Oublier le fil de retour. C’est l’erreur numéro un. Vous branchez la sortie loop vers votre HTTP Request, vous lancez… et un seul lot part, puis plus rien. La cause : le dernier node ne revient pas au node Loop Over Items. Sans ce fil de retour, il n’y a pas de boucle, juste un premier tour. Vérifiez toujours que la chaîne de traitement reboucle sur le node.

Ajouter un IF « y a-t-il des items ? » avant la boucle. On l’a vu plus haut : c’est inutile. Le node ne fait rien sur une entrée vide. Ce garde-fou n’ajoute que du bruit.

Confondre les deux modes du node Code. Si vous glissez un node Code dans votre boucle, il propose deux modes : Run Once for All Items (le code s’exécute une seule fois, quel que soit le nombre d’items) et Run Once for Each Item (le code s’exécute une fois par item). Choisir le mauvais mode donne des résultats déroutants : un traitement qui ne s’applique qu’à la première ligne, ou l’inverse. Pour agir item par item, c’est bien Run Once for Each Item qu’il faut.

Attendre du parallélisme. Loop Over Items traite les lots les uns après les autres, pas en même temps. C’est justement ce qui le rend précieux pour respecter un rythme ou un ordre. Mais si votre seul objectif est d’aller vite sur des items indépendants, la boucle vous ralentit pour rien : laissez n8n itérer nativement, c’est plus direct.

Un cas concret : enrichir 200 contacts sans se faire jeter

Imaginons que vous ayez 200 contacts dans un Google Sheets, et une API d’enrichissement qui plafonne à 60 requêtes par minute. Les envoyer tous d’un coup vous vaut un mur d’erreurs. Le bon montage tient en six nodes :

1. Schedule Trigger : le workflow tourne une fois par nuit, quand personne ne regarde.
2. Google Sheets (Get Rows) : il sort vos 200 contacts, soit 200 items.
3. Loop Over Items : Batch Size à 20. Il servira donc 10 paquets de 20.
4. HTTP Request : l’appel d’enrichissement. Grâce à l’exécution item-based, il part 20 fois par tour, un appel par contact du lot.
5. Wait : une pause de 30 secondes, pour rester sous la limite de l’API.
6. Retour au node Loop Over Items : ce fil relance la distribution du lot suivant.

Quand les 10 lots sont passés, le node bascule sur sa sortie done, et là vous branchez la suite : un node Slack qui poste « 200 contacts enrichis », ou un Set qui prépare un résumé. Le résultat : 200 appels étalés dans le temps, zéro erreur 429, et un workflow qui tient la charge sans surveillance.

Ici, la boucle ne sert pas à appeler l’API pour chaque contact : ça, n8n le fait seul. Elle sert à rythmer, à découper en lots et intercaler une pause. C’est sa seule raison d’être. Retirez la contrainte de rate limit, et vous pouvez la retirer avec.

Récap : le bon réflexe boucle

Si vous ne deviez retenir qu’une chose : n8n boucle déjà pour vous. La donnée circule en items, et la plupart des nodes s’exécutent une fois par item, sans câblage. Avant de chercher un node de boucle, posez directement le node qui fait le travail et regardez : il a probablement déjà tout traité.

Le node Loop Over Items (alias Split in Batches) n’entre en jeu que pour une vraie raison structurelle : espacer des appels vers une API qui rationne, accumuler un état au fil des tours, imposer un ordre, ou isoler de gros volumes par paquets. Réglez le Batch Size, branchez la sortie loop vers le traitement, rebouclez le dernier node sur le node lui-même, et laissez la sortie done prendre le relais à la fin.

Fuyez les trois réflexes qui alourdissent : le IF « y a-t-il des items ? » inutile devant Filter ou la boucle, le fil de retour oublié, et l’attente d’un parallélisme que le node ne fournit pas. Avec ça, vos workflows restent lisibles et font exactement ce que vous croyez qu’ils font.

C’est ce genre de modèle mental (comprendre comment n8n pense la donnée, pas juste empiler des nodes) que je déroule dans ma formation n8n. On part de zéro et on va jusqu’aux patterns que j’utilise en production chez mes clients, boucles comprises. Et tout ça marche à l’identique que vous soyez sur n8n Cloud ou en auto-hébergement : c’est du cœur de n8n, pas une option d’édition.

Sources : n8n Docs · Loop Over Items (Split in Batches), n8n Docs · Looping in n8n, n8n Docs · Item lists et data structure, n8n Docs · Code node.