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

# Overview

> Build orchestration graphs that call LLMs, REST APIs, and Actions with a declarative YAML flow

<Frame>
  <img src="https://mintcdn.com/datazone/AoTD8G-OYqCsc8OQ/images/covers/flows-changelog.png?fit=max&auto=format&n=AoTD8G-OYqCsc8OQ&q=85&s=6066e97b97ef256044903ee48f412185" alt="Flows" width="1920" height="741" data-path="images/covers/flows-changelog.png" />
</Frame>

# Flows

A Flow is a **directed graph of typed nodes** you connect together to orchestrate a task: call an LLM, hit an external API, branch on a condition, loop over a list, or invoke a project [Action](/reference/development/actions). Flows are defined declaratively — the same document your Flow Builder canvas edits is what gets executed — so every run is reproducible and versionable.

## Overview

A Flow consists of:

1. **Nodes** - Typed steps (`start`, `if`, `llm_call`, `rest_call`, `action_call`, `python`, `for_each`, `output`, `response`) that read inputs and produce outputs
2. **Connections** - Directed edges wiring one node's output port to another node's input port
3. **Parameters** - Values passed in at run time (manual trigger or schedule), available to every node

## Flow Structure

Flows use a YAML-based document format — the same envelope the Flow Builder posts when you edit on the canvas or switch to the YAML view:

```yaml theme={null}
flow:
  name: "My Flow"

nodes:
  - id: trigger
    type: start
    label: Start
    config: {}

  - id: call_api
    type: rest_call
    label: Fetch data
    config:
      url: "https://api.example.com/data"
      method: GET

  - id: finish
    type: response
    label: Response
    config: {}

connections:
  - from: trigger
    to: call_api
  - from: call_api
    to: finish
```

## Key Concepts

### Nodes

Every node has an **id** (unique within the flow), a **type** (which node class runs it), an optional **label**, and a **config** bag whose shape is validated against that node type's schema. See the [Node Reference](/reference/flows/nodes) for every type.

### Connections and ports

A connection wires one node's **output port** to another node's **input port**:

```yaml theme={null}
connections:
  - from: fetch_weather
    to: process
    from_port: response   # optional — defaults to the node's first output
    to_port: in            # optional — defaults to the node's first input
```

Most nodes have a single input (`in`) and a single output, so `from_port`/`to_port` can usually be omitted. Two node types are the exception:

* **`if`** is a **branching** node — its outputs are the mutually-exclusive ports `true`/`false`, and every outgoing connection from it **must** set `from_port`.
* **`for_each`** is a **container** node — it owns a nested `body` sub-flow (its own `nodes`/`connections`) instead of branching, executed once per item.

### Data flow between nodes

A node receives its upstream nodes' outputs as `inputs`, keyed by input port name, plus the run's `parameters`. Most nodes read `inputs.get("in")` and `save_as` a named key in their own output — see [Templating & Expressions](/reference/flows/templating) for exactly how each node type consumes them.

### Runs

A flow is executed as a **run**, triggered either **manually** or on a **schedule**. Each node execution is tracked as a step with its own status (`PENDING` -> `RUNNING` -> `SUCCESS`/`ERROR`/`SKIPPED`). See [Triggers & Runs](/reference/flows/triggers-and-runs).

## Best Practices

1. **One `response` node per flow** - a flow may contain at most one top-level `response` node; it's what gets returned to the caller
2. **Name your `save_as` keys clearly** - downstream nodes reference upstream output by the key you chose (e.g. `weather`, `result`)
3. **Set `from_port` on every branch** - connections leaving an `if` node must declare `true` or `false` explicitly
4. **Keep loops bounded** - `for_each` enforces a `max_iterations` cap (default `1000`) to guard against runaway iteration
5. **Avoid cycles** - a flow must be a DAG; the validator rejects any cycle before a run starts

## Next Steps

* [Node Reference](/reference/flows/nodes) - every node type, its config, and its ports
* [Triggers & Runs](/reference/flows/triggers-and-runs) - starting a flow manually or on a schedule, and reading run/step status
* [Templating & Expressions](/reference/flows/templating) - how nodes reference upstream data and flow parameters
* [YAML Reference](/reference/flows/yaml-reference) - the complete flow document schema