---
title: Using the Loop Native Action
slug: using-the-loop-native-action
docTags: 
createdAt: 2025-08-11T11:13:48.000Z
---

The **Loop** native action repeats child actions in a playbook. Use a **forEach** loop to iterate over an array, or a **While** loop to repeat while a condition is true.

This topic focuses on **While** loop timing inputs. Starting in **Turbine 26.2.0**, **Delay** and **Duration** are labeled and entered in **seconds** in the canvas UI.

## Choose Your Path

| I want to…                                    | Start here                                                                                                                  |
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Configure a While loop on the canvas          | [Configure a While Loop](https://docs.swimlane.com/using-the-loop-native-action#configure-a-while-loop)                     |
| Understand Delay and Duration units           | [Delay and Duration Units (26.2.0)](https://docs.swimlane.com/using-the-loop-native-action#delay-and-duration-units-2620)   |
| Confirm upgrade impact for existing playbooks | [Existing Playbooks After Upgrade](https://docs.swimlane.com/using-the-loop-native-action#existing-playbooks-after-upgrade) |
| Use playbook expressions for timing           | [Playbook Expressions](https://docs.swimlane.com/using-the-loop-native-action#playbook-expressions)                         |

## Configure a While Loop

1. Add a **Loop** action from the canvas **Add** panel.
2. On the action details panel, set **Type of loop** to **While**.
3. Click **Edit Condition** and define when the loop should continue.
4. Click **Configure** to open the While loop inputs.
5. Set **delay (in seconds)**, **duration (in seconds)**, and **limit** as needed.
6. Add child actions on the loop entry branch and save the playbook.

| Input                     | Description                                                   |
| ------------------------- | ------------------------------------------------------------- |
| **condition**             | Boolean expression that must be true for the loop to continue |
| **delay (in seconds)**    | Wait time before each iteration after the first               |
| **duration (in seconds)** | Maximum time the loop may run                                 |
| **limit**                 | Maximum number of iterations allowed                          |

:::hint{type="info"}
Use **limit** and a well-defined **condition** together so a While loop cannot run indefinitely. **Duration** provides an additional time-based guardrail.
:::

## Delay and Duration Units (26.2.0)

Before **Turbine 26.2.0**, the While loop **Delay** and **Duration** fields accepted numeric values in **milliseconds**, but the canvas did not show the unit. Users often assumed **seconds**, which caused loops to wait or run much longer than intended.

Starting in **26.2.0**:

| Field                     | What you enter in the UI     | What the playbook stores             |
| ------------------------- | ---------------------------- | ------------------------------------ |
| **delay (in seconds)**    | Seconds (for example **2**)  | Milliseconds (for example **2000**)  |
| **duration (in seconds)** | Seconds (for example **10**) | Milliseconds (for example **10000**) |

The canvas converts static numeric values when you open and save the While loop dialog:

- **On load** — stored milliseconds are divided by 1000 and shown as whole seconds in the UI.
- **On save** — whole-number seconds you enter are multiplied by 1000 before the playbook is saved.

The Turbine engine still evaluates **Delay** and **Duration** in **milliseconds** at run time.

## Existing Playbooks After Upgrade

The **26.2.0** unit change is **UI only**. Playbook JSON and API payloads are not migrated to a new unit.

| Stored value (unchanged) | What you see after upgrade          | Run-time behavior                                           |
| ------------------------ | ----------------------------------- | ----------------------------------------------------------- |
| **delay** = 2000         | **2** in **delay (in seconds)**     | Still waits **2000 ms** (2 seconds) between iterations      |
| **duration** = 10000     | **10** in **duration (in seconds)** | Still stops after **10000 ms** (10 seconds) total loop time |

Existing customer playbooks keep the same timing after upgrade. The UI displays equivalent seconds for clarity; run time does not change unless you edit and save new values.

:::hint{type="warning"}
If you open a While loop, change **Delay** or **Duration**, and save, the UI saves your entry as seconds converted to milliseconds. Review timing after edits to avoid unintentionally longer or shorter waits.
:::

## Playbook Expressions

You can map **delay**, **duration**, or **limit** to playbook properties or expressions instead of static numbers.

| Value type                           | UI behavior                                                        | Run-time behavior                                             |
| ------------------------------------ | ------------------------------------------------------------------ | ------------------------------------------------------------- |
| **Static number**                    | Shown and edited in **seconds**; converted to milliseconds on save | Engine uses stored milliseconds                               |
| **Expression or property reference** | Passed through without seconds conversion in the dialog            | Evaluated result is treated as **milliseconds** by the engine |

:::hint{type="info"}
If you use an expression for **delay** or **duration**, supply or calculate values in **milliseconds** even though the field label says seconds. For example, to wait two seconds via a variable, the evaluated value must be **2000**, not **2**.
:::

## See Also

- [Organizing Playbook in the Canvas](docId\:ds_geaoGH--2ujXg-ROYS) — canvas tools, loops, **Group**, and tool panel
- [Components](docId\:c7ipCS5NdR9sGu4z6Pjs0) — loop nesting depth limits