Loop

The Loop block is a container that executes blocks repeatedly. Iterate over collections, repeat operations a fixed number of times, or continue while a condition is met.

Loop blocks are container nodes that hold other blocks inside them. The contained blocks execute multiple times based on your configuration.

Configuration Options

Loop Type

Choose between four types of loops:

For Loop (Iterations) - A numeric loop that executes a fixed number of times:

Use this when you need to repeat an operation a specific number of times.

Example: Run 5 times
- Iteration 1
- Iteration 2
- Iteration 3
- Iteration 4
- Iteration 5

ForEach Loop (Collection) - A collection-based loop that iterates over each item in an array or object:

Use this when you need to process a collection of items.

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

While Loop (Condition-based) - Continues executing while a condition evaluates to true:

Use this when you need to loop until a specific condition is met. The condition is checked before each iteration.

Example: While {"<variable.i>"} < 10
- Check condition → Execute if true
- Inside loop: Increment {"<variable.i>"}
- Inside loop: Variables assigns i = {"<variable.i>"} + 1
- Check condition → Execute if true
- Check condition → Exit if false

Do-While Loop (Condition-based) - Executes at least once, then continues while a condition is true:

Use this when you need to execute at least once, then loop until a condition is met. The condition is checked after each iteration.

Example: Do-while {"<variable.i>"} < 10
- Execute blocks
- Inside loop: Increment {"<variable.i>"}
- Inside loop: Variables assigns i = {"<variable.i>"} + 1
- Check condition → Continue if true
- Check condition → Exit if false

How to Use Loops

Creating a Loop

Drag a Loop block from the toolbar onto your canvas
Configure the loop type and parameters
Drag other blocks inside the loop container
Connect the blocks as needed

Referencing Loop Data

There's an important distinction between referencing loop data from inside vs outside the loop:

Inside the loop, use <loop.> references to access the current iteration context:

<loop.index>: Current iteration number (0-based)
<loop.currentItem>: Current item being processed (forEach only)
<loop.items>: Full collection being iterated (forEach only)

// Inside a Function block within the loop
const idx = <loop.index>;           // 0, 1, 2, ...
const item = <loop.currentItem>;    // Current item

These references are only available for blocks inside the loop container. They give you access to the current iteration's context.

Outside the loop (after it completes), reference the loop block by its name to access aggregated results:

<LoopBlockName.results>: Array of results from all iterations

// If your loop block is named "Process Items"
const allResults = <processitems.results>;
// Returns: [result1, result2, result3, ...]

After the loop completes, use the loop's block name (not loop.) to access the collected results. The block name is normalized (lowercase, no spaces).

Example Use Cases

Processing API Results - ForEach loop processes customer records from an API

API (Fetch) → Loop (ForEach) → Agent (Analyze) → Function (Store)

Iterative Content Generation - For loop generates multiple content variations

Loop (5x) → Agent (Generate) → Evaluator (Score) → Function (Select Best)

Counter with While Loop - While loop processes items with counter

Variables (i=0) → Loop (While i<10) → Agent (Process) → Variables (i++)

Advanced Features

Limitations

Container blocks (Loops and Parallels) support nesting. You can place loops inside loops, parallels inside loops, and any combination of container blocks to build complex multi-dimensional workflows.

Loops execute sequentially, not in parallel. If you need concurrent execution, use the Parallel block instead.

Inputs and Outputs

Loop Type: Choose between 'for', 'forEach', 'while', or 'doWhile'
Iterations: Number of times to execute (for loops)
Collection: Array or object to iterate over (forEach loops)
Condition: Boolean expression to evaluate (while/do-while loops)

Available inside the loop only:

<loop.index>: Current iteration number (0-based)
<loop.currentItem>: Current item being processed (forEach only)
<loop.items>: Full collection (forEach only)

<blockname.results>: Array of all iteration results (accessed via block name)
Structure: Results maintain iteration order
Access: Available in blocks after the loop completes

Best Practices

Set reasonable limits: Keep iteration counts reasonable to avoid long execution times
Use ForEach for collections: When processing arrays or objects, use ForEach instead of For loops
Handle errors gracefully: Consider adding error handling inside loops for robust workflows

Common Questions

For loops (fixed count) and ForEach loops are capped at 1,000 iterations/items (from executor constants). While loops and Do-While loops with a condition have no hard iteration cap — they run until the condition evaluates to false. Do-While loops without a condition fall back to a fixed iteration count, which is capped at 1,000. Always ensure your While/Do-While conditions will eventually become false to avoid infinite loops.

Loops execute all iterations sequentially, one after another. If you need concurrent execution across items, use the Parallel block instead. You can also nest a Parallel block inside a Loop if you need both iteration patterns.

Inside the loop, use <loop.currentItem> to get the current item being processed and <loop.index> for the zero-based iteration number. These references are only available to blocks placed inside the loop container — blocks outside the loop cannot access them.

After the loop completes, reference the loop block by its normalized name (lowercase, no spaces) using <blockname.results>. This returns an array of all iteration results in order. For example, if your loop block is named 'Process Items', use <processitems.results>. Do not use <loop.> syntax outside the loop — that only works inside.

Yes. Container blocks (Loops and Parallels) fully support nesting. You can place loops inside loops, parallels inside loops, loops inside parallels, and any combination. Each nested container maintains its own scope and iteration context independently.

A While loop checks its condition before each iteration, so it may execute zero times if the condition is false initially. A Do-While loop executes its body at least once, then checks the condition after each iteration to decide whether to continue. Use Do-While when you need guaranteed first execution.

If the ForEach loop's collection is empty, the loop body is skipped entirely and the loop outputs an empty results array. The workflow continues normally to any blocks connected after the loop.

Common Questions

On this page