# Split in batches

Splits a list into smaller batches so downstream work can loop safely.

## Configuration

| Field | Role |
| --- | --- |
| **Input ctx key** | Path to the list: `last_output`, `input.items`, `event.body.items`, etc. The resolved value must be an array. |
| **Batch size** | Number of items per batch, from 1 to 1,000 (default 10). |

Use the **Batch** branch for processing and **Done** for completion. Batches run sequentially, not in parallel. The Batch branch executes once per chunk; the Done branch executes exactly once after every chunk has completed. With an empty input list, Batch is skipped and execution goes directly to Done.

## Example

For 250 customers and a batch size of 100:

```
250 customers
├── Batch 1: 100 customers
├── Batch 2: 100 customers
├── Batch 3:  50 customers
└── Done
```

A typical workflow is:

```
HTTP Request → Split In Batches
                  ├── Batch → Process / send the current items
                  └── Done  → Send the final report
```

## Batch payload

During each iteration, downstream nodes on the Batch branch receive this structured value through `last_output_parsed`:

```json
{
  "items": [/* current batch items */],
  "index": 0,
  "number": 1,
  "size": 100,
  "total": 250,
  "batch_count": 3,
  "is_first": true,
  "is_last": false
}
```

Use fields such as `{last_output.items}`, `{last_output.number}`, or `{last_output.is_last}` in the Batch branch.

## Runtime output

After all batches, the Done branch receives a summary containing `total`, `batch_size`, `batch_count`, `processed_batches`, and the collected `results` from each iteration. It is written to `last_output_parsed` and is also available through `{outputs.<node_id>.parsed}`.

## When to use it

- Respect an external API's maximum request size.
- Avoid sending thousands of records in one request.
- Keep agent prompts below context/token limits.
- Process file rows or database results progressively.
- Allow a long run to be cancelled between batches.

## Limits and troubleshooting

- Input must resolve to an array; otherwise the node fails with `Split In Batches input must be a list`.
- Batch size is clamped between 1 and 1,000.
- Processing is sequential, so smaller batches improve control but increase total execution time.
- Do not connect the Batch branch back to the Split In Batches node: the executor already performs the iteration.
- If a node in the Batch branch fails, batch processing stops and the Split In Batches error policy is applied.

## Example workflow

Use the workflow card below to create a working example in the editor. It uses safe sample data and avoids external side effects unless the node itself is an outbound integration.

---

*Source: https://agentbuilder.systalink.sn/docs/node-split-in-batches — human documentation.*
*Other language: [/docs-md/fr/node-split-in-batches.md](/docs-md/fr/node-split-in-batches.md).*
*Machine-readable index: [/llms.txt](/llms.txt).*