Skip to content
Echopoint Echopoint Docs

Executions & live runs

An execution is one run of a flow. Every launch — whoever triggered it, from wherever — is recorded with per-node results you can inspect afterwards.

Ways to launch

Section titled “Ways to launch”
FromHow
UIPress Run flow on the canvas
CLIechopoint flows launch <flow-id> or echopoint flows run <flow-id>
APIPOST /flows/{id}/launch with an API key
CIThe GitHub Action, nanostack-dev/echopoint-cli@v1
Terminal window
# Launch and return immediately with the execution ID
echopoint flows launch <flow-id>


# Run end-to-end and wait for the result (exit code 0 = passed)
echopoint flows run <flow-id> --environment staging --verbose

The API launch endpoint supports an Idempotency-Key header, so a retried request does not start a duplicate run:

Terminal window
curl -X POST "https://api.echopoint.dev/flows/<flow-id>/launch" \
  -H "X-Api-Key: <key>" \
  -H "X-Organization-Id: <org-id>" \
  -H "Idempotency-Key: deploy-2026-06-09-1"

Statuses

Section titled “Statuses”

An execution moves through: pending → running → completed, failed, or cancelled.

Nodes use the same statuses plus skipped — a node that did not run because its upstream path failed or its inputs were missing. Skipped nodes record why (see below).

Live progress on the canvas

Section titled “Live progress on the canvas”

While an execution runs, the canvas updates node by node over SSE — no refresh. The stream emits flat JSON events:

  • flow.started — the execution began
  • node.started — a node began executing
  • node.completed — a node finished, with its results
  • node.failed — a node failed

The same stream is available from the API at GET /flows/{flowId}/executions/{executionId}/stream, and echopoint flows run --verbose prints live node status in the terminal.

Run history and node results

Section titled “Run history and node results”

Each flow keeps its full run history. Open any execution to see every node’s recorded result:

  • assertion_results — each assertion with its expected value, actual value, and whether it passed. Recorded on passing runs too.
  • skip_reason — for skipped nodes, why the node did not run.
  • missing_inputs — which inputs a skipped node was waiting on.

Nodes also have node-level execution history: the results of one node across runs, useful for spotting a step that fails intermittently.

From the CLI:

Terminal window
echopoint flows execution list <flow-id>
echopoint flows execution get <flow-id> <execution-id>

Debugging a failed run

Section titled “Debugging a failed run”
  1. Find the first failed node in the execution — downstream nodes are usually skipped fallout, not the cause.
  2. Read its assertion results. Expected vs actual tells you immediately whether the API returned the wrong status, the wrong body value, or nothing at all.
  3. Check skipped nodes’ skip_reason and missing_inputs. A node skipped for a missing input points back at the upstream node whose output extractor did not match — often a jsonPath that no longer fits the response shape.
  4. Verify variables resolved as intended. Confirm the right environment key was used at launch and the flow’s {{variables}} reference outputs that exist.
  5. Fix and launch again. Adjust the request, extractor, or assertion, then run the flow against the same environment to confirm.

Next steps

Section titled “Next steps”