n8n Loop Over Items: Batching und automatisches Looping

n8n durchläuft mehrere Datensätze von selbst. Ein Node nimmt eine Liste von Items entgegen und führt seine Logik für jedes Item aus. Die Ergebnisse gibt er wieder als Liste zurück. Für die meisten Workflows brauchen Sie deshalb keine explizite Schleife.

Manchmal reicht das nicht. Eine API erlaubt nur wenige Anfragen pro Sekunde. Ein Node verarbeitet nur das erste Item. Eine paginierte Schnittstelle liefert eine unbekannte Zahl an Seiten. Für diese Fälle gibt es den Loop Over Items Node, früher Split in Batches.

Dieser Artikel zeigt, wie das automatische Looping funktioniert und wie der Node im Detail arbeitet. Er zeigt außerdem, wie Sie Batch-Größe und Wartezeiten gegen Rate-Limit-Fehler setzen.

Wie durchläuft n8n Items automatisch?

n8n führt jeden Node standardmäßig einmal pro eingehendem Item aus. Laut der Dokumentation zum Looping verarbeiten Nodes eine beliebige Anzahl an Items und geben die Ergebnisse wieder aus.

Verbinden Sie einen Datenspeicher-Node mit fünf Kundendatensätzen mit einem Slack-Node, verschickt n8n fünf einzelne Nachrichten. Eine eigene Schleife müssen Sie dafür nicht bauen.

Wollen Sie nur das erste Item verarbeiten, aktivieren Sie im Reiter Settings des Nodes die Option Execute Once. Der Node ignoriert dann alle weiteren Items. Das eignet sich für einmalige Benachrichtigungen am Ende eines Laufs.

Was macht der Loop Over Items Node genau?

Der Loop Over Items Node speichert die eingehenden Daten und gibt pro Durchlauf eine festgelegte Menge an Items aus. Sind alle Batches abgearbeitet, kombiniert er die Ergebnisse und gibt sie über den zweiten Ausgang aus.

Wichtig für den Aufbau: Der Node hat zwei Ausgänge in einer bestimmten Reihenfolge.

Element | Wert | Bedeutung

Element: Ausgang done · Wert: 0 · Bedeutung: liefert die gesammelten Ergebnisse, sobald keine Items mehr übrig sind

Element: Ausgang loop · Wert: 1 · Bedeutung: liefert bei jedem Durchlauf den nächsten Batch

Element: Parameter Batch Size · Wert: Zahl · Bedeutung: Anzahl der Items je Durchlauf, bei 1 wird jedes Item einzeln verarbeitet

Element: Option Reset · Wert: true/false · Bedeutung: initialisiert den Node bei jedem Durchlauf neu mit den eingehenden Daten

Reset brauchen Sie bei paginierten Abfragen, deren Seitenzahl Sie vorher nicht kennen. Die Dokumentation weist ausdrücklich darauf hin: Bei aktiviertem Reset ist eine gültige Abbruchbedingung Pflicht, sonst läuft die Schleife endlos.

Für die Abbruchbedingung stellt der Node zwei Kontextwerte bereit. {{$("Loop Over Items").context["noItemsLeft"]}} gibt zurück, ob noch Items übrig sind. {{$("Loop Over Items").context["currentRunIndex"]}} liefert den Index des aktuellen Durchlaufs. Beide werten Sie in einer IF-Node aus.

Wie sieht ein Loop-Workflow mit Wartezeit aus?

Ein stabiler Loop besteht aus vier Bausteinen: Loop Over Items, dem eigentlichen Aufruf, einem Wait-Node und der Rückverbindung. Der folgende Ausschnitt lässt sich über „Import from File" direkt in n8n einfügen.

