---
title: "Iteration"
description: "Process arrays by applying workflows to each element"
icon: "arrows-rotate"
---

The Iteration node processes arrays by running the same workflow steps on each element sequentially or in parallel. Use it for batch processing tasks that would otherwise hit limits or be inefficient as single operations.

<Frame caption="Iteration node processing workflow">
  <img src="https://assets-docs.dify.ai/2025/04/5f3f124c16b9e3565853f125f7db0e32.png" alt="Iteration node overview" />
</Frame>

## How Iteration Works

The node takes an array input and creates a sub-workflow that runs once for each array element. During each iteration, the current item and its index are available as variables that internal nodes can reference.

**Core Components:**
- **Input Variables** - Array data from upstream nodes  
- **Internal Workflow** - The processing steps to perform on each element
- **Output Variables** - Collected results from all iterations (also an array)

## Configuration

### Array Input

Connect an array variable from upstream nodes such as Parameter Extractor, Code nodes, Knowledge Retrieval, or HTTP Request responses.

### Built-in Variables

Each iteration provides access to:
- `items[object]` - The current array element being processed
- `index[number]` - The current iteration index (starting from 0)

### Processing Mode

<Tabs>
  <Tab title="Sequential Mode">
    **Sequential Processing** - Items processed one after another in order
    
    **Streaming Support** - Results can be output progressively using Answer nodes
    
    **Resource Management** - Lower memory usage, predictable execution order
    
    **Best For** - When order matters or when using streaming output
  </Tab>
  
  <Tab title="Parallel Mode">
    **Concurrent Processing** - Up to 10 items processed simultaneously
    
    **Improved Performance** - Faster execution for independent operations
    
    **Batch Processing** - Handles large arrays efficiently
    
    **Best For** - Independent operations where order doesn't matter
  </Tab>
</Tabs>

<Frame caption="Sequential vs parallel processing comparison">
  <img src="https://assets-docs.dify.ai/2024/12/2656dec26d6357556a280fcd69ccd9a7.png" alt="Processing mode comparison" />
</Frame>

<Frame caption="Enable parallel mode in iteration settings">
  <img src="https://assets-docs.dify.ai/2024/12/516af5e7427fce9a58fa9d9b583230d4.png" alt="Parallel mode setting" />
</Frame>

## Error Handling

Configure how to handle processing failures for individual array elements:

**Terminate** - Stop processing when any error occurs and return the error message

**Continue on Error** - Skip failed items and continue processing, outputting null for failed elements

**Remove Failed Results** - Skip failed items and return only successful results

Input-output correspondence examples:
- Input: `[1, 2, 3]` 
- Output with Continue on Error: `[result-1, null, result-3]`
- Output with Remove Failed: `[result-1, result-3]`

## Long Article Generation Example

Generate lengthy content by processing chapter outlines individually:

<Frame caption="Long article generation workflow">
  <img src="https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/workflow/node/3a403551d48b178d0a41ce2a5748dd2d.png" alt="Long story generator" />
</Frame>

**Workflow Steps:**

1. **Start Node** - User provides story title and outline
2. **LLM Node** - Generate detailed chapter breakdown  
3. **Parameter Extractor** - Convert chapter list to structured array
4. **Iteration Node** - Process each chapter with internal LLM
5. **Answer Node** - Stream chapter content as it's generated

<Frame caption="Start node configuration for story input">
  <img src="https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/workflow/node/3af1c2ed0df00f19e584bcf511302f55.png" alt="Start node setup" />
</Frame>

<Frame caption="Parameter extraction for chapter structure">
  <img src="https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/workflow/node/d3beee536ff3c35f4e1eb1ab610f35d7.png" alt="Parameter extraction setup" />
</Frame>

<Frame caption="Iteration configuration with LLM processing">
  <img src="https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/workflow/node/ac91582998868004b298afe2f04e5589.png" alt="Iteration node configuration" />
</Frame>

<Info>
  Parameter extraction effectiveness depends on model capabilities and instruction quality. Use stronger models and provide examples in instructions to improve results.
</Info>

## Output Processing

Iteration nodes output arrays that often need conversion for final use:

### Convert Array to Text

<Tabs>
  <Tab title="Using Code Node">
    ```python
    def main(articleSections: list):
        return {
            "result": "\n".join(articleSections)
        }
    ```
    
    <Frame caption="Code node array conversion">
      <img src="https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/workflow/node/8be2372b00a802e981efe6f0ceff815b.png" alt="Code node conversion" />
    </Frame>
  </Tab>
  
  <Tab title="Using Template Node">
    ```jinja2
    {{ articleSections | join("\n") }}
    ```
    
    <Frame caption="Template node array conversion">
      <img src="https://assets-docs.dify.ai/dify-enterprise-mintlify/en/guides/workflow/node/8c0bcc5de453dea2776d2755449bd971.png" alt="Template node conversion" />
    </Frame>
  </Tab>
</Tabs>

## Common Use Cases

**Token Limit Management** - Break large texts into chunks for translation, summarization, or analysis when content exceeds LLM context windows.

**Batch Processing** - Apply the same operations to multiple items efficiently, such as processing multiple documents or API calls.

**Quality Control** - Process items individually to maintain quality and handle errors gracefully rather than risking entire batch failures.

**Progressive Output** - Stream results as they complete instead of waiting for all processing to finish.

## Best Practices

**Choose Appropriate Mode** - Use sequential for ordered processing or streaming, parallel for independent operations requiring speed.

**Handle Errors Gracefully** - Configure error handling based on whether partial failures should stop processing or be skipped.

**Optimize Internal Workflows** - Keep iteration sub-workflows efficient since they run multiple times.

**Monitor Resource Usage** - Large arrays with complex processing can consume significant resources, especially in parallel mode.