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

wait blocks until the execution reaches a terminal state, then prints the result. It exits 0 for any terminal status — completed, failed, and cancelled all return 0. It exits 1 only when the HTTP call itself fails (server unreachable, wait timeout exceeded). The exit code does not encode the outcome, so $? cannot tell success from failure.

To branch on status in a script, wait first, then read the status field from execution get:

Terminal window
EXEC_ID=$(factflow config run CONFIG_ID | jq -r .execution_id)
factflow execution wait "$EXEC_ID"
status=$(factflow execution get "$EXEC_ID" --output json | jq -r .status)
if [ "$status" != "completed" ]; then
  echo "execution ended with status: $status" >&2
  exit 1
fi

Two different --timeout flags apply here:

  • factflow execution wait EXEC_ID --timeout 1h — the wait duration (subcommand flag, default 5m). How long the server blocks before giving up.
  • factflow --timeout 1h execution wait EXEC_ID — the HTTP client timeout (global flag, default 30s). When you raise the wait duration past 30s, raise this too, or the client disconnects first.
Terminal window
factflow --timeout 1h execution wait EXEC_ID --timeout 1h

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”