Skip to content
Factflow

Running pipelines

Once a pipeline config is stored, you start executions against it, monitor them, pause specific routes, and cancel runaways.

Start an execution

Section titled “Start an execution”
Terminal window
factflow config run CONFIG_ID

Or via API:

Terminal window
curl -X POST http://localhost:8000/api/v1/executions \
  -H 'Content-Type: application/json' \
  -d '{"config_id": "CONFIG_ID"}'

Response contains execution_id and initial status running.

List executions

Section titled “List executions”
Terminal window
factflow execution list
factflow execution list --status running
factflow execution list --status failed --limit 20 --offset 0

Filter: running, completed, failed, cancelled, interrupted.

Inspect one

Section titled “Inspect one”
Terminal window
factflow execution get EXEC_ID

Shows status, source config id, start/end times, route-level progress.

Wait for completion (blocking)

Section titled “Wait for completion (blocking)”
Terminal window
factflow execution wait EXEC_ID

Exit 0 on completed, non-zero on failed or cancelled. Useful in shell scripts and CI:

Terminal window
factflow config run CONFIG_ID | jq -r .execution_id | xargs factflow execution wait
echo "exit code: $?"

Tune timeout if needed:

Terminal window
factflow --timeout 1h execution wait EXEC_ID

Cancel

Section titled “Cancel”
Terminal window
factflow execution cancel EXEC_ID

Cancellation is graceful: the orchestrator signals every processor, processors stop consuming new messages, in-flight messages complete (or are cancelled with asyncio.CancelledError — adapters must be cancel-safe), then the execution transitions to cancelled.

DAG view

Section titled “DAG view”
Terminal window
factflow execution dag EXEC_ID

Returns nodes (routes + adapters) and edges (queue links). Useful for understanding what the orchestrator constructed from the YAML.

Stats

Section titled “Stats”
Terminal window
factflow execution stats EXEC_ID

Derived from lineage: message counts per adapter, failures, average duration.

List execution routes

Section titled “List execution routes”
Terminal window
factflow execution routes EXEC_ID

Every running route under this execution, with its queue name and processor state.

Pause and resume routes (global)

Section titled “Pause and resume routes (global)”

Routes can be paused globally — across all executions that share the route name:

Terminal window
factflow pipeline pause ROUTE_ID
factflow pipeline resume ROUTE_ID

Use case: a downstream service is degraded; pause the route writing to it, let upstream queue up, resume when the downstream is back. Messages in the broker queue survive the pause.

Global metrics

Section titled “Global metrics”
Terminal window
factflow system metrics

Point-in-time snapshot of the orchestrator: total messages received / completed / failed / in-flight, running route count.

Pipeline-level metrics

Section titled “Pipeline-level metrics”
Terminal window
factflow pipeline list
factflow pipeline metrics ROUTE_ID

Per-route throughput and latency.

Replay

Section titled “Replay”

Replay produces a new execution from a prior one’s storage. See the replay guide for full mechanics.

Section titled “Related”