n8n Aggregate Node

n8n processes data as individual items, but APIs and databases often expect arrays. Your workflow pulls 50 customer records from a spreadsheet. Each record becomes a separate item in n8n. But the API you need to call accepts a single request with an array of customers. Without a way to combine those 50 items into one, you’re stuck making 50 API calls instead of 1.

The Aggregate node solves this fundamental mismatch. It takes multiple items flowing through your workflow and combines them into a single item containing an array. Think of it like packing individual items into a box before shipping.

The Multi-Item Problem

n8n’s power comes from processing items individually. Each item flows through nodes, gets transformed, filtered, and routed. But this item-by-item approach creates friction when you need to:

• Send a batch of records to an API endpoint that expects an array
• Collect results from a loop before continuing the workflow
• Combine paginated API responses into a complete dataset
• Prepare a single email containing data from multiple sources

Without aggregation, you end up with workarounds: complicated Code nodes, nested loops, or hitting API rate limits with excessive individual requests.

What the Aggregate Node Actually Does

The Aggregate node takes items from your workflow and combines them:

• Collects multiple items into a single output item
• Preserves all data from each original item
• Creates arrays containing the aggregated values
• Supports two modes for different aggregation needs
• Handles binary data like files and images when needed

The result is one item that contains an array of all the original items (or specific fields from them). This single item then continues through your workflow, ready for nodes that expect array inputs.

What You’ll Learn

• How to choose between Individual Fields and All Item Data modes
• Step-by-step configuration for combining workflow items
• The critical difference between Aggregate, Merge, and Summarize nodes
• Real-world patterns for batch API requests and loop aggregation
• Common mistakes that cause unexpected nested arrays
• Best practices for production-ready aggregation workflows

When to Use the Aggregate Node

Before configuring the node, understand when Aggregate is the right choice versus other data manipulation nodes.

Scenario	Best Choice	Why
Combine 50 records into single API payload	Aggregate	Creates array from multiple items
Collect results after Split in Batches loop	Aggregate	Reassembles items after loop processing
Join data from two different sources	Merge	Merge handles combining separate data streams
Calculate sum, average, or count	Summarize	Summarize performs mathematical aggregations
Rename or restructure fields	Edit Fields	Field transformation, not aggregation
Complex array manipulation	Code node	Full JavaScript control when nodes aren’t enough
Combine paginated API responses	Aggregate	Collects all pages into single dataset
Group items by category before processing	Aggregate + Summarize	Aggregate collects, Summarize groups

Rule of thumb: Use Aggregate when you need to turn multiple items into one item containing an array. Use Merge when combining separate data streams. Use Summarize when you need calculations like sums or counts.

Understanding the Two Modes

The Aggregate node offers two distinct modes for combining data. Choosing the right mode determines how your output is structured.

Individual Fields Mode

Best for: Collecting specific fields from items into separate arrays.

Individual Fields mode lets you select which fields to aggregate. Each field you choose becomes a separate array in the output.

Example input (3 items):

[
  { "name": "Alice", "email": "[email protected]", "score": 85 },
  { "name": "Bob", "email": "[email protected]", "score": 92 },
  { "name": "Carol", "email": "[email protected]", "score": 78 }
]

Individual Fields configuration: Aggregate the name and email fields.

Output (1 item):

{
  "name": ["Alice", "Bob", "Carol"],
  "email": ["[email protected]", "[email protected]", "[email protected]"]
}

Notice that score is not included because it wasn’t selected. Each field becomes its own array.

All Item Data Mode

Best for: Preserving complete items as an array of objects.

All Item Data mode takes each entire item and adds it to an array. Nothing is filtered out.

Same input (3 items):

[
  { "name": "Alice", "email": "[email protected]", "score": 85 },
  { "name": "Bob", "email": "[email protected]", "score": 92 },
  { "name": "Carol", "email": "[email protected]", "score": 78 }
]

All Item Data configuration: Put output in field users.

Output (1 item):

{
  "users": [
    { "name": "Alice", "email": "[email protected]", "score": 85 },
    { "name": "Bob", "email": "[email protected]", "score": 92 },
    { "name": "Carol", "email": "[email protected]", "score": 78 }
  ]
}

All original data is preserved within the users array.