1{
2  "name": "Loop Over Items mit Wartezeit",
3  "nodes": [
4    {
5      "parameters": {},
6      "name": "When clicking 'Execute workflow'",
7      "type": "n8n-nodes-base.manualTrigger",
8      "typeVersion": 1,
9      "position": [-220, 0]
10    },
11    {
12      "parameters": {
13        "batchSize": 5,
14        "options": {}
15      },
16      "name": "Loop Over Items",
17      "type": "n8n-nodes-base.splitInBatches",
18      "typeVersion": 3,
19      "position": [0, 0]
20    },
21    {
22      "parameters": {
23        "url": "https://api.beispiel.de/v1/kontakte",
24        "options": {}
25      },
26      "name": "HTTP Request",
27      "type": "n8n-nodes-base.httpRequest",
28      "typeVersion": 4.2,
29      "position": [240, 120]
30    },
31    {
32      "parameters": {
33        "amount": 2,
34        "unit": "seconds"
35      },
36      "name": "Wait",
37      "type": "n8n-nodes-base.wait",
38      "typeVersion": 1.1,
39      "position": [460, 120]
40    },
41    {
42      "parameters": {},
43      "name": "Fertig",
44      "type": "n8n-nodes-base.noOp",
45      "typeVersion": 1,
46      "position": [240, -120]
47    }
48  ],
49  "connections": {
50    "When clicking 'Execute workflow'": {
51      "main": [[{ "node": "Loop Over Items", "type": "main", "index": 0 }]]
52    },
53    "Loop Over Items": {
54      "main": [
55        [{ "node": "Fertig", "type": "main", "index": 0 }],
56        [{ "node": "HTTP Request", "type": "main", "index": 0 }]
57      ]
58    },
59    "HTTP Request": {
60      "main": [[{ "node": "Wait", "type": "main", "index": 0 }]]
61    },
62    "Wait": {
63      "main": [[{ "node": "Loop Over Items", "type": "main", "index": 0 }]]
64    }
65  }
66}
Copy

Beachten Sie die Reihenfolge im Feld connections: Das erste Array unter Loop Over Items ist der done-Zweig, das zweite der loop-Zweig. Vertauschen Sie beide, läuft der Workflow genau einmal durch.

Der Wait-Node pausiert hier zwei Sekunden pro Batch. Seine Einheit stellen Sie über Wait Unit auf Seconds, Minutes, Hours oder Days.

Welche Nodes brauchen eine manuelle Schleife?

Einige Nodes verarbeiten grundsätzlich nur das erste Item oder alle Items auf einmal. Die Dokumentation nennt diese Ausnahmen namentlich.

Node | Betroffene Operation

Node: CrateDB, MongoDB, TimescaleDB · Betroffene Operation: Insert, Update

Node: Microsoft SQL · Betroffene Operation: Insert, Update, Delete

Node: QuestDB · Betroffene Operation: Insert

Node: Code · Betroffene Operation: Modus „Run Once for All Items"

Node: Execute Workflow · Betroffene Operation: Modus „Run Once for All Items"

Node: HTTP Request · Betroffene Operation: manuelle Paginierung

Node: Redis · Betroffene Operation: Operation Info

Node: RSS Read · Betroffene Operation: läuft einmal je angeforderter URL

In diesen Fällen bauen Sie die Schleife selbst. Entweder setzen Sie Loop Over Items mit Batch Size 1 davor. Oder Sie verbinden den Ausgang eines Nodes zurück auf einen früheren Node. Die Abbruchbedingung prüfen Sie dann in einer IF-Node.

Welche Batch-Größe ist die richtige?

Die richtige Batch-Größe ergibt sich aus dem Rate-Limit des Zieldienstes, nicht aus einem allgemeinen Richtwert. Die folgende Übersicht zeigt die Kompromisse.

Batch Size | Vorteil | Nachteil | Sinnvoll bei

Batch Size: 1 · Vorteil: jedes Item einzeln nachvollziehbar, sanfteste Last · Nachteil: längste Laufzeit, viele Durchläufe · Sinnvoll bei: Nodes ohne automatische Iteration, sehr strenge Limits

Batch Size: 5 bis 20 · Vorteil: guter Kompromiss aus Tempo und Schonung · Nachteil: Fehler betrifft mehrere Items zugleich · Sinnvoll bei: typische REST-APIs mit Limits pro Minute

Batch Size: über 50 · Vorteil: wenige Durchläufe, kurze Gesamtlaufzeit · Nachteil: hohes Risiko für HTTP 429, unübersichtliche Fehler · Sinnvoll bei: interne Dienste ohne Limit, reine Datenbankschreibvorgänge

