How to use splitInBatches node in n8n?

The SplitInBatches node lets you take a big list of items coming from a previous node and process them in smaller, controlled chunks. You tell the node how many items should be in each batch, and the workflow will loop through those batches until everything is processed. You run the first pass as normal, then you connect the node back to itself (or to another node and then back), and n8n will keep re‑running that section with the next batch until the list is finished. It’s basically n8n’s way of doing a “loop” over large datasets without loading everything into one giant operation.

 

What SplitInBatches Actually Does

 

When a node before it outputs, for example, 3,000 items, the SplitInBatches node doesn’t output all of them at once. Instead, you configure something like “batch size = 100”. Then:

• The first time it runs, it outputs items 1–100.
• When the node runs again (because you loop back to it), it outputs 101–200.
• This continues until all items are exhausted.

The most important thing to understand: the workflow run stays alive the whole time. It doesn’t start new runs; it re-executes the downstream part of the workflow multiple times inside the same execution.

 

How To Use It Step‑By‑Step

 

• Put a node that returns multiple items before the SplitInBatches node. Example: a database query returning many rows, or an API returning a big array.
• Add the SplitInBatches node and set its Batch Size (like 50 or 100). This controls how many items you handle each loop.
• Connect it to whatever node should process each batch. This could be an API call, a Function node, etc.
• After your processing node, connect back into the SplitInBatches node. This creates the loop.
• Inside the SplitInBatches node, make sure “Always Output Data” is enabled if you need consistency for downstream nodes.
• The SplitInBatches node will stop looping automatically when all items are consumed. You don’t need extra conditions.

 

A Minimal Example Workflow Structure

 

This is the simplest working pattern:

• Node A: returns 2,000 items
• SplitInBatches (batch size = 100)
• Processing node (for example, an HTTP Request)
• Back to SplitInBatches

In this pattern, the processing node will execute about 20 times, each time with 100 items.

 

Simple Expression Example

 

Sometimes you need to pass the current batch items to another node. Inside an HTTP Request body you could write:

{
  "batch": {{$json}}   // this returns the current batch of items
}

 

Key Production Tips

 

• Batch size matters: Too large = API rate limits or timeout risk. Too small = runs slower. Start with 50–200 in most cases.
• Don’t put heavy logic inside the loop unless necessary. If something is slow, isolate the slow part in the processing node.
• Beware very long loops. SplitInBatches keeps the workflow running until all batches finish. For tens of thousands of items, think about chunking upstream or moving heavy processing outside n8n.
• Use error workflows or try/catch nodes. If one batch fails (like an API rate limit), you want retry logic instead of losing the whole execution.
• Avoid mixed data types. SplitInBatches expects an array of consistent objects. If your previous node returns something weird, fix it first.
• Remember: SplitInBatches outputs an array. Some nodes expect single objects in JSON mode, so adjust accordingly or iterate again inside the processing node.

 

The Practical Mental Model

 

The SplitInBatches node is a controlled loop. It doesn’t duplicate data, it just slices the original input. The workflow says: “Give me the next X items; process them; repeat until nothing is left.” Once you understand that, you can easily use it to safely process big datasets or rate‑limit your calls to external systems.