Executions

Execution routes expose read-only access to the execution log. Lifecycle operations (run, resume, cancel, status) live under the workflow-scoped paths documented in Workflows.

GET /executions

List executions across the catalog with optional filters.

• Query:

  • namespace=<ns> — restrict to one namespace.
  • workflow_name=<name> — restrict to one workflow.
  • state=<STATE> — one of CREATED, SCHEDULED, CLAIMED, RUNNING, PAUSED, RESUMING, RESUME_SCHEDULED, RESUME_CLAIMED, CANCELLING, CANCELLED, COMPLETED, FAILED. Case-insensitive; invalid values return 400.
  • limit=<int> (default 50).
  • offset=<int> (default 0).

• Permission: execution:*:read.

• Response:

  {
    "executions": [
      {
        "execution_id": "...",
        "workflow_id": "...",
        "workflow_namespace": "...",
        "workflow_name": "...",
        "state": "COMPLETED",
        "worker_name": "worker-1"
      }
    ],
    "total": 132,
    "limit": 50,
    "offset": 0
  }

GET /executions/{execution_id}

Show a single execution.

• Query: ?detailed=true returns the full ExecutionContextDTO (input, output, full event log, current worker, timestamps). Without it, the response is a compact summary.
• Permission: execution:*:read.
• 404: execution not found.

Lifecycle operations

The remaining execution operations are scoped to a specific workflow:

See Workflows for the full signatures.

Execution states

The state field returned by every execution endpoint is one of:

• CREATED — context written, not yet visible to workers.
• SCHEDULED — dispatcher has flagged it for the next available worker.
• CLAIMED — a specific worker has claimed it but not started running.
• RUNNING — the worker is executing tasks.
• PAUSED — a pause() task has parked the execution; resume with POST /workflows/{ns}/{name}/resume/{execution_id}/{mode}.
• RESUMING, RESUME_SCHEDULED, RESUME_CLAIMED — intermediate states during the resume handoff.
• CANCELLING — cancel was requested; the worker is winding down.
• COMPLETED — terminal success.
• FAILED — terminal failure; output carries the exception detail.
• CANCELLED — terminal cancellation.

Use ?state= on GET /executions to filter by any of these (case-insensitive).

The detailed flag

Every execution-returning endpoint accepts ?detailed=true. Without it, responses are summaries (execution_id, workflow_name, state, worker_name). With it, the full ExecutionContextDTO is returned, including:

• input — the original input value.
• output — the workflow’s return value (when in a terminal state) or the exception detail (when failed).
• events — the complete ExecutionEvent log: every task start/complete/retry/fallback/rollback transition.
• current_worker — the worker that last touched the execution.
• created_at, updated_at, started_at, finished_at — timestamps.

Event logs grow with the size of the workflow; only request detailed=true when you actually need the trace.

Human-in-the-loop approval

When a workflow uses the approval primitive, the server exposes:

POST /executions/{exec_id}/authorize/{task_name}

Approve or reject a pending approval task. The caller’s identity must:

• hold a valid bearer token,
• match the auth_exempt_tasks policy on the workflow (if configured), and
• carry an exec_id claim matching the execution (when called by the worker itself with an execution token).

The body shape is the approval decision payload ({"approved": bool, ...}); see the workflow’s approval task implementation for the exact contract. Permission: depends on the workflow’s metadata.required_permissions.