n8n Loops
Three meanings of "loop" map to three mechanisms:
- "Run this node for every item." Default. Most nodes loop automatically, so do nothing.
- "Run this node once with all items, not once per item." The setting (single boolean).
- "Process items in explicit batches with control flow between iterations." The node (formerly ).
For paginated APIs, the HTTP Request node has built-in pagination. Almost always preferable to a hand-built page-counting loop.
The model: items are an array
Data flows between nodes as an array of items, each
{ json: {...}, binary?: {...} }
. 50 items = 50-entry array.
Default: a node runs once per item. An HTTP Request with 50 input items fires 50 requests and outputs 50 result items. This is the implicit loop most workflows rely on.
The input array is the loop. Control iteration by controlling the array.
Non-negotiable
whenever a node should fire once-per-run, not once-per-item. Includes any expression
aggregating across the dataset via
/
plus
/
/
(without it, the aggregate computes N times for N upstream items, often producing N duplicates downstream). Also includes single notifications, aggregate writes, summary messages.
Counter-case: combined with another node's
(a per-item lookup, e.g.,
$('Get Tags').all().filter(tag => $('Search Posts').item.json.tag_ids.includes(tag.json.id))
) is real per-item work and should keep
off. See the
skill's executeOnce section for the full distinction.
Strong defaults
- Don't build a loop when default iteration suffices. Most nodes (HTTP Request, native service nodes, Set, IF/Switch) run once per input item automatically: N items in, N runs. To make N HTTP calls or create N records, just connect the source to the node. Don't reach for unless you need per-iteration control. (Note: is the exception. It defaults to a single all-items batch. See for .)
- For paginated APIs, use HTTP Request's built-in pagination. Don't reinvent with + manual unless the API is genuinely odd. See
references/HTTP_PAGINATION.md
- is for explicit batching or per-iteration control (rate limiting, per-batch error recovery, stateful chunks, polling). See
references/LOOP_OVER_ITEMS.md
Decision tree: which mechanism do I need?
Need to do something for each item?
├── Default per-item iteration is enough
│ └── Just connect the node. Done.
│
├── The node should run once total, not once per item?
│ └── Set executeOnce: true on the node
│
├── Paginated API (multiple HTTP calls to fetch all pages)?
│ └── Use HTTP Request's Pagination option (see references/HTTP_PAGINATION.md)
│
├── Need explicit batching (rate limit, chunk size, per-batch error handling)?
│ └── Use Loop Over Items node (see references/LOOP_OVER_ITEMS.md)
│
└── Need to recurse / repeat with state until a condition is met?
└── Loop Over Items with Reset, OR a sub-workflow that calls itself.
Both are advanced patterns; see references/LOOP_OVER_ITEMS.md.
: the single-fire setting
Every node's Settings tab has an Execute Once toggle. When on, the node runs once using only the first input item.
ts
{
name: 'Aggregate Slack',
type: 'n8n-nodes-base.slack',
parameters: { /* ... */ },
executeOnce: true,
}
When to use it:
- Notifications and aggregate writes. A "summary message" shouldn't fire 100 times because 100 items came in.
- Counters, totals, reports. Anything computing etc. should run once.
- Expressions aggregating across the full array via / . Otherwise the aggregate runs per upstream item. (Per-item lookups using filtered by another node's are the counter-case, see .)
When NOT to use it:
- Per-item operations. One notification per item is the default and usually correct.
- HTTP requests fanning out per item. You want one call per item.
Most common mistake: forgetting
on an aggregate node, then seeing the same message fire 50 times after a fan-out.
When the implicit loop bites you
Default per-item iteration is great until it isn't. Common surprises:
A "single" config node fires per item
A
node after a fan-out runs once per item, producing N copies of the same constants. Usually fine, but expensive expressions (long
, Luxon parse) run N times. Move the Set above the fan-out, or set
.
An aggregate Code node runs N times
A Code node reading
to compute a sum runs once per upstream item without
, producing N identical items. Set
.
A respond-to-webhook fires twice
Most painful version. Respond-to-Webhook fires per input item, and two branches converging without a merge fire it twice: first response wins, the rest log errors. Merge first, or ensure only one branch reaches the responder. See
.
An LLM call fires N times when you wanted one summary
Same shape as the aggregate Code node. An LLM node with
in its prompt makes N identical calls, costs N tokens, returns N identical answers without
.
When to reach for
Default iteration handles most cases. Use
for:
- Rate limiting. "Process 10 at a time, 1s wait between batches."
- Batched API calls with array bodies. "Send 50-item chunks to /bulk."
- Per-batch error handling. "If a batch fails, log and continue."
- Stateful iteration. "Each iteration depends on the previous output."
- Polling a long-running job. "Start, check status every 30s until done or capped." Uses plus a ceiling.
- Per-item multi-branch with aggregation. "For each input, run transforms in parallel, merge, then aggregate." The done output (index 0) carries the result.
For wiring details, the output-index gotcha (output 0 =
done, output 1 =
loop), and worked examples, see
references/LOOP_OVER_ITEMS.md
.
When NOT to reach for
The most common rationalization: "I need to wait for all items to finish before the next step, so I'll add Loop Over Items and use the
output."
You don't need Loop Over Items for that. Default per-item iteration already waits: each item flows through the full downstream chain before the next item starts, and the post-loop node never fires "early."
The cure for that mistake is almost always: delete the Loop Over Items node, change nothing else, ship. That is Scenario 1 below, and it covers the majority of cases.
The four scenarios are independent. Read them as separate decisions, not as alternatives that all "replace" Loop Over Items. Most builds hit Scenario 1 and are done. Scenarios 2 and 3 only enter the picture when their specific goal applies. Scenario 4 is the narrow case where Loop Over Items actually earns its place.
Scenario 1: default per-item iteration (the default, most common)
Source emits N items, per-item processor runs N times, downstream chain follows.
No Loop Over Items, no , no Aggregate. Just connect the nodes.
[Source: 20 items]
→ [Per-item processor] # default iter, runs 20 times
→ [Next step] # runs after each item, in order
If a
was added here "to wait for all items" or "to make the next node run for each item," delete the Loop Over Items node and wire source straight to processor.
Do not replace it with anything. Default iteration already does the job. The exception is
(sub-workflow): it defaults to a single all-items batch, so per-item invocation needs
on that node, not a Loop. See
.
Scenario 2: a downstream node should fire once total ()
Independent of Scenario 1. Triggered only when there is a SPECIFIC downstream node whose job is once-per-run, not once-per-item: one digest email after 20 papers process, one summary write after the loop, one final Slack notification.
Set
on that node. The node receives all upstream items but runs once. This is a per-node setting, not a Loop replacement: the per-item processor in Scenario 1 still runs N times, and only this one downstream node collapses.
Scenario 3: a node needs the items as a single array (Aggregate)
Independent of Scenario 1. Triggered only when a downstream node's input contract is a list, not per-item invocations (e.g., a node taking a JSON array body, an LLM prompt that needs the whole list).
Use the Aggregate node to collapse the per-item stream into one item containing the array. Again, not a Loop replacement.
Scenario 4: genuine batching (the only time Loop Over Items earns its place)
Rate limiting (process N at a time with a Wait between batches), chunked bulk API calls (POST 50-item arrays to
), per-batch error handling, polling a long-running job with
and a
ceiling, stateful iteration where each batch depends on the previous output.
"Wait for items to finish" does not qualify. Default iteration already does that.
Quick disambiguation
If your only reason for the Loop is "wait for items / run for each item," you are in Scenario 1. Delete the Loop. Do not add
or Aggregate as a substitute. They solve different problems and are only added when their own scenario applies.
When to reach for HTTP pagination
Three common page shapes:
- Next-URL in response. Each response includes a link.
- Page number/cursor parameter. Bump or each call.
- Stop on empty page or specific status.
HTTP Request handles all natively via its Pagination option: set the mode, give a next-page expression, and the node loops internally, returning a single output array of all pages' items.
Don't reinvent with
+ manual
unless the API does something the built-in modes can't express.
See
references/HTTP_PAGINATION.md
.
Sub-workflow recursion
For genuinely recursive work (tree walking, retry-with-backoff, "process this and its children"), a self-calling sub-workflow is cleaner than
with
. Input parameters carry recursion state.
Sub-workflow: Walk Tree
inputs: { node_id, depth }
body: process node, look up children, for each child call self with depth+1
Watch recursion depth. n8n has nested-execution limits. For deep recursion, a queue + flat loop beats true recursion.
Reference files
| File | Read when |
|---|
references/LOOP_OVER_ITEMS.md
| Configuring the Loop Over Items node, batching, rate limiting, stateful iteration |
references/HTTP_PAGINATION.md
| Calling a paginated API, configuring HTTP Request pagination modes |
Anti-patterns
| Anti-pattern | What goes wrong | Fix |
|---|
| Adding to "make it loop" when default iteration already does | Workflow harder to read for no benefit, and loop output vs done output gets miswired | Just connect the node directly and let default iteration handle it |
| Aggregate Code node without | Same aggregate computed N times, output has N identical items | Set |
| Manual pagination loop with + | Reinvents what HTTP Request does natively, with brittle stop conditions | Use HTTP Request's option |
| Sending one Slack message per item when you wanted a summary | Slack channel floods, rate limits hit, embarrassment | on the Slack node, build the summary upstream |
| Two branches both reach | Responds twice, downstream callers see errors | Merge before the responder, or ensure only one branch reaches it |
| with and no clear termination | Infinite loop, n8n eats memory until the execution is killed | Always have a clear termination condition. Prefer HTTP pagination for paged APIs |
| Nesting one inside another in the same workflow | Broken at runtime, validation passes | Move the inner loop into a sub-workflow called per outer iteration. See |