Loop Over Items

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.

Example settings

{
  "batchSize": 1,
  "concurrency": 1,
  "maxIterations": 10000,
  "iterationRetryCount": 0,
  "failurePolicy": "stop",
  "perItemTimeoutMs": 30000
}

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

List Folder → Filter → Loop Over Items.
Connect Loop to the body and Done to aggregation.
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:

Default node configuration

{
  "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.

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.

Node reference

Triggers

Logic

Data

Network

Browser

Communication

System

When to use this node

Example: Process approved files sequentially

Configuration

Workflow JSON

Inputs

Outputs

Execution behavior

Common issues

Where it can run

Test and inspect

​When to use this node

​Example: Process approved files sequentially

​Configuration

​Workflow JSON

​Inputs

​Outputs

​Execution behavior

​Common issues

​Where it can run

​Test and inspect

​Related guides

When to use this node

Example: Process approved files sequentially

Configuration

Workflow JSON

Inputs

Outputs

Execution behavior

Common issues

Where it can run

Test and inspect

Related guides