# Looper

<figure><img src="/files/ydU6oO8PKabL2DHMRec3" alt="" width="375"><figcaption></figcaption></figure>

## Overview

The **Loop Helper** is one of the most powerful Helpers and at the same time, one of the easiest to setup. It allows you to loop over [**lists**](https://docs.locoia.com/connectors/helpers/pages/-Me_20t0sZFoIsFyOutC#2.-lists), a list of [**dictionaries**](https://docs.locoia.com/connectors/helpers/pages/-Me_20t0sZFoIsFyOutC#1.-dictionaries-dict) and **arrays** and execute **an action multiple times** (each entry of the list, dict or array).

## Actions

### 1. Iterate Over Loop

The Iterate Over action loops over a pre-defined list.&#x20;

Let's use an example:\
Imagine you want to send emails to each user you get from the **Get Contacts** step that returns a list of contacts:

{% code title="List of contacts" %}

```python
[
  {"id": 123, "email": "john.doe@mail.com"},
  {"id": 456, "email": "peter.gragory@mail.com"},
  {"id": 789, "email": "richard.hednricks@mail.com"}
]
```

{% endcode %}

\
Select the Action type **Iterate Over** and input `get_contacts` to the Loop Reference. In the [**Action Loop**](#action-loop-arrow) send an email to each user by accessing the email property with the Jinja expression `{{get_contacts[index].email}}`

<figure><img src="/files/qqOdXsfcA5uR3x3PAFHF" alt=""><figcaption><p>Iterate Over example</p></figcaption></figure>

### 2. Iterate While Loop

The Iterate Over action loops while (until) a defined condition is matched; usually e.g. until there are no more pages to loop over.

The condition is always **checked at the end of each loop iteration** so that you can also reference steps that happen inside the loop, which are not yet available at the beginning of the first iteration.

### Example

Run while the index is smaller than 10:

```
index < 10
```

This loop will have 11 iterations because `index` starts at `0` and the condition is checked at the end and not at the beginning of each loop iteration.

{% hint style="info" %}
The iterate while loop has a **maximum of 1000** iterations for capacity protection. If you need to increase this limit, please raise a support ticket.
{% endhint %}

## Action Loop arrow

It is necessary to link the ActionLoop arrow in the Looper Helper to the steps that will be executed during each iteration.&#x20;

{% hint style="warning" %}
The Looper Helper is associated with the pre-created arrow named **ActionLoop**, so don't change it or it will break.
{% endhint %}

## Nested loops

It is possible to loop over multiple objects, e.g. over a list of companies (`loo1`) then over each employee (`loo2`) then over each ticket of an employee (`loo3`). Just make sure, you reference correctly in the subsequent branches of the loop.

{% hint style="info" %}
Keep in mind that `{{index}}` always refers to the current loop. In a nested loop, `{{index}}` will always reflect the index of the innermost loop. If you need to reference the index of an outer loop, you must store that index explicitly in a variable (using a "Dict Helper" step or a similar approach) before entering the inner loop. This allows you to safely access the outer loop's index while iterating through the inner loops.
{% endhint %}

## Run certain iteration

The Looper runs all iterations by default, but if working with complex flows and if waiting for results is time- or resource-consuming, you can also run a selected iteration, when using Single Flow Step runs.

{% hint style="info" %}
When running the entire Flow, the Looper will run **all** iterations, no matter what iteration index is set.
{% endhint %}

<figure><img src="/files/gLRHi2wjUCM7Viq7DNPF" alt=""><figcaption><p>Set iteration index</p></figcaption></figure>

## Referencing Behavior

Using the same reference inside a Looper as the Looper Helper itself does not work as expected, as the Looper Helper's reference will always have priority, while the Looper is running, and thus any other step with the same reference inside the loop will never be considered.

## Run iterations in parallel

The "Run Iterations in Parallel" feature is designed to accelerate flow execution by processing items in batches of 10 concurrently. After completing the first batch, the Looper moves on to the next batch of 10 items (or the remaining number).

**Key Aspects of the Parallel Looper:**

* **Sorting**:

  The output in the step's debugger will be sorted by start date, so steps from later iterations might appear before those from earlier iterations.

  * Currently in development: Sorting of the final output of the Looper according to the iteration indexes and then start date (so that different iterations are not mixed in the Flow Debugger)
* [**Custom Error Handling**](/automation/flow-builder/custom-error-handling.md):

  Each step in the Looper can have its own error handling:

  * **Terminate flow:** If a step fails with this error handler, no further iterations will be scheduled. However, already scheduled iterations will continue to execute.
  * **Skip loop iteration:** This error handler skips the current iteration but allows the Looper to continue processing other iterations.
  * **Break current loop:** This causes the Looper to exit the current loop iteration but does not affect others.

  If multiple errors occur with different handlers, the most severe one dictates the outcome:

  * For example, if multiple steps fail and use different error handlers (e.g., one step uses **Skip loop iteration**, another uses **Break current loop**, and a third uses **Terminate flow**), the "worst" status wins. In this case, the Looper will terminate with an error, and flow execution will not continue.
* **Completion of Running Iterations**:
  * If an error occurs that requires stopping further iterations (like "Terminate"), the Looper will not schedule any more batches.
  * However, all currently running iterations will be allowed to complete.\
    **For example:** if an error happens on the 3d iteration, the Looper will finish the remaining iterations from the current batch


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.locoia.com/connectors/helpers/loop-helper.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.