Für reine HTTP-Aufrufe brauchen Sie oft gar keinen eigenen Loop. Der HTTP-Request-Node bringt laut Dokumentation zu Rate Limits unter Add Option > Batching die Felder Items per Batch und Batch Interval (ms) mit. Das ersetzt Loop Over Items und Wait in einem Node.

Typische Fehler und Ursachen

Der Workflow läuft nur einen einzigen Durchlauf.

Ursache: Der Folge-Node hängt am Ausgang done statt am Ausgang loop. Lösung: Die Verarbeitung an den unteren Ausgang loop hängen und deren Ende auf den Loop Over Items Node zurückführen. Quelle: Loop Over Items Node.

Die Schleife läuft endlos weiter.

Ursache: Die Option Reset ist aktiv, aber es gibt keine Abbruchbedingung. Lösung: Eine IF-Node einbauen, die {{$("Loop Over Items").context["noItemsLeft"]}} prüft und den Workflow beendet. Quelle: Loop Over Items Node.

Der Dienst antwortet mit HTTP 429.

Ursache: Die Anfragen kommen schneller, als das Limit erlaubt. Lösung: Batch Size senken, einen Wait-Node in den loop-Zweig setzen oder im Node unter Settings „Retry On Fail" mit passendem „Wait Between Tries (ms)" aktivieren. Quelle: API-Rate-Limits.

Nur der erste Datensatz landet in der Datenbank.

Ursache: Der verwendete Node gehört zu den Ausnahmen ohne automatische Iteration, etwa Microsoft SQL bei Insert. Lösung: Loop Over Items mit Batch Size 1 davorsetzen. Quelle: Looping in n8n.

Der Code-Node verarbeitet die Items nicht einzeln.

Ursache: Der Node steht im Modus „Run Once for All Items" und bekommt alle Items als ein Bündel. Lösung: Auf „Run Once for Each Item" umstellen oder die Iteration im Code selbst schreiben. Quelle: Code Node.

Sie wollen n8n-Workflows nicht nur bauen, sondern dauerhaft stabil betreiben? Bei genau solchen Performance- und Rate-Limit-Fragen unterstützen wir Sie im Rahmen unserer n8n-Automatisierung.

Häufige Fragen

Was ist der Unterschied zwischen automatischem Looping und dem Loop Over Items Node?

Automatisches Looping passiert bei fast jedem Node von selbst. Der Node verarbeitet jedes eingehende Item und gibt die Ergebnisliste weiter. Loop Over Items brauchen Sie erst, wenn Sie die Verarbeitung in kontrollierte Häppchen aufteilen wollen, etwa wegen Rate-Limits.

Wie verhindere ich eine Endlosschleife beim Loop Over Items Node?

Eine Endlosschleife entsteht meist bei aktivierter Reset-Option ohne Abbruchbedingung. Bauen Sie eine IF-Node ein, die {{$("Loop Over Items").context["noItemsLeft"]}} auswertet. Leiten Sie den Workflow am Ende in den done-Zweig statt zurück in die Schleife.

Welche Batch-Größe sollte ich für API-Anfragen wählen?

Eine pauschale Zahl gibt es nicht, weil jeder Dienst eigene Rate-Limits hat. Starten Sie mit Werten zwischen 1 und 10 Items pro Batch. Passen Sie den Wert dann anhand der Antwortzeiten und der Fehlermeldungen des Zieldienstes an.

Muss ich bei jedem Node selbst eine Schleife bauen?

Nein. Die meisten Nodes verarbeiten mehrere Items ohne zusätzliche Konfiguration. Nur die oben genannten Ausnahmen brauchen Loop Over Items oder eine rückverbundene IF-Node.

Kann ich innerhalb einer Schleife auf Daten aus vorherigen Durchläufen zugreifen?

Ja. Über currentRunIndex identifizieren Sie den aktuellen Durchlauf, über Referenzen auf frühere Nodes greifen Sie auf deren Daten zu. Für Zwischenergebnisse über mehrere Durchläufe hinweg sammeln Sie die Daten zusätzlich in einem Code-Node.