Split Out and Aggregate in n8n: turning an array into items, and back

The first wall most n8n beginners hit isn't a JavaScript expression or a misconfigured credential: it's the data model. In n8n, everything that flows between two nodes is a list of items, and every node runs once per item it receives. Until that rule sinks in, you can't understand why an email node fires fifty times, or why an API response that visibly contains fifty results shows up as a single item in the UI. The Split Out and Aggregate nodes are the two native levers for steering this mechanic: the first explodes an array into N individual items, the second merges N items back into one. Master this round trip and you've unlocked 80% of the data-reshaping situations in n8n.

n8n's data model in thirty seconds

Between two nodes, data always travels in the same shape: a list of JSON objects, called items. A node that receives 50 items runs 50 times (once per item), and a node that receives a single item runs once. This convention makes workflows predictable, but it creates two uncomfortable situations:

• The array hidden inside an item. APIs often return their list of results inside a single JSON object: {"results": [...50 objects...]}. To n8n, that's one item containing an array field — downstream nodes will therefore run only once, on the whole bundle, when what you wanted was to process each result individually.
• Items you'd like to merge. Conversely, after processing 50 items, you sometimes want to produce a single output: a summary email, an LLM-generated digest, an export file. Without regrouping, the final node would run 50 times and you'd send 50 emails.

Split Out solves the first case, Aggregate the second. The idea of reshaping data through successive transformations — folding, unfolding, splitting — is nothing new, by the way: the Potter's Wheel system presented by Raman and Hellerstein at the VLDB conference in 2001 (Potter's Wheel: An Interactive Data Cleaning System — see on Google Scholar) already formalized fold, unfold and split operations applied interactively to tabular data. Split Out and Aggregate are their direct heirs, applied to the JSON flowing through your workflows.

Split Out: exploding an array field into N items

The Split Out node takes an item containing an array field and produces one output item per element of that array. Its configuration boils down to two parameters:

• Fields To Split Out: the name of the array field to unfold — for example results, or a nested path like data.items.
• Include: what to do with the other fields of the original item — keep nothing, keep all the other fields (replicated onto every output item), or keep only a selection.

Typical example: an HTTP Request node queries a CRM API that answers {"total": 3, "contacts": [{"name": "Martin"}, {"name": "Durand"}, {"name": "Leroy"}]}. In the output panel, n8n shows 1 item. A Split Out configured on the contacts field turns that output into 3 items, one per contact — and every downstream node (enrichment, sending, database write) will run three times, once per contact. If the API paginates its results, this unfolding pairs naturally with HTTP Request pagination: each page brings back its array, and Split Out flattens it out.

Worth noting: if the unfolded field contains objects, each output item receives the object's keys directly. If it contains plain values (a list of strings, say), each value is placed under a field whose name you control.

Aggregate: merging N items into one

The Aggregate node makes the reverse trip, with two operating modes in its Aggregate parameter:

• Individual Fields: you pick one or more fields to collect; each field becomes an array gathering the values from all incoming items. 50 items with an email field become 1 item with an email field holding 50 addresses. Handy for building a recipient list or an array of values to pass as a parameter.
• All Item Data: each whole item is placed, with all its fields, into an array under a single key (data by default). This is the "keep everything" mode: 50 items become 1 item containing an array of 50 complete objects.

In both cases the result is a single item at the output — and therefore a single execution for everything downstream.

Three concrete use cases

Unfolding an API response. The Split Out case par excellence, described above: an API returns an array wrapped in an object, and you want to process each element individually. Without Split Out, beginners end up hardcoding expressions like {{ $json.results[0].name }}, which handle only the first element and silently ignore the rest.

Preparing a single summary for an LLM. You have 30 items (support tickets, customer reviews, monitoring entries), and you want the model to produce one synthesis of the whole set. An Aggregate in "All Item Data" mode right before the AI node merges everything into one item: the prompt can then reference {{ JSON.stringify($json.data) }} and the LLM receives a single call, with the full context. Without the Aggregate, the AI node would run 30 times and produce 30 summaries of one ticket each — billing you for 30 calls.

Building the body of a recap email. Same logic: after extracting 20 rows from a file (see our guide on extracting and generating Excel/CSV files), an Aggregate groups them, then a Code node or an expression builds an HTML table or a bullet list from the aggregated array, injected into a single email sent exactly once.

Not to be confused with Loop Over Items or Merge

Three nodes that handle lists, three distinct jobs:

• Split Out changes the structure: 1 item containing an array of N elements → N items. No notion of pacing or batching.
• Loop Over Items changes the pace: N items → the same N items, but processed in batches of a chosen size, with a loop-back connection. It's a pacing tool, not a reshaping one — our n8n loops guide details when it's actually needed, given that most nodes already iterate over each item on their own.
• Merge combines multiple branches: it waits for data from two separate workflow inputs and joins them (by position, by key, or by appending). Aggregate works on a single branch and merges its items together — see our article on combining data with the Merge node for cross-source joins.

The trio works great together: Split Out to unfold an API response, Loop Over Items to process the items in batches of 10 while respecting a rate limit, then Aggregate to rebuild a single report at the end.

The Code node alternative

When the reshaping comes with business logic (conditional filtering, renaming, calculations), a Code node can replace both nodes at once:

• Split Out equivalent: return an array of objects. A return items.flatMap(...) or more simply a return myArray.map(x => ({ json: x })) produces N output items — n8n treats each element of the returned array as a separate item.
• Aggregate equivalent: $input.all() gives you access to every incoming item within a single run of the node (in "Run Once for All Items" mode). Returning [{ json: { data: $input.all().map(i => i.json) } }] reproduces exactly an "All Item Data" Aggregate.

Our guide on JavaScript expressions and the Code node covers these patterns in detail. The common-sense rule: for a plain unfold or regroup, prefer the dedicated nodes — their configuration is readable at a glance by anyone opening the workflow. Save the Code node for genuinely composite transformations.

Common pitfalls

• Processing only the first element without realizing it. An expression like {{ $json.results[0].email }} on an item containing an array works… for the first result only. If the next node runs just once when the API returned 50 results, a Split Out is probably missing.
• Forgetting the Aggregate before a "final" node. Email sending, file generation, a summarizing LLM call: if that node receives N items, it runs N times. Fifty emails instead of one, or thirty billed AI calls instead of a single one — the classic symptom of a missing Aggregate.
• Pointing Split Out at the wrong field. If the array is nested (data.results rather than results), targeting the wrong level produces an error or an empty output. Check the exact path in the previous node's output panel before configuring the Split Out.
• Using Merge instead of Aggregate. Merge joins two separate branches; it doesn't collapse N items from the same branch into one. To go from N to 1 on a linear flow, Aggregate is the node you need.
• Aggregating huge volumes without thinking about it. An "All Item Data" Aggregate over thousands of heavy items builds one very large item, fully loaded in memory — and often too big for an LLM's context window. On large document corpora, chunking documents for RAG is a far better strategy than a raw aggregation.

Going further

Split Out and Aggregate are so central that they appear in almost every serious data-processing workflow — starting with those of the RAG Assistant Pack (€119), whose document ingestion workflows chain precisely these two nodes: Split Out to unfold lists of documents and chunks, Aggregate to rebuild contexts before indexing. If you're new to n8n's data model, round out this read with our guide on JavaScript expressions to manipulate item contents with precision, and the one on the Merge node to join data coming from multiple sources.