Skip to main content
A Flow is a saved, editable directed acyclic graph of nodes. It has a name, a graph of nodes and connections, any number of schedules, and a set of editor settings. The Flow is the persistent definition - the thing you design, save, and share. The definition by itself does nothing; executing it is a separate concern.

​
Flow runs

A FlowRun is one execution of a Flow. Every time a flow runs - manually, on a schedule, or from a dry run in the editor - a new FlowRun row is recorded. Each run captures:
  • Status: running, ok, aborted, failed, or cancelled.
  • Start and finish timestamps.
  • Errors encountered during execution.
  • Logs emitted by nodes, and a trace identifier.
  • Persisted assigns: a snapshot of named values the flow chose to keep.
Only a subset of the token’s assigns is persisted. The flow’s editor settings include a persist assigns list that names which assigns are worth snapshotting. This keeps the run history small even for flows that iterate over large collections and build up intermediate state.

​
Triggering a run

Flows can be started in several ways:
  • Manually, from the flow editor. Manual runs are enqueued with higher priority than scheduled runs so an operator’s ad-hoc execution jumps ahead of pending scheduled work.
  • On a schedule. A flow can carry several schedules, each with its own cron expression and enabled flag. When a schedule is enabled, the Flow Scheduler enqueues a run each time that schedule’s cron expression matches. Each schedule can seed different preset values, so one flow can run more than once with different parameters. See Scheduling and observability.
  • As a dry run, from the editor’s Evaluator pane. Dry runs substitute stub values for each assign declared by the graph and skip the actual step invocations. They are useful for validating that the graph is wired correctly without hitting source systems.
Manual and scheduled runs both execute the full graph; dry runs generate synthetic values instead of calling external systems.

​
Cancelling a running flow

A running flow can be cancelled from the editor. Cancellation sends a signal to the running evaluator, which checks for the signal between nodes and finalises the FlowRun with status cancelled. Cancellation is cooperative - a step that is currently blocked on an external call keeps running until that call returns, after which the evaluator picks up the signal and stops. Cancellation is distinct from a flow aborting itself. See Execution and error handling for the difference between user-initiated cancellation, abort_flow, and the on_error policies.

​
Run history

The run history for a flow is the list of FlowRun rows for that flow, ordered by start time. Each row links to its logs and any persisted assigns. This is the primary surface for understanding whether scheduled flows are succeeding, how long runs take, and what changed between runs.