Loop Node

The Loop node takes any array from an upstream node and runs the connected downstream subgraph once for each item. Each iteration receives the current item plus loop metadata — index, total count, and whether it is the last item. Pair it with an Aggregator node at the end of the body to collect all results into a single output.

How It Works

Connect an array-producing node (Price Data, Function, LLM, etc.) to the Loop's items input. Connect downstream processing nodes to the Loop's item output — those nodes form the loop body and run once per item. Place an Aggregator at the end of the body to collect results.

The execution engine automatically detects Loop → body → Aggregator patterns. Body nodes are executed inside the loop and not in the main workflow flow — only the Aggregator emits output that downstream nodes can use.

What Each Iteration Receives

Every node in the loop body receives the following fields injected by the Loop node:

Reference these in downstream nodes as {item}, {index}, {total}, {isLast}.

Configuration

Input Array Path

The field is an expression-only input — always wrap the path in {...}:

The autocomplete popup (triggered by typing {) lists available paths from connected upstream nodes.

Workflow Variables

You can point the Loop at a workflow variable that holds an array. Set the Input array path to {workflow.myVariable} or {global.myVariable}:

{workflow.symbols}    → iterates over the "symbols" workflow variable
{global.watchlist}    → iterates over the "watchlist" global variable

This is useful when the list of items is configured at the workflow level and changes between runs.

External Dependencies in the Loop Body

Loop body nodes can receive data from outside the loop body — for example, a Stocks Data node that runs in parallel and feeds into a Function node inside the body. The execution engine automatically waits for all such external inputs to be ready before starting loop iterations.

In the diagram above, Stocks Data runs concurrently with the Loop setup phase. The engine delays loop body execution until the Stocks Data output is available.

Nesting Loops

You can place a Loop node inside another loop body to process nested data structures — for example, iterating over a list of symbols and then over each symbol's candles.

Nesting rules

• Maximum depth: loops can be nested up to 2 levels deep. A Loop node inside an outer loop body is the maximum allowed.
• The builder enforces this limit: the Loop option in the node picker is disabled when the source node is already at nesting level 2, and manually connecting a Loop node to a level-2 body is blocked with an explanatory message.
• Exceeding the limit is also caught during workflow validation before execution.

Each level has its own Aggregator that collects that level's results before passing them back to the outer loop.

Error Handling and Retry

By default, any error inside a loop iteration halts the entire loop. To process best-effort:

1. Enable Continue on error — failed iterations are logged with success: false in the Aggregator's output.
2. Set Max retries — the engine retries the full iteration body before considering it failed.

Retry attempts are included in the retryAttempts field of each iteration record visible in the Aggregator output.

Use Case: Process Price Candles

Fetch OHLCV candles from Price Data, loop over each candle, compute a signal in a Function node, and collect all signals in an Aggregator.

Loop config:

• Input array path: {price_data.data.prices[0].candles}
• Continue on error: off

Function node (in body) — accesses the current candle as {item}:

candle = inputs['item']
signal = 'buy' if candle['close'] > candle['open'] else 'sell'
return { 'signal': signal, 'close': candle['close'] }

Aggregator → outputs results[] with one signal per candle.

Use Case: Fan-Out LLM Analysis

Iterate over a list of symbols from a workflow variable, run an LLM analysis for each, and collect the outputs.

Loop config:

• Input array path: {workflow.symbols}
• Continue on error: on (skip symbols the LLM fails on)
• Max retries: 2

The LLM node in the body references {item} as the current symbol. The Aggregator collects all responses.

Output

The Loop node's own output (visible from the Loop node ID in subsequent non-body nodes) includes:

The primary output consumers are the body nodes and the Aggregator. Downstream nodes after the Aggregator reference {aggregator.results}, {aggregator.total}, etc.

Next Steps

• Aggregator Node — Collect and merge all loop iteration results.
• Function Node — Write per-iteration processing logic.
• Conditional Node — Branch inside the loop body.
• LLM Node — Run AI analysis on each item.
• Price Data Node — Fetch arrays of candles or prices to iterate over.