> ## 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.

# Triggers & Runs

> How Datazone Flows start, and how to read the status of a run.

Every execution of a flow is a **run**. A run is created either manually or by a schedule, and progresses through the graph one node at a time, recording a per-node **step** as it goes.

## Trigger Types

Datazone supports two ways to start a flow:

| Type       | Description                                                            |
| ---------- | ---------------------------------------------------------------------- |
| `MANUAL`   | Started on demand, from the UI or by calling the run endpoint directly |
| `SCHEDULE` | Started automatically on a cron expression                             |

### Manual Runs

A manual run takes an optional set of **parameters** — a flat object made available to every node as `parameters` (and, on the `start` node's output, echoed back under `parameters`):

```json theme={null}
{
  "parameters": {
    "city": "London",
    "invoice_id": "INV-2024-0001"
  }
}
```

### Scheduled Runs

A **Flow Schedule** runs a flow's deployed definition automatically on a cron expression:

| Attribute    | Type   | Description                                                      |
| ------------ | ------ | ---------------------------------------------------------------- |
| `name`       | string | Schedule name                                                    |
| `flow`       | string | Id of the flow to run                                            |
| `branch`     | string | Branch whose definition should be scheduled (defaults to `main`) |
| `expression` | string | Cron expression (e.g. `0 * * * *` for hourly)                    |
| `parameters` | object | (Optional) Parameters passed to every scheduled run              |
| `is_active`  | bool   | Whether the schedule is currently enabled                        |

```yaml theme={null}
name: "Hourly weather refresh"
flow: "664f1c2e5a2ac9f0d39326"
branch: main
expression: "0 * * * *"
parameters:
  city: "London"
```

<Note>
  A schedule always runs the flow's definition on the **branch it was created against**. Deploying a new version of the flow to that branch changes what the next scheduled run executes.
</Note>

## Run Lifecycle

A run moves through the following statuses:

| Status     | Description                                    |
| ---------- | ---------------------------------------------- |
| `CREATED`  | The run has been accepted and queued           |
| `RUNNING`  | The graph is currently executing               |
| `SUCCESS`  | Every required node finished without error     |
| `FAILURE`  | A node raised an error that wasn't recoverable |
| `CANCELED` | The run was canceled before it finished        |

## Step Lifecycle

Each node execution inside a run is tracked as a **step**, with its own status:

| Status     | Description                                                             |
| ---------- | ----------------------------------------------------------------------- |
| `PENDING`  | Not started yet                                                         |
| `RUNNING`  | Currently executing                                                     |
| `SUCCESS`  | Finished without error                                                  |
| `ERROR`    | Raised an error                                                         |
| `TIMEOUT`  | Exceeded its `timeout_sec`                                              |
| `CANCELED` | The run was canceled while this step was pending/running                |
| `SKIPPED`  | Unreachable because a branching node (`if`) chose the other output port |

Each step also records `started_at`, `finished_at`, `execution_time`, `stdout`/`stderr`, and, on failure, `error_type`/`error_message`/`traceback` — everything you need to debug a failing node without re-running the whole flow.

<Note>
  Nodes inside a `for_each` body re-execute once per item. Rather than one step per iteration, the step for a body node is overwritten on each pass (last-iteration-wins), with `iteration`/`iterations_total` reporting progress.
</Note>

## Canceling a Run

A running flow can be canceled while it's in progress. In-flight and not-yet-started steps are marked `CANCELED`, and the run transitions to `CANCELED` once cancellation completes.

## Validation Before a Run

Before a run starts, the flow document is validated as a whole. The most common issues you'll see surfaced per-node:

<Warning>
  * A **required input port** must be connected (e.g. `response` and `output` always require their `in` port to be wired).
  * Connections leaving a **branching** node (`if`) must set `from_port` to a valid output port (`true`/`false`).
  * A flow may contain **at most one** top-level `response` node.
  * A `for_each` node's `body` must contain **exactly one** `response` node.
  * The flow (and every `for_each` body) must be a **DAG** — cycles are rejected.
  * `for_each` nesting is capped at a maximum depth of 5.
</Warning>

See the [Node Reference](/reference/flows/nodes) for the full set of per-node-type validation rules.

## Next Steps

* [Overview](/reference/flows/overview) - flow structure and core concepts
* [Node Reference](/reference/flows/nodes) - every node type and its config
* [YAML Reference](/reference/flows/yaml-reference) - the complete flow document schema