Boucles dans n8n : maîtriser Loop Over Items (Split in Batches)

« Comment faire une boucle dans n8n ? » est probablement la question la plus posée par ceux qui arrivent d'un langage de programmation classique — et la réponse surprend : dans la majorité des cas, il n'y a rien à faire. n8n itère nativement sur les items, et le réflexe d'ajouter une boucle explicite partout produit des workflows plus lents et plus fragiles. Reste une famille de cas où une vraie boucle s'impose, et là, un seul node compte : Loop Over Items (anciennement Split in Batches). Ce guide couvre quand l'utiliser, comment le câbler sans tomber dans les pièges classiques, et quelles alternatives envisager quand il montre ses limites.

Le piège n°1 des débutants : n8n boucle déjà tout seul

Dans n8n, les données circulent sous forme de liste d'items, et presque tous les nodes s'exécutent automatiquement une fois par item reçu en entrée. Un node qui renvoie 50 contacts, suivi d'un node Set qui reformate les champs, puis d'un node HTTP Request qui appelle une API : les trois étapes traitent les 50 contacts sans qu'aucune boucle ne soit déclarée. C'est le modèle d'exécution par défaut de n8n, l'équivalent implicite d'un for each sur chaque node.

Conséquence directe : entourer chaque traitement d'un Loop Over Items avec un Batch Size de 1 « pour être sûr » est non seulement inutile, mais contre-productif — chaque itération ajoute de la surcharge d'exécution, et le workflow devient illisible. Avant d'ajouter une boucle, posez-vous la question : est-ce que le node suivant ne fait pas déjà le travail item par item ? Dans neuf cas sur dix, la réponse est oui.

Quand une vraie boucle s'impose

Il reste des situations où l'itération native ne suffit pas, parce que le besoin ne porte pas sur chaque item mais sur le rythme ou le regroupement du traitement :

• Traiter par lots : envoyer 500 lignes à un modèle IA par paquets de 20 pour construire des prompts groupés, ou insérer en base par blocs plutôt qu'en 500 requêtes unitaires.
• Insérer une pause entre les lots : une API à quota serré (typiquement une API IA) refuse les rafales ; il faut espacer les appels, ce que l'itération native ne permet pas.
• Appeler une API paginée avec une logique que l'option native du node HTTP Request ne couvre pas — le schéma détaillé dans notre guide sur la pagination API dans n8n.
• Traiter séquentiellement quand l'ordre compte : chaque étape dépend du résultat de la précédente (numérotation, solde courant, écriture ordonnée dans un document).

Si votre besoin ne rentre dans aucune de ces cases, l'itération native fera l'affaire — éventuellement combinée à un node Merge pour recombiner des branches.

Le node Loop Over Items : Batch Size, loop et done

Le node s'appelle Loop Over Items dans les versions récentes de n8n (vous croiserez encore son ancien nom, Split in Batches, dans beaucoup de tutoriels et de workflows partagés — c'est le même node). Son fonctionnement tient en trois éléments :

• Batch Size : le nombre d'items émis à chaque itération. 1 pour un traitement strictement séquentiel item par item, 10 ou 20 pour des lots.
• La sortie « loop » : émet le lot courant. C'est ici que se branche le traitement à répéter — et le dernier node de ce traitement doit être reconnecté à l'entrée de Loop Over Items pour déclencher l'itération suivante.
• La sortie « done » : ne s'active qu'une fois tous les lots consommés, et émet alors l'ensemble des items passés par la boucle. C'est ici que se branche la suite du workflow.

Le câblage typique ressemble donc à :

Source (500 items)
  → Loop Over Items (Batch Size: 20)
      ├─ loop → OpenAI → Set → (retour vers Loop Over Items)
      └─ done → Google Sheets (écrit les 500 résultats)

L'erreur classique — responsable d'une bonne partie des « ma boucle ne marche pas » sur les forums — est de brancher la suite du workflow sur la mauvaise sortie : sur loop, la suite s'exécute à chaque itération avec un lot partiel ; et si rien ne revient vers l'entrée du node, la boucle s'arrête après le premier lot sans jamais activer done. Retenez la règle : le traitement répété part de loop et y revient ; tout ce qui vient après la boucle part de done.

Ajouter un Wait dans la boucle pour respecter un rate limit

Le cas d'usage le plus fréquent en 2026 : appeler un modèle IA sur des centaines d'items sans déclencher d'erreurs 429. La solution tient en un node Wait placé à l'intérieur de la boucle, juste avant le retour vers Loop Over Items :

