> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryblend.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Lists & single values
> Why a single value runs the next node once and a list runs it once per item — plus items vs. parts, structured-list fan-out, failures, and the API shape.
This is the rule that decides how many times the rest of your workflow runs.
* A **single value** runs the next node **once**.
* A **list** runs it **once per item** — N items means N runs of that node, and everything downstream of it. The result pairs each input with the output it produced.
That's the whole mental model. Everything else follows from it.
## Items, not parts
Nodes move **items** between each other. An item is one logical unit of work, and a node runs **once per item** — not once per part inside it. A single value is one item; a list is several.
The distinction matters because one item can carry *many parts*. A single image-generation call might return four image parts, but it's still **one item**, so the next node runs once and receives all four parts together.
| Shape | Downstream runs |
| -------------------------- | --------------- |
| One item, one text part | 1 |
| One item, four image parts | 1 |
| Four separate items | 4 |
So "many things" is not the same as "a list." What multiplies your runs is the number of **items**, not the number of parts.
## Lists come from Batch
A [Batch](/workflow/nodes/batch) node is what turns a single value into a list of items. It's fan-out — a `for value in list` loop. Three rows in a Batch means three runs.
**Example.** A Batch of three prompts — `a cat`, `a dog`, `a fox` — wired into an LLM node makes that node run three times, once per prompt. You get three outputs, each paired with the prompt that produced it. If those three outputs feed an Image Gen node, it runs three times too — the fan-out continues downstream.
## LLM structured-list output
A Batch isn't the only way to make a list. An [LLM](/workflow/nodes/llm) node with structured output can emit one too — it depends on the shape of the schema:
| Structured output | Downstream behavior |
| ----------------------------------------------------------- | ------------------------------------------------------------------------------ |
| Scalar fields (for example `title`, `score`, or `category`) | **One item** with a named handle per field. |
| Exactly one list field and no other fields | **One item per element**—downstream runs once per element, exactly like Batch. |
| Scalars mixed with a list | **One item**. The list field is JSON array text on its named handle. |
| Multiple list fields | **One item** with each list serialized on its own handle. |
Structured fields support strings, numbers, enums, and list versions of all three. A list fans out only when it is the schema's sole field.
An LLM that already receives multiple items cannot also use list-shaped response fields. This prevents nested list-of-lists fan-out.
## Two lists multiply
Point two lists at the same downstream node and the runs **multiply** — the node runs once per *combination* (a Cartesian product). A list of 3 and a list of 2 into one node is **3 × 2 = 6** runs. There's no "zip" mode: if two handles each receive a list, expect the combinations to multiply.
Combinations and cost grow fast. Three lists of 10 reaching one node is 10 × 10 × 10 = **1,000 runs**, and each run costs credits. Check the run count before you launch.
## A collection is a value, not a list
A [Collection](/workflow/nodes/collection-read) of images looks like "many things", but it's passed as a **single item**. Every file rides along as a separate part of that one item — so the downstream node runs **once** over the whole set.
A Collection does **not** fan out by itself. To run once **per file**, connect it to a [Batch](/workflow/nodes/batch) file row and enable **Explode**. Leaving that row in **Set** mode keeps the collection together as one item.
## Choose Output collapses or keeps a list
[Choose Output](/workflow/nodes/output-comparison) lets you pause and pick, and the mode decides whether a list survives:
| Mode | Downstream behavior |
| -------------------- | ----------------------------------------------------------------- |
| **Single choice** | One item continues — the next node runs once. |
| **Multiple choices** | Every selected item continues — the next node runs once per item. |
## Failed items
Failures are tracked **per item**. If one of six items fails:
* The node's result becomes **partial**.
* Successful items keep flowing downstream.
* The failed item stays visible in results with its status and error.
* User Result nodes and the API keep item boundaries intact, so you can tell exactly which item failed.
One bad item doesn't sink the whole run.
## In the API
When you publish, lists show up as **arrays** in the [API](/introduction). A field fed by a list becomes an **array input** — the caller passes several values and the workflow runs once per entry. On the way out, each Result field comes back as an **array of output items**, where each item carries an `id`, `item_index`, `status`, and `parts`.
```json theme={null}
{
"output": {
"caption": [
{
"id": "item_1",
"item_index": 0,
"status": "completed",
"parts": [
{ "type": "text", "text": "A cat on the moon." }
]
}
]
}
}
```
See [Output parts](/parts) for the full response shape.
## Related
The node that turns a single value into a list and fans the chain out.
A set of files passed as one item—until Batch Explode separates the files.