Mode Comparison

Feature	Individual Fields	All Item Data
Output structure	Separate array per field	Single array of complete objects
Field selection	Choose specific fields	Includes all fields automatically
Best for	API expecting specific arrays	API expecting array of objects
Data loss risk	Yes, unselected fields excluded	No, all data preserved
Output field naming	Uses original field names	You specify the containing field name

When to Choose Each Mode

Choose Individual Fields when:

• The API expects separate arrays for each data type
• You only need specific fields, not complete records
• You want to rename fields during aggregation
• Reducing payload size matters

Choose All Item Data when:

• The API expects an array of complete objects
• You need to preserve all fields from original items
• You’re unsure which fields might be needed later
• Simplicity is more important than payload optimization

Your First Aggregate

Let’s build a simple aggregation step by step: combining customer records for a batch API request.

Step 1: Add the Aggregate Node

1. Open your n8n workflow
2. Click + to add a node
3. Search for “Aggregate”
4. Click to add it to your canvas
5. Connect it to your data source

Step 2: Choose the Mode

For this example, we want complete customer records in an array:

1. Set Aggregate to “All Item Data”
2. In Put Output in Field, enter customers

Step 3: Test the Node

If you have sample data from a previous node:

1. Click Test step
2. Examine the output panel
3. You should see one item with a customers array

Before Aggregate (5 items):

Item 0: { "id": 1, "name": "Customer A" }
Item 1: { "id": 2, "name": "Customer B" }
Item 2: { "id": 3, "name": "Customer C" }
Item 3: { "id": 4, "name": "Customer D" }
Item 4: { "id": 5, "name": "Customer E" }

After Aggregate (1 item):

{
  "customers": [
    { "id": 1, "name": "Customer A" },
    { "id": 2, "name": "Customer B" },
    { "id": 3, "name": "Customer C" },
    { "id": 4, "name": "Customer D" },
    { "id": 5, "name": "Customer E" }
  ]
}

Step 4: Use the Aggregated Data

Now your HTTP Request node can send the entire array in one request:

{
  "customers": {{ $json.customers }}
}

One API call instead of five. Faster, cleaner, and respects rate limits.

Individual Fields Mode Deep Dive

When you need to aggregate specific fields separately, Individual Fields mode provides granular control.

Configuration Options

Input Field Name

The field from your input items to aggregate. You can add multiple fields, and each becomes a separate array in the output.

Rename Field

Optionally give the aggregated field a different name. Useful when the downstream API expects a specific field name.

Input Field	Rename To	Result
email	email_addresses	Output field is email_addresses
customer_id	ids	Output field is ids

Merge Lists

When your input field is already an array, this option flattens nested arrays.

Without Merge Lists:

{
  "tags": [["urgent", "review"], ["pending"], ["approved", "shipped"]]
}

With Merge Lists enabled:

{
  "tags": ["urgent", "review", "pending", "approved", "shipped"]
}

Enable this when you want a flat array instead of an array of arrays.

Keep Missing And Null Values

By default, null and missing values are skipped. Enable this to include null placeholders.

Input:

[
  { "name": "Alice", "nickname": "Ali" },
  { "name": "Bob", "nickname": null },
  { "name": "Carol" }
]

Without Keep Missing And Null Values:

{ "nickname": ["Ali"] }

With Keep Missing And Null Values:

{ "nickname": ["Ali", null, null] }

Enable this when you need position correspondence between aggregated arrays.

Individual Fields Example

Scenario: Your e-commerce API expects separate arrays for product IDs and quantities.

Input (3 items):

[
  { "product_id": "SKU001", "quantity": 2, "price": 29.99 },
  { "product_id": "SKU002", "quantity": 1, "price": 49.99 },
  { "product_id": "SKU003", "quantity": 5, "price": 9.99 }
]

Configuration:

• Aggregate: Individual Fields
• Field 1: Input Field Name = product_id, Rename To = product_ids
• Field 2: Input Field Name = quantity, Rename To = quantities

Output:

{
  "product_ids": ["SKU001", "SKU002", "SKU003"],
  "quantities": [2, 1, 5]
}

Notice that price is excluded because it wasn’t configured.

All Item Data Mode Deep Dive

