Overview
The Iterator node is designed to facilitate iterative workflows in n8n, such as paginating through API results or processing data in chunks. It supports two main iteration strategies: auto-incrementing a numeric value (useful for offset-based pagination) and referencing the "next" value (useful for cursor- or token-based pagination). The node can accumulate results across iterations and control when to stop looping based on various criteria.
Common scenarios:
- Paginating through large datasets from APIs that use either offset/limit or next-page tokens.
- Building loops that require custom exit conditions, such as reaching a maximum number of items or iterations.
- Combining results from multiple iterations before passing them downstream.
Practical examples:
- Fetching all pages of a REST API by incrementing an offset until no more results are returned.
- Using a "next page" token from an API response to fetch subsequent pages.
- Collecting all items from multiple requests and outputting them as a single array when done.
Properties
| Name | Type | Meaning |
|---|---|---|
| Iterator Type | options | Selects the iteration strategy: "Auto Increment" (numeric offset) or "Reference Next" (token/cursor). |
| Increment Start | number | Starting value for the auto-increment counter (used if Iterator Type is "Auto Increment"). |
| Increment Size | number | Step size for each increment (used if Iterator Type is "Auto Increment"). |
| Reference Start | string | Initial reference value (used if Iterator Type is "Reference Next"). |
| Reference Next | string | Value for the next reference/token (used if Iterator Type is "Reference Next"). |
| Options > Expected Item Count | number | Minimum number of items expected per iteration; used to determine if the loop should continue. |
| Options > Is There Another Page | boolean | Indicates if another page exists; can be set dynamically from API responses. |
| Options > Combine | boolean | If true, accumulates all items across iterations and outputs them together when done. |
| Options > Limit | number | Maximum number of results to return in total. |
| Options > Iteration Limit | number | Maximum number of iterations to perform before stopping. |
Output
The node produces two possible outputs:
Done (Output 0):
- When the iteration is complete (based on limits, item count, or no more pages), this output contains the accumulated results.
- If "Combine" is enabled, all collected items are output as an array.
- If "Limit" is set, only up to the specified number of items are included.
- Each item is an object with a
jsonproperty containing the data passed through the node.
Iterate (Output 1):
- During ongoing iterations, this output emits the last received input item, allowing the workflow to continue looping.
Example output structure (Done):
[
{
"json": { /* data from one iteration */ }
},
{
"json": { /* data from another iteration */ }
}
]
Note:
- No binary data is produced by this node.
Dependencies
- No external services or API keys required.
- The node relies solely on n8n's built-in context and parameter mechanisms.
Troubleshooting
Common issues:
- Infinite Loops: If neither a limit nor an iteration limit is set, the node may loop indefinitely if the exit condition is never met.
- Unexpected Early Exit: If "Expected Item Count" is set higher than the actual number of items returned, the loop may terminate prematurely.
- No Output: If the input data is empty or filtered out, the Done output may be empty.
Error messages and resolutions:
- No explicit error messages are thrown by the node itself. However, misconfiguration (such as missing required parameters for the selected iterator type) may result in unexpected behavior or empty outputs.
- Ensure that the correct properties are set for the chosen "Iterator Type".
- Set reasonable values for "Iteration Limit" and "Limit" to avoid excessive looping.