nodes / builtin / flow
Split in Batches
Loop over a list a batch at a time, running the body once per batch
Work through a list a few items at a time, running the same steps once per batch.
What it does
Section titled “What it does”Split in Batches works like Loop, but instead of a condition you give it a list. It has two inputs and two outputs:
- Input (top): where the data first comes in.
- Loop Back (bottom input): connect the last step of the repeated part here.
- Loop (output): gets the next batch; the steps to repeat start here.
- Done (output): runs once, after the last batch.
On each pass it sends the next Batch size items out of Loop and waits for them to come back through Loop Back before sending the next ones. With 7 items and a batch size of 3, the steps run three times, with items 1-3, 4-6 and 7, then the workflow continues from Done.
- An empty list goes straight to Done. A single value that is not a list counts as one batch of one item.
- As a safety limit, the node stops after 1,000 passes, even if items are left.
- If the run pauses in the middle (for example on a Wait For Approval inside the loop), it resumes at the right batch.
When to use it
Section titled “When to use it”- Send rows to an API 10 at a time because it rejects large requests.
- Ask for an approval or show a form once per item (batch size 1).
- Slow down: add a Wait inside the loop so a site or API isn’t hit too fast.
Most nodes already run once per item, so you don’t need Split in Batches just to handle every item of a list. To repeat until a condition changes, use Loop.
Inputs and settings
Section titled “Inputs and settings”| Setting | Type | What it does |
|---|---|---|
| Items (required) | Value | The list to split into batches. |
| Batch size | Number | How many items to emit per pass. Default: 1 |
| Collect results | Toggle | Output everything that came back through Loop Back, in order, on Done. Default: Off |
| One entry per item | Toggle | Used with Collect results: a pass that returns a list adds its items one by one. Off: one entry per pass. Default: On |
| Fail if the pass limit is reached | Toggle | Fail the step when 1,000 passes end the split before every item was processed. Default: Off |
Set Items to an expression that returns a list, for example {{ $input.data.contacts }} after an Http Request. If your data arrives as many separate items, gather them into one list first with Aggregate.
Collect results
Section titled “Collect results”Turn on Collect results to get, on Done, everything that came back through Loop Back during the passes, in order, as results (one entry per item, or per pass). Without it, Done only carries the last data, as before. Up to 10,000 entries (about 2 MB) are kept; beyond that the list is cut, resultsTruncated is set and the run log warns you. Nested loops each keep their own results.
Fail if the pass limit is reached
Section titled “Fail if the pass limit is reached”The node stops after 1,000 passes. When that happens before every item was processed, it says so (a warning, and stoppedEarly, processed and total on each pass). Turn on Fail if the pass limit is reached to make it fail the step instead, so a cut-short run can’t pass for a complete one.
Outputs
Section titled “Outputs”-
Done -
Loop
Each output item has these fields:
| Field | Type | What it holds |
|---|---|---|
| done | True/false | True once every item has been emitted |
| batch | List | The items of this pass |
| batchIndex | Number | |
| isLast | True/false | |
| items | List | Every item being split |
| processed | Number | How many items have been emitted so far |
| total | Number | How many items there are to split |
| stoppedEarly | True/false | True on the Done pass when the pass limit stopped the split before the end |
| results | List | With Collect results: what came back through Loop Back on every pass |
| resultsTruncated | True/false | True when Collect results stopped at its limit |
{ "done": true, "batch": [], "batchIndex": 0, "isLast": true, "items": [], "processed": 0, "total": 0, "stoppedEarly": true, "results": [], "resultsTruncated": true}In the repeated steps, read the current batch with {{ $input.batch }}. batchIndex counts batches from 0, and isLast is true on the final batch. From Done, {{ $input.items }} still gives you the whole list.
Dependencies and credentials
Section titled “Dependencies and credentials”None. This node needs no connection and has no slots for other nodes.
Example workflow
Section titled “Example workflow”Send contacts to an API 25 at a time:
- Http Request gets
https://api.example.com/contacts, which returns{ "contacts": [...] }. - Split in Batches with Items
{{ $input.data.contacts }}and Batch size25. - From Loop: a second Http Request, POST to
https://api.example.com/contacts/bulkwith{{ $input.batch }}in the JSON body, then Wait with Amount2and Unit Seconds. Connect the Wait to Loop Back. - From Done: Show Notification says
All contacts sent.
Common issues
Section titled “Common issues”- The steps run only once. The last repeated step is not connected to Loop Back, so the node never gets asked for the next batch. Connect it to the bottom input, not the top one.
- It goes straight to Done. Items resolved to an empty list or to nothing. Check the expression in the run’s input for this node; it must point to a list.
- Nothing runs after the loop. Connect the next steps to Done, not to Loop.
- It stopped before the end of a very long list. The node stops after 1,000 passes. Raise Batch size so the list fits in fewer passes.