All Item Data mode is simpler: take everything and put it in an array.

Configuration Options

Put Output in Field

The name of the field that will contain your array of items. Choose a name that makes sense for your use case:

• users for user records
• orders for order data
• results for generic results
• items for general-purpose arrays

Include Binaries

When your items contain binary data (files, images, documents), enable this to include them in the aggregated output.

Enable when:

• Preparing multiple files for email attachments
• Collecting downloaded images for batch processing
• Aggregating PDF files for merging

Leave disabled when:

• Working only with JSON data
• Binary data isn’t needed downstream
• Reducing memory usage matters

All Item Data Example

Scenario: Combine API search results for a report generation workflow.

Input (4 items from paginated API):

[
  { "id": 1, "title": "First Result", "score": 0.95 },
  { "id": 2, "title": "Second Result", "score": 0.87 },
  { "id": 3, "title": "Third Result", "score": 0.82 },
  { "id": 4, "title": "Fourth Result", "score": 0.79 }
]

Configuration:

• Aggregate: All Item Data
• Put Output in Field: search_results

Output:

{
  "search_results": [
    { "id": 1, "title": "First Result", "score": 0.95 },
    { "id": 2, "title": "Second Result", "score": 0.87 },
    { "id": 3, "title": "Third Result", "score": 0.82 },
    { "id": 4, "title": "Fourth Result", "score": 0.79 }
  ]
}

All fields preserved. Ready for the next node that expects this structure.

Aggregate vs Merge vs Summarize

This comparison causes the most confusion. Understanding the differences prevents hours of debugging wrong node choices.

Quick Definitions

Aggregate: Combines multiple items into ONE item containing arrays. Items come from the same data stream.

Merge: Combines items from TWO OR MORE separate data streams. Like SQL joins.

Summarize: Performs calculations (sum, count, average) on items. Like Excel pivot tables.

Detailed Comparison

Aspect	Aggregate	Merge	Summarize
Input streams	One	Two or more	One
Primary purpose	Collect into array	Join different sources	Calculate values
Output	Single item with array	Combined items	Calculated results
Preserves original data	Yes (in array)	Yes (joined)	No (transformed)
Common use	Batch API calls	CRM + order data join	Sales totals

Visual Flow Examples

Aggregate Flow:

Item 1 ─┐
Item 2 ─┼─► [Aggregate] ─► Single item containing [Item 1, Item 2, Item 3]
Item 3 ─┘

Merge Flow:

Stream A (Items) ──┬─► [Merge] ─► Combined items with data from both streams
Stream B (Items) ──┘

Summarize Flow:

Item 1 ─┐
Item 2 ─┼─► [Summarize: Sum of 'amount'] ─► { "sum": 150 }
Item 3 ─┘

Decision Matrix

You want to…	Use
Turn 50 items into 1 array	Aggregate
Combine customer data with order data	Merge
Count how many items match a criteria	Summarize
Prepare batch payload for API	Aggregate
Calculate total sales	Summarize
Match users from different databases	Merge
Collect loop results	Aggregate
Group and count by category	Summarize

For more on workflow architecture, see our workflow best practices guide.

Real-World Examples

Example 1: Batch Items for Single API Request

Scenario: Your CRM limits API calls but accepts bulk updates with up to 100 records per request.

Workflow:

1. Spreadsheet node returns 250 customer updates
2. Loop Over Items splits into batches of 100
3. Aggregate collects each batch
4. HTTP Request sends batch to CRM

Aggregate Configuration:

• Mode: All Item Data
• Put Output in Field: contacts

HTTP Request Body:

{
  "contacts": {{ $json.contacts }}
}

Result: 3 API calls instead of 250.

Example 2: Collect Loop Results

Scenario: Process each order through an AI enrichment step, then aggregate results for a summary report.

Workflow:

1. Database query returns 20 orders
2. Loop processes each through AI node
3. Aggregate collects all enriched orders
4. Generate report from aggregated data

The Pattern:

[Get Orders] ─► [Split in Batches] ─► [AI Enrichment] ─┐
                       ▲                                │
                       └────────────────────────────────┘
                                    │
                              [Aggregate]
                                    │
                              [Report Node]

Aggregate Configuration:

