Inspecting executions

Every run — dev and live — leaves a complete trace: the workflow execution, its flow executions, and each node execution with inputs, resolved configuration, and outputs. Debugging is reading that trace in the right order, not rerunning and hoping.

Finding runs

cai exec list                       # recent executions for the pinned workflow
cai exec get <workflowExecutionId> --json

In the app, the builder header’s Run history panel lists runs and opens Run details; each node execution shows Inputs / Process / Outputs tabs. Subflow calls drill down with breadcrumbs; loops drill into per-iteration detail — how you debug the for-each that failed on item 37. Each run also shows its usage cost.

Retention

Run history is plan-capped (7 days free, 90 days standard). Last month’s failing run may simply no longer exist — capture execution ids and evidence while they’re fresh.

The fault-isolation order

cai exec tree <workflowExecutionId> --json     # the whole run as a tree
cai exec node <nodeExecutionId> --json
cai exec ports <nodeExecutionId> --json        # inputs vs resolved configs vs outputs

1. Walk the tree to the first unexpected status. Debug that node, not the last error in the run — downstream failures are usually echoes.
2. Distinguish skip from failure. A skipped node records why: its own condition (only_when_false) versus an untaken branch upstream. Only-when skips still let downstream run (with nulls); branch blocks propagate.
3. Compare the three port layers. Inputs are what arrived; resolved configs are what the expressions produced; outputs are what left. The mismatch between two adjacent layers is the bug’s address.
4. Treat green-but-empty as failure. Expressions null-propagate and empty filter comparisons match nothing — the classic wrong-but-green run. The evidence is an empty resolved config or an empty output, never an error message.

Node errors carry a real four-way taxonomy — input, process, output, unknown — each with subtypes; a wired type mismatch fails loudly as an input error. See the execution model.

Controlling a running execution

A running execution can be paused, a paused one resumed, and a pending, running, or paused one cancelled — from run details or the API. That is the lever when a live workflow is mid-flight and wrong.

Example prompts

Walk the tree of execution 4821: find the first unexpected node, show its ports, and tell me whether this is a skip, a failure, or a silent empty.

Compare the resolved configs of this node between the last green run and this failing one, and diff what changed.