Loop

The Loop block is a container that executes the blocks inside it repeatedly. It is not a regular block with its own source file -- it is a special wrapper node managed by the executor's LoopBlockHandler. Drag blocks into the loop container and they will run once per iteration.

Loop blocks are container nodes. Drag other blocks inside them on the canvas to define what runs each iteration.

Loop Types

For Loop -- runs a fixed number of times. The default iteration count is 5 if not specified.

Example: Run 3 times
- Iteration 1 (index 0)
- Iteration 2 (index 1)
- Iteration 3 (index 2)

ForEach Loop -- iterates over each item in an array or object. The collection must be non-empty; an empty collection throws an error.

Example: Process ["apple", "banana", "orange"]
- Iteration 1: currentItem = "apple"
- Iteration 2: currentItem = "banana"
- Iteration 3: currentItem = "orange"

For objects, each iteration receives a [key, value] pair.

While Loop -- evaluates a condition before each iteration. If the condition is false on the first check, the body never executes.

While and Do-While loops have no built-in iteration cap. They rely on the condition becoming false (or the workflow timeout) to stop.

Do-While Loop -- executes the body at least once, then evaluates the condition after each iteration. Useful when you need at least one pass before checking.

How It Works

The executor's LoopBlockHandler manages iteration control:

Initialize -- the loop counter starts at 1. For forEach loops, the collection is resolved (JSON, variable references, or expressions).
Check continuation -- for/forEach compare the counter against the collection length or iteration count. while/doWhile evaluate the condition expression using the same engine as the Condition block.
Activate children -- blocks connected to the loop's internal start handle are placed on the active execution path.
Collect results -- each iteration's outputs are aggregated into loop.results.
Increment and repeat -- the counter advances and step 2 runs again. When the loop finishes, blocks connected to the loop's exit handle are activated.

Iteration Variables

Inside the loop body, the following variables are available:

Variable	Type	Description
`loop.index`	number	Zero-based index of the current iteration
`loop.currentItem`	any	The current item (ForEach loops) or loop context (While loops)
`loop.items`	array/object	The full collection being iterated (ForEach only)

After the loop completes, downstream blocks can access:

Variable	Type	Description
`loop.results`	array	Ordered array of all iteration outputs

Configuration

Parameter	Applies to	Description
Loop Type	All	`for`, `forEach`, `while`, or `doWhile`
Iterations	For	Number of times to repeat (default: 5)
Collection	ForEach	Array or object to iterate. Supports JSON literals, `<block.output>` references, and expressions.
Condition	While / Do-While	A boolean expression evaluated each iteration (e.g., `<variable.i> < 10`)

Example Use Cases

Processing API Results

An API block fetches a list of customer records.
A ForEach loop iterates over each customer.
Inside the loop, an Agent analyzes the customer data and a Function stores the result.
After the loop, a Response block returns the aggregated loop.results.

A For loop set to 5 iterations generates content variations.
Inside the loop, an Agent produces a draft and an Evaluator scores it.
After the loop, a Function selects the highest-scoring variation from loop.results.

Limitations

Container blocks (Loops and Parallels) cannot be nested inside each other. You cannot place a Loop inside another Loop, or a Parallel inside a Loop. If you need multi-dimensional iteration, restructure your workflow to use sequential loops or process data in stages.

Loops execute iterations sequentially. For concurrent execution of independent tasks, use the Parallel block instead.

Best Practices

Set reasonable iteration counts for For loops to avoid long-running workflows. The default is 5.
Use ForEach for collections -- it automatically sizes to the collection length and gives you currentItem.
Always update your condition variable inside While/Do-While loops. Forgetting to change the variable the condition depends on creates an infinite loop (bounded only by the workflow timeout).