Loop Over Items (Batch Size: 10)
  ├─ loop → OpenAI (10 appels) → Wait (Amount: 5, Unit: Seconds) → retour boucle
  └─ done → suite du workflow

Chaque lot de 10 appels est ainsi suivi d'une pause de quelques secondes, ce qui étale la charge et maintient le débit sous le quota de l'API. La bonne valeur dépend de la limite réelle de votre fournisseur — consultez sa documentation plutôt que de deviner, et combinez la pause avec les stratégies de backoff décrites dans notre guide sur les rate limits des API IA. Pour les erreurs résiduelles, un retry bien configuré sur le node HTTP Request complète le dispositif.

Récupérer les résultats après la boucle

Point rassurant pour ceux qui cherchent où « accumuler » leurs résultats : il n'y a rien à faire. La sortie done émet tous les items qui ont traversé la boucle, avec les champs ajoutés ou modifiés à chaque itération. Un node Google Sheets, Postgres ou Slack branché sur done reçoit donc la liste complète des 500 items enrichis, en une seule fois. Si vous avez besoin d'une agrégation (compter, sommer, regrouper), un node Code ou Aggregate placé après done travaille sur l'ensemble.

Débit, lots et temps total : l'intuition de la loi de Little

Ralentir une boucle pour rester sous un rate limit a un coût mécanique : le temps total s'allonge. Ce n'est pas un défaut de n8n, c'est un arbitrage débit/latence formalisé de longue date par la théorie des files d'attente. Le résultat fondateur est la loi de Little, démontrée par John D. C. Little dans « A Proof for the Queuing Formula: L = λW » (Operations Research, 1961 — voir sur Google Scholar) : le nombre de travaux en cours dans un système est le produit du débit par le temps moyen passé dans le système. Traduction pour vos workflows : à volume donné, si vous divisez le débit par deux (pause plus longue, lots plus petits), le temps de traversée double. Inutile donc de chercher un réglage magique — choisissez le débit maximal que l'API tolère, et acceptez le temps total qui en découle, ou parallélisez (voir ci-dessous).

Les alternatives à Loop Over Items

Trois options couvrent les cas où le node atteint ses limites :

• Un sub-workflow appelé par lot : la boucle appelle un workflow enfant via Execute Sub-workflow, qui traite un lot et rend la main. Chaque lot s'exécute dans un contexte isolé — mémoire libérée entre les lots, logique réutilisable et testable séparément. C'est le schéma détaillé dans notre guide des sub-workflows n8n.
• Le node Code pour boucler en JavaScript : un for ou un reduce dans un node Code traite des milliers d'items en une seule exécution de node, sans la surcharge d'itérations visuelles — idéal pour des transformations pures, sans appel externe. Voir notre guide des expressions et du node Code.
• Le mode queue pour paralléliser à grande échelle : quand le volume dépasse ce qu'une exécution séquentielle peut absorber, distribuer le travail sur plusieurs workers via le mode queue de n8n avec Redis remplace avantageusement une boucle géante.

Pièges à éviter

• La boucle infinie : si un IF à l'intérieur de la boucle détourne certains items sans jamais les ramener vers Loop Over Items, ou si la suite est branchée sur loop au lieu de done, l'exécution tourne sans fin ou s'arrête à mi-course. Testez toujours avec un petit jeu de données (5 à 10 items) avant de lancer le volume réel.
• La mémoire sur de très gros volumes : tous les items de la boucle restent en mémoire jusqu'à la sortie done. Sur des dizaines de milliers d'items enrichis de gros payloads, l'exécution peut ralentir fortement, voire échouer. Écrivez au fil de l'eau (insertion en base à chaque lot, dans la branche loop) plutôt que d'attendre done, ou basculez sur le schéma sub-workflow.
• Le Batch Size de 1 par défaut : séquentiel strict = temps total maximal. Ne le choisissez que si l'ordre ou l'isolation l'exige vraiment ; sinon, un lot de 10 ou 20 divise d'autant le nombre d'itérations.

Pour aller plus loin

Loop Over Items est un node simple une fois qu'on a intégré ses deux règles : n8n itère déjà nativement (la boucle explicite est l'exception, pas la norme), et le traitement répété part de loop pour y revenir, tandis que la suite du workflow vit sur done. Les workflows n8n prêts à l'emploi de FlowKit appliquent ces schémas partout où un traitement par lots ou un rate limit l'exige — boucle bornée, Wait calibré, écriture au fil de l'eau — pour vous éviter de redécouvrir ces pièges un lundi matin en production.