---
title: "Loop"
url: "https://help.flows.world/en/article/loop"
language: "en"
last_updated: "2026-09-19T07:06:09.280Z"
---

# Loop

## **Overview**

Iterates through each item in an array, executing a set of stages for every element in the collection.

**IMPORTANT:** The fields do not contain **{{}}** just plain text as it is an Array. When specifying the `Items to Loop On` field, use the plain variable name (e.g., `customers`) rather than the variable reference syntax (e.g., **{{****customers****}}**).

![](https://cdn-assets.productfruits.com/8a898eb5-0b6b-48b3-93b7-2b19d9b53e40)

## **When to Use**

-   Process each item in a list of records
-   Send emails to multiple recipients
-   Update multiple database records
-   Transform array data item by item
-   Perform calculations on each element
-   Make API calls for each item in a collection
-   Generate reports for multiple entities

## **Configuration**

### **Fields Reference**

| Field | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| **Items to Loop On** | Array | Yes | Array variable containing items to iterate (use plain variable name, not **{{}}** syntax) | customers, orderItems, emailList |
| **Loop Item Name** | String | Yes | Variable name for the current item during each iteration (default: variable) | customer, order, item |

**Critical Note:** When configuring `Items to Loop On`, enter the plain variable name without **{{}}** brackets. The system treats this as an array reference.   
![](https://cdn-assets.productfruits.com/a843ea78-67e2-4e0d-ab3c-2a3759031ea0)

## **Exit Points**

| Exit | When | Purpose |
| --- | --- | --- |
| **Iterate** | Executes for each item in the array | ✓ Connect stages that run once per array element |
| **Pass** | After all items have been processed | ✓ Flow continues after loop completes |

## **How It Works**

When executed, the stage:

1.  **Parses the Array** - Converts items into a processable collection
2.  **Iterates Sequentially** - Processes items one at a time (not parallel)
3.  **Sets Current Item** - Makes item available via Loop Item Name variable
4.  **Executes Iterate Path** - Runs connected stages for current item
5.  **Waits for Completion** - Finishes iteration before moving to next item
6.  **Repeats** - Continues until all items processed
7.  **Exits via Pass** - After all iterations complete

## **Item Access Patterns**

| Item Type | How to Access | Example |
| --- | --- | --- |
| **Primitive (string, number)** | Use **{{****variable****}}** directly | **{{****variable****}}** if item is a simple ID |
| **JSON Object** | Use dot notation for fields | **{{****variable.userid****}}**, **{{****variable.email****}}** |
| **Nested Object** | Chain dot notation | **{{****variable.address.userid****}}** |

## **Common Use Cases**

### **1\. Send Email to Multiple Recipients**

-   **Items to Loop On:** customers
-   **Loop Item Name:** customer
-   **Iterate Path:** Call API to send email with **{{****variable.email****}}** and **{{****variable.userid****}}**

### **2\. Calculate Totals**

-   **Items to Loop On:** cartItems
-   **Loop Item Name:** item
-   **Iterate Path:** Increment Number with **{{****variable.price****}}**
-   **Pass Path:** Fetch Data to get final total

## **Key Behaviors**

| Feature | Behavior |
| --- | --- |
| **Processing Order** | Sequential (one at a time, not parallel) |
| **Empty Array** | Goes directly to Pass exit (no iterations) |
| **Variable Cleanup** | Previous item variable removed before loading next item |
| **Debug Limit** | Debug output shows first 15 iterations only |
| **Loop Counter** | ✗ No counter variable exposed to flow |
| **Break Early** | ✓ Use Stop Loop stage to exit before completion |
| **Nested Loops** | ✓ Supported (use unique loop item names) |

## **Do's and Don'ts**

| Do | Don't |
| --- | --- |
| ✓ Use descriptive loop item names (`customer` better than `item`) | ✗ Use generic variable names (makes code unclear) |
| ✓ Connect the Iterate exit to stages that run per item | ✗ Try to loop non-array data (ensure input is array) |
| ✓ Connect the Pass exit to continue after loop | ✗ Create infinite loops (ensure iterate path completes) |
| ✓ Keep iterations simple to avoid timeouts | ✗ Access wrong variable (use `customer`, not `customers`) |
| ✓ Handle errors within iterations using error exits | ✗ Modify the source array during iteration |
| ✓ Use Stop Loop to break out early when needed | ✗ Forget to connect exits (both required) |
| ✓ Test with small arrays first before large datasets | ✗ Assume arrays always have items (handle empty case) |
| ✓ Use unique names for nested loops | ✗ Use same variable name in nested loops (causes conflicts) |

## **Troubleshooting**

| Issue | Common Cause | Fix |
| --- | --- | --- |
| Loop doesn't execute, goes straight to Pass | Iterate exit not connected | Always connect Iterate exit to stages you want to run for each item |
| Flow stops after loop completes | Pass exit not connected | Connect Pass exit to continue flow after all iterations complete |
| Variables from loop items not accessible | Using wrong variable name | Use loop item name `customer`, not array name `customers` within iterations |
| Loop processes wrong data | Passing single object instead of array | Ensure loop input is actually an array/list; verify source variable contains array |
| Loop never completes | Iterate path doesn't return to loop | Ensure iterate path eventually completes and returns control for next item |
| Cannot access nested object fields | Not using dot notation | Access nested fields with dot notation: **{{****customer.address.userid****}}** |
| Nested loops overwrite variables | Variable name conflicts between loops | Use unique, clear names for each loop level (**{{****customer.name****}}** and **{{****variable.name****}}**) |
| Stage errors not handled in loop | No error exits on iterate stages | Add error exits on stages within iterate path to handle failures gracefully |
| Loop parsing fails (Error exit) | Invalid JSON in array variable | Verify array variable contains valid JSON array format; check source data |
| Debug output stops after 15 items | Debug mode iteration limit | Normal behavior; loop continues processing all items, just stops logging after 15th |

## **Edge Cases**

### **Empty Array**

Loop body never executes. Goes directly to Pass exit. This is normal behavior, not an error. Ensure Pass exit is connected to handle zero-iteration scenario.

### **Single Item Array**

Iterates exactly once, then exits via Pass. No special handling required.

### **Null Items in Array**

If array contains null items, they're stored as null in dictionary. Loop doesn't skip nulls automatically. Downstream stages must handle null values.

### **Breaking Out Early**

Use Stop Loop stage to exit before all items processed. After break, goes to Pass exit (not a different exit).

### **Very Large Arrays (10,000+ items)**

No explicit limit enforced. Performance scales linearly with array size. Consider flow timeout settings. Debug output capped at 15 iterations to avoid performance issues.

### **Nested Arrays**

If array item is itself an array, nest another Loop stage inside to iterate nested arrays. Parent loop provides context for child loop.

## **Related Stages**

-   [**Stop Loop**](https://help.flows.world/en/article/stop-loop-stage)**:** Exit a loop early when a condition is met
-   [**Route Flow**](https://help.flows.world/en/article/route-flow)**:** Make decisions within each iteration
-   [**Change Data**](https://help.flows.world/en/article/change-data)**:** Transform data during each iteration
-   [**Save Data**](https://help.flows.world/en/article/save-data)**:** Store results from each iteration
-   [**Call API**](https://help.flows.world/en/article/call-api)**:** Make API calls for each item