• Mode: All Item Data
• Put Output in Field: enriched_orders

Example 3: Aggregate Paginated API Responses

Scenario: An API returns 100 results per page. You need all 500 results combined.

Workflow:

1. HTTP Request fetches page 1
2. Check if more pages exist
3. Loop to fetch remaining pages
4. Aggregate all pages into single dataset

Key Insight: Place the Aggregate node AFTER the loop completes, connected to the “done” output of Split in Batches.

HTTP Request Expression:

{{ $json.results }}

Aggregate Configuration:

• Mode: Individual Fields
• Input Field Name: results
• Merge Lists: Enabled (flattens page arrays)

Output:

{
  "results": [/* all 500 items from all pages */]
}

Example 4: Group Items by Category

Scenario: Aggregate products by their category for a category-wise inventory report.

Workflow:

1. Get all products
2. Use Summarize node to group by category
3. For each category, aggregate the products

Note: True grouping requires the Summarize node. Aggregate alone doesn’t group by field values. Combine them:

1. Summarize: Group by category, operation: Collect all product_name
2. Result: One row per category with array of product names

If you need complex grouping logic, the Code node provides full control.

Example 5: Prepare Email with Multiple Attachments

Scenario: Send one email with all invoice PDFs attached.

Workflow:

1. Query database for outstanding invoices
2. Generate PDF for each invoice
3. Aggregate all PDFs
4. Send single email with all attachments

Aggregate Configuration:

• Mode: All Item Data
• Put Output in Field: invoices
• Include Binaries: Enabled

Email Node:

The aggregated binary files are now available as a single collection for attachment.

Common Mistakes and Troubleshooting

Mistake 1: Using Aggregate When Summarize Is Needed

Symptom: You expected a sum or count but got an array.

Cause: Aggregate collects items into arrays. It doesn’t perform calculations.

Fix: Use the Summarize node for sum, count, average, min, max operations.

You want	Wrong choice	Right choice
Total of amount field	Aggregate	Summarize (Sum)
Count of items	Aggregate	Summarize (Count)
Array of amount values	Summarize	Aggregate

Mistake 2: Unexpected Nested Arrays

Symptom: Output has arrays inside arrays when you expected a flat array.

Example:

{
  "tags": [["a", "b"], ["c"], ["d", "e"]]
}

Cause: Input items already contained arrays, and you aggregated those arrays.

Fix: Enable “Merge Lists” in Individual Fields mode to flatten nested arrays:

{
  "tags": ["a", "b", "c", "d", "e"]
}

Mistake 3: Loop Aggregation Not Working

Symptom: Aggregate only contains items from the last loop iteration.

Cause: Aggregate is placed inside the loop instead of after it.

Wrong placement:

[Split in Batches] ─► [Process] ─► [Aggregate] ─┐
         ▲                                       │
         └───────────────────────────────────────┘

Correct placement:

[Split in Batches] ─► [Process] ─┐
         ▲                       │
         └───────────────────────┘
                    │
              (done output)
                    │
              [Aggregate]

Connect Aggregate to the “done” output of Split in Batches, not inside the loop.

Mistake 4: Missing Items in Aggregation

Symptom: Some items from input don’t appear in aggregated output.

Causes:

1. Null values filtered: By default, nulls are skipped. Enable “Keep Missing And Null Values” if you need them.

2. If node filtering: An upstream If node may route items to different paths. Aggregate only sees items on its connected path.

3. Error in previous node: Items that caused errors don’t reach Aggregate.

Debug steps:

1. Check the Aggregate node’s input panel for actual items received
2. Verify upstream node outputs
3. Use our workflow debugger to trace item flow

Mistake 5: Order of Items Lost

Symptom: Aggregated array order doesn’t match original order.

Cause: Parallel execution or async processing can reorder items.

Fix options:

1. Add an index field before processing, sort after aggregation
2. Use expressions to include timestamps for sorting
3. If order matters, avoid parallel execution in your workflow

Pro Tips and Best Practices

1. Name Your Aggregate Nodes Descriptively

Instead of “Aggregate” or “Aggregate1”, use names that describe the aggregation:

• “Batch Customer Records”
• “Collect API Results”
• “Aggregate Order Items”

