Skip to main content
The Loop node is a container. Drop nodes inside it and they run once for every item in an array you resolve from upstream; nodes outside the loop run once, as usual. Reach for it when an extracted document yields a variable-length list (line items, attachments, contacts) and you need to act on each entry.

​
How it works

  • Drag nodes inside the Loop to make them its body. The body runs once per item, in array order.
  • Inside the body, reference the current item with {{loop.payload.item}} and its position with {{loop.payload.index}} (0-based), where loop is the loop node’s name.
  • The whole loop runs as a single sub-run, not one run per item. Open it from the run detail and use the item pager to step through each item’s output.
  • Items are processed one at a time, in array order.
Atomic failure. If any item fails, the loop stops immediately and the step fails, so the remaining items do not run. A loop’s Store writes are held until every item succeeds and are committed only then, so a failed loop (or one interrupted by a worker restart) persists nothing to the Store.

​
What can go inside

A loop body may only contain these node types:
  • Transform
  • Validation
  • Store
  • Variable
Extract, Review, Route, Classify, HTTP, the output nodes (Email, Forward, Download, Callback Output), Reconcile, Merge, and nested Loops are not allowed inside a loop. Place those before or after the loop instead. HTTP and Callback Output are excluded because a stopped or retried loop could re-fire a per-item external request that has no idempotency key. Do that work after the loop, or use a batch endpoint.

​
Connecting nodes

  • Connect the node that produces the array to the Loop (an edge into the loop node).
  • Connect downstream nodes from the Loop, not from a node inside it. Edges may not cross the loop boundary.
  • The Loop’s own outgoing connection is optional. Because the body does the per-item work, a Loop may end a branch (like a Store node in Set mode). Its source handle stays, so you can still wire it onward to downstream nodes when you need results after the loop.
  • Wire body nodes to each other inside the loop as normal. For a given item, each body node can read the previous body node’s output for that same item.

​
Referencing items

Inside the body, per item:
  • {{loop.payload.item}} for the current item
  • {{loop.payload.index}} for its 0-based position
  • {{loop.metadata.itemCount}} for the total number of items
After the loop, from downstream nodes:
  • {{loop.payload.results}} for the full resolved array
  • {{loop.metadata.itemCount}} for the count
(Replace loop with your loop node’s actual name.)

​
Configuration

FieldDescription
SourceA template expression that resolves to an array, for example {{extract.payload.lineItems}} or {{aggregator.payload.items}}.
Sequential executionCurrently has no effect: a loop always processes its items one at a time, in array order.

​
Limits

A single loop may iterate over at most 500 items. A larger source array fails the step with a clear error rather than attempting it. Filter or page the array upstream so the loop runs over fewer items.

​
Errors

  • Source expression is required: the Source field is empty.
  • Source expression resolved to a non-array value: the expression resolved to something other than a JSON array (an object, a string, and so on). Check the upstream output and the path you reference.
  • Loop has no body nodes: the loop is empty. Drag at least one node inside it.
  • A node cannot be inside a Loop: a body node is of a type the loop does not allow (see What can go inside).
  • An edge crosses the loop boundary: a node inside the loop is connected directly to one outside it. Connect to the Loop itself instead.
  • The item count exceeds the maximum: the run fails with “Loop … resolved N items, which exceeds the maximum of 500. Reduce the source array (for example filter or page it) so the loop runs over fewer items.”