Skip to content
Factflow

Executions API

13 endpoints under /api/v1/executions. The CLI’s factflow execution commands map to this API 1:1.

Start

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

Response: {"execution_id": "...", "status": "running", ...}.

Optional fields:

  • trigger_context — free-form JSON stamped onto the execution row; visible in GET responses (use for tagging e.g. "source": "cron")
  • idempotency_key — if provided, the server dedupes concurrent POSTs with the same key within a short window

List

Section titled “List”
Terminal window
GET /api/v1/executions
GET /api/v1/executions?status=running
GET /api/v1/executions?status=failed&limit=50&offset=0

Inspect

Section titled “Inspect”
Terminal window
GET /api/v1/executions/{id}

Returns the execution row + config_snapshot + timestamps + derived stats.

Wait (SSE)

Section titled “Wait (SSE)”
Terminal window
GET /api/v1/executions/{id}/events        # SSE stream of status changes

The CLI’s factflow execution wait consumes this stream. The stream closes when the execution reaches a terminal state.

Cancel

Section titled “Cancel”
Terminal window
POST /api/v1/executions/{id}/cancel

Graceful cancellation; returns immediately with status: "cancelling". The execution transitions to cancelled once processors drain.

Stats

Section titled “Stats”
Terminal window
GET /api/v1/executions/{id}/stats

Counts per adapter (completed, failed, pending), average duration, throughput. Derived from lineage — updates live as the execution runs.

DAG

Section titled “DAG”
Terminal window
GET /api/v1/executions/{id}/dag

Nodes (routes + adapters) and edges (queue links). Use this to build an execution-topology UI.

Routes

Section titled “Routes”
Terminal window
GET /api/v1/executions/{id}/routes

Per-route detail: queue name, processor status, in-flight count.

Replay

Section titled “Replay”
Terminal window
POST /api/v1/executions/{id}/replay
Body: {"from_stage": "markdown", "to_route": "embeddings"}

See the replay guide for mechanics.

Storage stream (SSE)

Section titled “Storage stream (SSE)”
Terminal window
GET /api/v1/executions/{id}/storage-stream

Live feed of storage writes during the execution. Powers factflow storage watch.

Tags

Section titled “Tags”
Terminal window
POST /api/v1/executions/{id}/tag

Attach labels to an execution (e.g., "env": "prod", "owner": "@ove"). Queryable via GET /api/v1/executions?tag=env:prod.

Content model

Section titled “Content model”

An execution’s life cycle:

created → running → (completed | failed | cancelled | interrupted)
                      ↑
            replay inherits from a parent → new execution
  • created — row exists, orchestrator not yet started (transient, usually skipped)
  • running — active
  • completed — all routes drained, no failures
  • failed — at least one uncaught adapter error; see error field and lineage failures
  • cancelled — user cancelled via POST .../cancel
  • interrupted — server crashed; recovery on next startup resumes from lineage

Idempotency and retries

Section titled “Idempotency and retries”

If you POST the same POST /api/v1/executions twice with the same idempotency_key, the second call returns the first execution’s row. Useful for cron jobs that may retry on network failure.

Section titled “Related”