<!-- BusyBot node reference — https://busybot.net/tools/split-out/ -->

> Node: Split Out (`split_out`) · Action · v1
> Category: Core Nodes · Credentials: none
> Updated: 2026-08-16

# Split Out

> Loop through array items one by one

## Overview

Separates a single item containing an array into multiple individual items. Essential for processing API responses where data is returned as a list within a single object.

**Category:** Core Nodes  
**Tool Name:** `split_out`  
**Version:** 1

**Appearance:** Icon: `splitOut` | Color: `#ec4899`

## Node Type

**Action** — processes input items and produces output

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## Credentials

This tool does not require any credentials.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Field To Split Out | `string` | Yes | — | The name of the field containing the array to split. Use dot notation for nested fields (e.g., 'results.items', 'data.records'). Supports expressions like {{ $json.arrayFieldName }}. |
| Include | `options` | Yes | `noOtherFields` | Determines which other fields from the original item are included in each split output item. |
| | | | | Options: `noOtherFields` (only include the data from the split array), `allOtherFields` (include all other fields from the original item in each split item), `selectedOtherFields` (include only specific fields from the original item) |
| Fields To Include | `string` | No | — | Comma-separated list of field names to include when 'Include' is set to 'Selected Other Fields'. Supports dot notation for nested fields (e.g., 'id, metadata.timestamp, user.name'). _(shown when Include is `selectedOtherFields`)_ |
| Options | `collection` | No | `{}` | Additional options for controlling split behavior. |
| — Destination Field Name | `string` | No | — | If set, places the split data under this field name instead of at the root level. For example, setting 'item' would output `{ item: <splitData> }` instead of `<splitData>` directly. |
| — Disable Dot Notation | `boolean` | No | `false` | When enabled, dots in field names are treated literally rather than as nested path separators. Enable this if your field names contain actual dots. |
| — Include Binary | `boolean` | No | `false` | When enabled, binary data (if any) from the input item is passed through to all split output items. |
| Max Concurrency | `number` | No | `100` | Maximum number of input items to process concurrently. |

## Output Data

This node changes how many items are in flight: one input item becomes **one output item per element** of the array at Field To Split Out. An input item whose array is empty produces no output items at all, and an input item whose named field is missing or is not an array is an item error. Binary data is forwarded to every split item only when Include Binary is on.

Each output item is built like this:

- With **Destination Field Name** set, the element is placed whole under that name — `{ "item": <element> }`.
- With no Destination Field Name, an element that is a plain object is merged at the root of the output item, so its own keys become the item's fields. Anything else — a string, number, boolean, or nested array — is wrapped under the key `value`.
- Whatever Include selects is added alongside: nothing (`noOtherFields`), every other field of the original item (`allOtherFields` — the split field itself is removed), or just the fields named in Fields To Include (`selectedOtherFields`).

Every output item also carries `_splitMeta`, describing where it came from:

```json
{
  "_splitMeta": {
    "sourcePointer": "...",
    "sourceField": "data.users",
    "arrayIndex": 0,
    "arrayLength": 3
  }
}
```

`sourceField` is the resolved path that was split, `arrayIndex` is the element's position in that array and `arrayLength` its total length — useful for numbering or for detecting the last item downstream. `sourcePointer` is an internal reference to the item this one was split from.

Reference the split element downstream by expression, e.g. `{{ $json.id }}` when elements are objects, or `{{ $json.value }}` when they are not.

## Usage Examples

- loop through each item in the list
- process every element one by one
- split the array into individual items
- iterate over the results
- go through each row separately

## Example Configuration

Basic split, no other fields:

```json
{
  "type": "split_out",
  "parameters": {
    "fieldToSplitOut": "data.users",
    "include": "noOtherFields"
  }
}
```

Split with all other fields:

```json
{
  "type": "split_out",
  "parameters": {
    "fieldToSplitOut": "results.items",
    "include": "allOtherFields",
    "maxConcurrency": 50
  }
}
```

Split with selected fields only:

```json
{
  "type": "split_out",
  "parameters": {
    "fieldToSplitOut": "response.records",
    "include": "selectedOtherFields",
    "fieldsToInclude": "id, metadata.timestamp, status"
  }
}
```

Advanced split with options:

```json
{
  "type": "split_out",
  "parameters": {
    "fieldToSplitOut": "api.data.entries",
    "include": "selectedOtherFields",
    "fieldsToInclude": "requestId, user.email",
    "options": {
      "destinationFieldName": "item",
      "disableDotNotation": false,
      "includeBinary": true
    }
  }
}
```

Split an API response containing multiple records:

```json
{
  "type": "split_out",
  "parameters": {
    "fieldToSplitOut": "data.results",
    "include": "allOtherFields"
  }
}
```

Split an array but preserve only essential metadata:

```json
{
  "type": "split_out",
  "parameters": {
    "fieldToSplitOut": "orders.items",
    "include": "selectedOtherFields",
    "fieldsToInclude": "orderId, customerId, timestamp"
  }
}
```

Split deeply nested arrays with a custom output structure:

```json
{
  "type": "split_out",
  "parameters": {
    "fieldToSplitOut": "response.data.transactions.list",
    "include": "noOtherFields",
    "options": {
      "destinationFieldName": "transaction",
      "includeBinary": false
    }
  }
}
```

When field names contain actual dots rather than path separators:

```json
{
  "type": "split_out",
  "parameters": {
    "fieldToSplitOut": "data.records",
    "include": "selectedOtherFields",
    "fieldsToInclude": "user.email.address, config.api.key",
    "options": {
      "disableDotNotation": true
    }
  }
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

Takes an array field within each item and splits it into separate output items, one per array element. Use when a previous tool produced items containing arrays that need to be processed individually. Produces N items from each input item, where N is the length of the specified array field.