Run steps for each item with For each
A For each step (loop.for_each) takes a list and runs the steps placed
inside it once per item, one item at a time, in the same run. The list can be
orders, line items, CSV rows, any array from the trigger or an earlier step, or
a plain list of order IDs. When the loop finishes, its output holds a result
for every item, so later steps can see what happened to each one.
{
"key": "each_order",
"type": "loop.for_each",
"config": {
"items": "{{ steps.find_orders.output.orders }}",
"max_items": 250,
"on_overflow": "fail",
"steps": [
{
"key": "buy_label",
"type": "orderly.label.purchase",
"config": { "order_id": "{{ item.id }}" }
}
]
}
}
Settings
| Field | Type | Description |
|---|---|---|
items | array | Required. The list to loop over, or a reference to one. At most 1,000 entries |
max_items | integer | The most items the loop runs, 1 to 1,000. Defaults to 100. Required when a step inside the loop moves money |
on_overflow | fail | first_n | What happens when the list is longer than the cap. fail (the default) fails the step before any item runs; first_n runs the first items up to the cap and leaves the rest out. Required when a step inside the loop moves money |
continue_on_item_error | boolean | Default false: the first item that fails stops the loop. Set true to record the failure and move on to the next item |
collect | array of step keys | The steps inside the loop whose outputs are kept in the loop's output. Defaults to every step inside it |
steps | array | Required. The steps to run for each item, 1 to 20, counting the steps in branch lanes inside the loop |
Inside the loop
Every step inside the loop can read three extra roots in its references and guards:
| Root | What it holds |
|---|---|
item | The current item |
index | Its position in the list, starting at 0 |
loop | loop.item, loop.index, loop.count (items the loop runs), loop.first, and loop.last |
A list of order IDs is read as {{ item }}; a list of orders as
{{ item.id }}. loop.item is there for the case where a Map list step
inside the loop has its own item: the loop's item stays reachable as
loop.item. In a code.run step, item, index, and loop are variables.
A step inside the loop can read steps that run before the loop, and steps earlier in the loop for the same item. It cannot read the loop step itself or a step that comes later inside the loop.
What a loop can hold:
- Any step, including Branch, except another For each (loops do not nest), Wait for event, and Respond.
- Steps inside a loop can retry, and steps that move no money can skip on error. They cannot have error handler lanes.
A For each step can sit inside a branch lane and can come after a Wait for event step.
How many items run
The loop runs at most its cap of items:
max_itemswhen you set it, otherwise 100.- Never more than your plan's per-loop ceiling. Plans allow up to 1,000
items per loop unless your plan sets a lower ceiling.
GET /api/v1/flows/usagereports the ceiling that applies to you asmax_loop_items. - Never more than 1,000, the hard maximum.
Publishing refuses a max_items above your plan's ceiling. Because plans can
change after publishing, the cap is applied again every time the loop starts.
A list longer than the cap fails the loop before any item runs, unless
on_overflow is first_n, which runs the first items up to the cap. The
loop's output says which happened (total, count, truncated, cap, and
cap_source, which is default, step, or plan).
Two more limits keep a run within bounds:
- A run can execute at most 5,000 steps inside For each loops, counting
every loop in the run. Publishing checks the worst case of each loop
(
max_items, or 100, times the number of steps inside it), and a loop that would pass the limit at run time fails before any item runs. - The list a loop runs is saved when it starts and can be up to 5 MB.
Billing
Each step inside the loop is billed as one step for every item it runs on. The
For each step itself is not billed. A step that is set to skip on error still
counts, and a step that is skipped by its when guard does not.
For example, a loop over 500 orders with 3 steps inside bills 1,500 steps in
one run. A Map list step doing similar work in one step
bills 1. Set max_items to bound the cost of a loop: it caps the items, and so
the steps, that one run can bill.
The list is fixed when the loop starts
When a loop starts, it saves the list it is going to run. Every retry and every resume of the run uses that saved list, even if the source data, lookup tables, or parameters changed in the meantime. Item 3 always means the same item, so the steps for it are never repeated for a different record.
Item failures
When a step inside the loop fails (after its own retries):
- By default the loop stops: no further items start, and the run fails at that
item and step, for example
each_order[3].buy_label. Retrying the run picks up the items that have not succeeded yet; items that already succeeded are not run again. - With
continue_on_item_error: true, the rest of that item's steps are not run, the failure is recorded in the loop's output, and the next item starts. The loop succeeds even if some items failed, so checkfailedin its output if later steps depend on every item. - A step inside the loop that is set to skip on error is recorded as skipped, and the item carries on.
- In a client's flow, an item that names another
client's record always stops the loop, whatever
continue_on_item_errorsays.
The For each step itself can only fail on error, or skip or run a handler lane when nothing inside it moves money. It cannot retry; set retries on the steps inside it instead.
Loops that move money
A loop "moves money" when any step inside it, at any depth, buys a label
(orderly.label.purchase), books a pickup (orderly.pickup.schedule), or
voids a label (orderly.label.void). Such a loop has stricter rules:
- It must set
max_itemsandon_overflowexplicitly. The defaults are not enough, so the size of the loop is always a choice you made. - Any failure of a money step stops the loop.
continue_on_item_errordoes not apply to it, and the step cannot skip on error. - The For each step can only fail on error: no skip and no handler lane.
- Any failure of the loop opens a high-priority exception, and an active scheduled flow is paused, the same as when a money step fails outside a loop.
Before the first label is bought, Orderly checks that your balance covers every
label the loop will buy, when the order IDs come from the item or from steps
before the loop. A shortfall fails the loop with INSUFFICIENT_BALANCE and no
label is bought. Each label still holds its own funds before the carrier is
called, so a loop never overdraws your balance.
Every step inside a loop runs under a key of its own for each item, such as
each_order[3].buy_label. Retrying a step reuses the same key, so a retry or a
resumed run never buys the same label or books the same pickup twice. The same
order listed twice returns the first label the second time. Two identical
pickups in a list are booked twice, so put a Remove duplicates step before a
loop that books pickups.
The output
After the loop, later steps read steps.<loop_key>.output:
{
"total": 340,
"count": 250,
"truncated": true,
"cap": 250,
"cap_source": "step",
"succeeded": 248,
"failed": 2,
"not_run": 0,
"halted": false,
"items": [
{
"index": 0,
"status": "succeeded",
"error": null,
"outputs": { "buy_label": { "shipment_id": "7b1e…", "tracking_number": "1Z…" } }
},
{
"index": 1,
"status": "failed",
"error": "No assigned shipping service for this order parcel",
"failed_step": "buy_label",
"outputs": {}
}
],
"outputs_truncated": false
}
itemshas one entry per item the loop ran, in list order. Each item'sstatusissucceeded,failed, ornot_run(never reached because the loop stopped).outputsholds the latest output of eachcollectstep.haltedistruewhen the loop stopped early, andhalted_keynames the step that stopped it.- The output is capped at 5 MB. Past that, every item's
outputsis dropped (status and errors stay) andoutputs_truncatedistrue. The loop never fails because of its output size.
Steps after the loop cannot read the steps inside it directly; read the loop's
output instead, for example
{{ pluck(steps.each_order.output.items, 'outputs.buy_label.tracking_number') }}
or a Filter list on item.status.
Dry runs
A dry run resolves the list, applies the
cap, and reports total, count, cap, cap_source, and truncated. It then
runs the steps inside the loop for the first 3 items, with money and write
steps resolved but not run, as in any dry run. The report names each previewed
step by its item key, such as each_order[0].buy_label.
Runs
A run's detail lists each loop once, with a summary in loops (status,
attempt, total, count, cap, and the succeeded, failed, not_run, and
halted counts once the loop finishes). The steps that ran for each item are
paged separately:
| Method | Path | Scope | Description |
|---|---|---|---|
GET | /api/v1/flows/runs/{runId}/loops/{stepKey}/iterations | flows:read | One page of the loop's items with their status. offset (default 0) and limit (1 to 100, default 50) |
GET | /api/v1/flows/runs/{runId}/loops/{stepKey}/iterations/{index} | flows:read | One item: its value and every attempt of the steps that ran for it |
While a loop is running, the item list reflects the steps finished so far.
In the Portal, a For each step draws a frame around the steps inside it, and the run view shows the loop as one row with its counts. Select it to page through the items, and select an item to see its steps.