Skip to main content

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​

FieldTypeDescription
itemsarrayRequired. The list to loop over, or a reference to one. At most 1,000 entries
max_itemsintegerThe most items the loop runs, 1 to 1,000. Defaults to 100. Required when a step inside the loop moves money
on_overflowfail | first_nWhat 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_errorbooleanDefault false: the first item that fails stops the loop. Set true to record the failure and move on to the next item
collectarray of step keysThe steps inside the loop whose outputs are kept in the loop's output. Defaults to every step inside it
stepsarrayRequired. 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:

RootWhat it holds
itemThe current item
indexIts position in the list, starting at 0
looploop.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_items when 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/usage reports the ceiling that applies to you as max_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 check failed in 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_error says.

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_items and on_overflow explicitly. 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_error does 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
}
  • items has one entry per item the loop ran, in list order. Each item's status is succeeded, failed, or not_run (never reached because the loop stopped). outputs holds the latest output of each collect step.
  • halted is true when the loop stopped early, and halted_key names the step that stopped it.
  • The output is capped at 5 MB. Past that, every item's outputs is dropped (status and errors stay) and outputs_truncated is true. 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:

MethodPathScopeDescription
GET/api/v1/flows/runs/{runId}/loops/{stepKey}/iterationsflows:readOne 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:readOne 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.