This makes complex workflows self-documenting.

2. Test with Small Datasets First

Before aggregating 10,000 items, test with 5-10. Verify the output structure matches expectations. Large aggregations can cause memory issues if structured incorrectly.

3. Consider Memory Limits

Aggregating very large numbers of items (hundreds of thousands) into a single array can exhaust memory. For massive datasets:

• Process in batches and save incrementally
• Use database storage instead of in-memory aggregation
• Consider streaming approaches

4. Use Merge Lists for Flat Arrays

When input fields are already arrays and you want a single flat array, always enable “Merge Lists”. This prevents the common nested array problem.

5. Position Aggregate After Loops Correctly

Always connect Aggregate to the “done” output of Split in Batches. The “loop” output goes back for more iterations. Only “done” contains all processed items.

6. Combine with Summarize for Group-By

For true group-by functionality:

1. Use Summarize with “Split By” to group items by a field
2. The Summarize node can collect values into arrays within each group

This handles “aggregate products by category” patterns.

7. Include Timestamps for Debugging

When debugging aggregation issues, add a timestamp field to each item before aggregating. This helps identify order issues and processing delays.

{{ $now.toISO() }}

Test complex expressions using our expression validator.

8. Validate JSON Structure Before API Calls

After aggregating, use an Edit Fields node to verify the structure matches API expectations. This catches issues before they cause API errors.

For production workflows needing expert setup, our workflow development services and consulting packages can help design robust aggregation patterns.

Frequently Asked Questions

When should I use Aggregate vs Merge in n8n?

Use Aggregate when you have multiple items from a single data stream that need to be combined into one item with an array. Common examples: collecting loop results, batching records for an API, combining paginated responses. Use Merge when you have two or more separate data streams that need to be joined together, like combining customer data from one source with order data from another. The key distinction: Aggregate works on one stream of items, Merge joins different streams. If your workflow has multiple paths that converge, you likely need Merge. If you’re collecting items that flow sequentially through one path, you need Aggregate.

How do I aggregate loop results in n8n?

Connect the Aggregate node to the “done” output of the Split in Batches node, not inside the loop. A common mistake is placing Aggregate inside the loop, which only captures the last iteration. The correct pattern: Split in Batches has two outputs - “loop” (which connects back to your processing nodes) and “done” (which fires after all iterations complete). Connect Aggregate to “done” and it will receive all processed items. Configure All Item Data mode with a descriptive field name like processed_items, and the node will output a single item containing an array of everything the loop processed.

Can I group items by a field value before aggregating?

The Aggregate node alone doesn’t support grouping by field values. For true group-by functionality, use the Summarize node instead. In Summarize, set the operation to one of the aggregation types (like “Concatenate” or just pass through values) and use “Split By” to specify the grouping field. For example, to group products by category: configure Summarize with “Split By: category” and it creates separate output items for each category. If you need more complex grouping with JavaScript array methods, the Code node provides full control using methods like reduce() and Object.groupBy().

Why is my Aggregate node outputting nested arrays instead of a flat array?

This happens when your input items already contain arrays in the field you’re aggregating. By default, Aggregate creates an array of the field values - so arrays become arrays of arrays. To fix this, enable the “Merge Lists” option when using Individual Fields mode. This flattens the nested structure into a single-level array. For example, if three items each have a tags field with arrays like ["a","b"], ["c"], and ["d","e"], without Merge Lists you get [["a","b"],["c"],["d","e"]]. With Merge Lists enabled, you get ["a","b","c","d","e"]. If you’re using All Item Data mode and still getting nested arrays, check whether your input structure is already nested before reaching the Aggregate node.

How do I aggregate items from multiple branches in my n8n workflow?

When you have items coming from different workflow branches (like after an If node), you first need to merge those branches before aggregating. Use a Merge node set to “Append” mode to combine the branches into a single stream. Then connect the Aggregate node to the Merge output. The pattern is: If node splits into two paths, each path does its processing, both paths connect to a Merge node (Append mode), and then Aggregate collects all items into an array. Without the Merge step, Aggregate only sees items from whichever branch it’s directly connected to. For complex multi-branch scenarios, consider whether your workflow design could be simplified. Our workflow debugger tool helps visualize item flow through branches.