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

# Runs & executions

> What happens when a workflow actually runs.

A run is one execution of a workflow. A run can be started manually, on a schedule, or from a webhook or API [trigger](https://docs.celerflow.ai/concepts/triggers.md). Every run is persisted, ordered, and streamed back to your browser in real time. If something goes wrong, the failure is surfaced precisely — not as a generic error.

## Data model

Each run is a row in `workflow_runs`. Each step within that run is a row in `workflow_steps`. Steps are ordered by their position in the DAG and execute sequentially once their upstream dependencies resolve.

### Step lifecycle

```
pending → running → completed
                 ↘ failed
```

A step moves from `pending` to `running` when it starts, then to `completed` or `failed` when the agent finishes. A failed step stops the run.

## Orchestration

Runs are dispatched to a Trigger.dev task named `celerflow-workflow-run`. Trigger.dev only orchestrates — it walks the node list, handles retries, and calls back a webhook that updates the `workflow_steps` and `workflow_runs` rows. The actual agent work always runs on Railway, never inside Trigger.dev. That callback is what drives the status transitions you see in the UI.

A step can also **fan out** over an array, running its agent on each element with bounded concurrency and aggregating the results into one output.

## Real-time updates

The UI subscribes to run progress via Supabase Realtime. Each open browser tab gets a channel with a unique subscriber suffix — so if you have the same workflow open in two tabs, they don't overwrite each other's state.

## Run result

When a run completes, a `result_markdown` field is written to the run record. This is rendered on the run detail page. See [Executions](https://docs.celerflow.ai/dashboard/executions.md) for the UI surface.

## Rerun and dispatch failures

**Rerun** — triggering a rerun queues a new deploy command and starts a fresh run record. Previous run history is preserved.

**Dispatch failure** — if Trigger.dev can't accept the dispatch (capacity, network, or config issue), the UI shows a `dispatch_failed` banner on the run detail page. This is a named error state, not a generic 500.

> [!NOTE]
>
> The `dispatch_failed` state means CelerFlow could not hand the run off to Trigger.dev. It does not mean the workflow itself has a bug. Retrying the run is safe.

For the full execution UI, see [Executions](https://docs.celerflow.ai/dashboard/executions.md). For workflow lifecycle states, see [Workflows](https://docs.celerflow.ai/concepts/workflows.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.