> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sndbox.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Loop Over Items

> Process a bounded collection in deterministic batches. Exact configuration, ports, placement, and execution behavior.

**Node type:** `loop_over_items` · **Version:** `1` · **Category:** Logic

Process a bounded collection in deterministic batches. sndbox classifies this node as side-effecting, so tests or automatic runs can require additional confirmation and permission review.

## When to use this node

* Run a visible body once per item or deterministic batch.
* Bound parallel item processing while retaining item identity and attempts.

## Example: Process approved files sequentially

Filter a folder listing, then process one approved path at a time.

```json title="Example settings" theme={"system"}
{
  "batchSize": 1,
  "concurrency": 1,
  "maxIterations": 10000,
  "iterationRetryCount": 0,
  "failurePolicy": "stop",
  "perItemTimeoutMs": 30000
}
```

This shows the important settings, not a complete exported node.

1. List Folder → Filter → Loop Over Items.
2. Connect Loop to the body and Done to aggregation.
3. Review side-effect warnings before increasing concurrency.

## Configuration

| Field                 | Type   | Default  | What it controls                                                                   |
| --------------------- | ------ | -------- | ---------------------------------------------------------------------------------- |
| `batchSize`           | number | `1`      | Number of items in one deterministic iteration batch.                              |
| `concurrency`         | number | `1`      | Maximum active body iterations.                                                    |
| `maxIterations`       | number | `10000`  | Hard iteration bound.                                                              |
| `iterationRetryCount` | number | `0`      | Retries an individual iteration with the same stable identity.                     |
| `failurePolicy`       | string | `"stop"` | Stop or continue after a handled item failure. Values: `stop`, `continue_handled`. |
| `perItemTimeoutMs`    | number | `30000`  | Timeout applied to each body node in an iteration.                                 |

## Workflow JSON

The editor stores this node with the following implemented default configuration:

```json title="Default node configuration" theme={"system"}
{
  "type": "loop_over_items",
  "version": 1,
  "configuration": {
    "batchSize": 1,
    "concurrency": 1,
    "maxIterations": 10000,
    "iterationRetryCount": 0,
    "failurePolicy": "stop",
    "perItemTimeoutMs": 30000
  }
}
```

Values may be entered literally or mapped from an earlier compatible output when the inspector exposes a mapping control. See [Variables and data mapping](/workflows/variables-and-data).

## Inputs

| Port    | Type    | Required | Description |
| ------- | ------- | -------- | ----------- |
| `items` | `array` | Yes      | Items       |

## Outputs

| Port   | Type    | Required | Description |
| ------ | ------- | -------- | ----------- |
| `loop` | `array` | No       | Loop        |
| `done` | `array` | No       | Done        |

## Execution behavior

* Batch membership and iteration IDs are deterministic; concurrency greater than one may complete out of order.
* Iteration retry reuses identity, cancellation reaches active bodies, and exactly-once side effects are not promised.
* The editor catalogue declares `loop` (array), `done` (array) for mapping. The execution inspector can contain additional evidence fields; inspect a real result before selecting nested paths from object or any outputs.

## Common issues

* Both Loop and Done outputs must be connected.
* Keep a finite maximum iteration count and use idempotent downstream mutations.

## Where it can run

* Desktop local runner
* Paired self-hosted runner
* Hosted runner

## Test and inspect

Use **Test node** in the editor to preview this step with the current configuration. A full run records resolved inputs, outputs, logs, duration, and any artifacts in the execution inspector. Side-effecting or destructive nodes can require an additional confirmation or approved workflow permission.

## Related guides

* [Loops and recovery](/workflows/collections-and-items)
* [Retries and recovery](/execution/retries-and-recovery)