Skip to main content
The Batch node turns one downstream field into several values. Connect its output to an editable field, add values, and the downstream chain runs once for each emitted item. For scalar fields, each row is normally one item. For file fields, each row is a set of files and you choose whether to keep that set together or Explode it into one item per file.

​
How fan-out works

1

Connect Batch to a field

Drag the Batch output to an editable field on a downstream node, such as an LLM prompt, model selector, generation parameter, or file upload. Batch copies that field’s label, type, and control.
2

Add values

Add scalar rows, or choose files for a file row. The node’s badge shows the current row count or that it is using a dynamic list.
3

Choose Set or Explode for files

A file row defaults to Set, which keeps all files together in one item. Switch it to Explode to emit one item per file.
4

Run

Each emitted item runs the connected node and its downstream chain once.
Scalar example. Three prompt rows—a cat, a dog, and a fox—make the connected LLM run three times. File example. One row containing ten product images behaves differently by mode:
Batch stays one node on the canvas. It is the output items—not the number of visible nodes—that multiply downstream runs.

​
Set vs. Explode

Set and Explode are available on file rows when the row contains multiple files or receives files from an upstream connection.
  • Set keeps every file in the row together. Use it when a model should see the whole reference set in one call.
  • Explode separates the files. Use it when the same chain should process each file independently.
  • Each file row makes its own choice, so one row can remain a set while another explodes.
To run once per file from a Collection, connect the Collection’s Files output to a Batch file row and enable Explode. A Collection by itself, or a Batch row left in Set mode, remains one bundled item.

​
Static and dynamic lists

A scalar Batch can get its values in two ways:
  • Static rows — enter values directly in the Batch node with Add one more.
  • Dynamic list — connect a User Input to the Batch’s User input handle. The User Input becomes a repeated list editor used by the canvas, published Runner, and API.
Dynamic User Input lists can contain up to 25 items. The caller can add and remove items without changing the workflow graph. File batches keep per-row input handles because every row represents its own file set. Scalar batches use the whole-list User input handle; old workflows with legacy scalar row connections continue to work.

​
Cartesian products

When independent lists reach different fields on the same downstream node, the run count is their Cartesian product. Example: compare models across prompts.
  • Batch A → Model with 3 models.
  • Batch B → Prompt with 2 prompts.
  • The LLM runs 3 × 2 = 6 times, once for every model-and-prompt pairing.
Combinations grow quickly. Three lists of 10 reaching one node create 10 × 10 × 10 = 1,000 runs. Review the displayed run count and price estimate before starting.

​
Inputs

​
Outputs

The output binds to an editable downstream field. It does not connect to arbitrary structural handles such as an Agent’s tool list.

​
Supported field types

Batch supports:
  • Text input and text area
  • Select and tabs
  • Model selector
  • Range and number
  • File/upload fields, including image, video, and audio
Boolean toggles and collection selectors are not batchable. To batch a collection’s files, connect the Collection output to a Batch file row instead of batching the collection selector.

​
Published workflows and API inputs

Batch is internal workflow logic. It becomes caller-editable only when a User Input is connected to its User input handle. That User Input appears as a repeated field in the published Runner and as an array in the API inputs object. The Batch emits one item per supplied scalar value, up to the 25-item limit. File sets configured directly on Batch remain part of the saved workflow. Their Set/Explode choices are saved with each row.

​
Results and cost

  • User Result preserves one output item per successful iteration.
  • Failures are tracked per item, so successful iterations can still complete.
  • Cost scales with emitted items and with downstream Cartesian products.
  • For files, Set counts as one item per row; Explode counts one item per file.

​
Next steps

Lists & single values

Understand items, file parts, fan-out, and Cartesian products.

Collection node

Supply a reusable file bundle and optionally explode it with Batch.