# Processing Lists

A list is a collection of items, such as form entries, database rows, orders, users, or results returned by an API.

Flowcrafter can narrow a list, organize its items, turn it into text, or run an action for every item. Start by deciding what you want the workflow to produce.

## Choose what to do with the list

| If you want to… | Use | Result |
|---|---|---|
| Run one or more nodes for every item | [For Each](/documentation/flowcrafter/nodes/flow/for-each/) | **Each item** repeats; **Done** runs once afterward |
| Keep only the items that meet certain conditions | [Filter](/documentation/flowcrafter/nodes/flow/filter/) | One shorter list; no routing branch |
| Remove repeated items | [Deduplicate](/documentation/flowcrafter/nodes/flow/deduplicate/) | One list with duplicates removed |
| Organize items by a shared value | [Group By](/documentation/flowcrafter/nodes/flow/group-by/) | One group per value, with all matching items preserved |
| Send known categories down different paths | [Split](/documentation/flowcrafter/nodes/flow/split/) | One branch per non-empty bucket |
| Combine all the items into one block of text | [Format List](/documentation/flowcrafter/nodes/flow/format-list/) | One string for an email or another text field |

These nodes can also be combined. For example, you could filter a list of registrations, remove duplicate email addresses, and then use For Each to contact every remaining person.

:::note[Filter is not a routing node]
Filter evaluates every item and returns one list. It does not take a Yes or No branch. Use [Condition](/documentation/flowcrafter/nodes/logic/condition-entry/) or [Switch](/documentation/flowcrafter/nodes/logic/switch/) to choose a route for the run, or Split when separate list buckets need separate routes.
:::

---

## Decide whether the next action runs once or once per item

This is the most important choice when working with a list.

Use **For Each** when an action needs to happen separately for every item. For example:

- Send a separate email to every registrant;
- Make one API request for every order; or
- Update every matching entry.

Use the other list nodes when you want to produce a new list or one combined result. The next node then runs once with that result.

For example:

- **Filter → Format List → Send Email** creates one email containing the matching items.
- **Filter → For Each → Send Email** sends a separate email for every matching item.
- **Group By → For Each** lets you process each group separately.
- **Split** sends different categories of items down different branches.

---

## Start with a list

Lists can come from many places in a workflow, including:

- Query nodes such as [Get Entries](/documentation/flowcrafter/nodes/actions/get-entries/), Get Users, or Get Database Rows;
- A [Webhook](/documentation/flowcrafter/nodes/triggers/webhook-trigger/) payload;
- An [HTTP Request](/documentation/flowcrafter/nodes/actions/http-request/) response; or
- An AI or other node that returns several items.

For Each processes a list from the node connected directly before it. Filter, Deduplicate, Group By, Split, and Format List can select a list from any earlier node.

:::caution[Using Get Entries with list nodes]
With **Return** set to **Entry IDs only**, Get Entries stores the results separately and outputs only summary data. For Each can still process those stored entries one at a time.

Other list nodes need the actual list in the output. Set **Return** to **Full entries** before sending Get Entries to Filter, Deduplicate, Group By, Split, or Format List.
:::

---

## Common patterns

### Send one summary containing every item

Use **Format List** to turn the items into readable text, then insert that text into an email, notification, or API request.

### Perform the same action for every item

Use **For Each** and place the repeated nodes on its **Each item** branch. Work that should happen only after every item has been processed belongs on **Done**.

![A For Each workflow separates per-item work from the Done route](/documentation/flowcrafter/screenshots/node-for-each-canvas.png)

<details><summary><strong>⚙️ Read the current item with flow tags</strong></summary>

Inside **Each item**, the picker offers runtime flow tags:

| Flow tag | Result |
|---|---|
| `{{ item }}` | Whole current item |
| `{{ item.email }}` | One property from the current item |
| `{{ loop_1.index }}` | Zero-based position |
| `{{ loop_1.number }}` | One-based position |
| `{{ loop_1.count }}` | Total item count |
| `{{ loop_1.remaining }}` | Items remaining after this one |

The For Each runtime ID varies. Use **Insert flow tag** instead of typing `loop_1` yourself. Outside the **Each item** branch, `{{ item.* }}` is unavailable.

A named node in the same branch returns the result for the current item. A named node from before For Each returns its single earlier result.

</details>

### Work with only part of a list

Use **Filter** when you need the matching items and can discard everything else.

Use **Split** when different categories need different workflow branches.

![Filter's list source and matching rules](/documentation/flowcrafter/screenshots/node-filter-settings.png)

### Handle repeated or related items

Use **Deduplicate** when you want to keep only the first item with a particular value, such as the first entry for each email address.

Use **Group By** when you want to preserve all the items but collect those with a shared value, such as orders belonging to the same customer.

---

## Unsupported shapes

Flowcrafter blocks these workflows during activation:

| Shape | Why |
|---|---|
| For Each inside another For Each's **Each item** branch | Nested iteration cannot keep a safe independent cursor |
| [Delay](/documentation/flowcrafter/nodes/flow/delay/) or Wait inside **Each item** | The item batch cannot park halfway through |

Two For Each nodes in sequence are supported when the second starts from the first node's **Done** output.

---

## Item failures

The **On Error** setting controls what happens when one item fails:

- **Continue** records the failed item, processes the rest, marks the result `partial`, and takes **Done**.
- **Stop** ends on the first failure and does not take **Done**.

---

## Learn more

Each node page explains its settings, output, limitations, and examples. Start with the links in the table above, or try these guides:

- [Passing Data Between Nodes](/documentation/flowcrafter/building/using-flow-tags/)
- [Branching &amp; Conditional Logic](/documentation/flowcrafter/building/branching-and-conditions/)
- [Run & Node Statuses](/documentation/flowcrafter/reference/workflow-statuses/)