Flow Executions

Every time a published flow runs — triggered by an inbound message, a campaign send, an API call, or a scheduled cron — Orbit records a complete execution trace: which nodes ran, what their inputs and outputs were, how long they took, and any errors raised. This page covers both the Dashboard walkthrough — the Flows page’s Executions tab — and the Executions API further down. Use the dashboard to find a problematic run and inspect its steps; use the API to automate that same inspection or forward execution events to your observability stack over webhooks.

Dashboard walkthrough

Open the Executions tab

In the dashboard, open the Flows page at /flows and select the Executions tab. It shows the tenant-wide run log: every execution across every flow, newest first, with stat cards for total runs, successes, failures, and average duration. Filter by status pill (running/completed/failed), a date range (Today, 7 days, 30 days, or all), or search by flow name or trigger. To scope the table to one flow, either deep-link from that flow’s Analytics tab (it pins a ?flow= scope you can clear from the filter banner) or open the flow in the Builder — both converge on this tab. A run first appears with a running badge and updates in place as nodes complete; refresh the list to pick up its terminal state. To start a run manually, use the Run button next to a published flow in the My Flows tab (an empty trigger payload runs it against its own defaults), then watch it land here.

Run lifecycle states

Each row’s Status badge reports one of the status values — running, waiting (parked on a long delay node, resumes automatically), completed, completed_with_errors (finished with partial failures routed via error edges), failed, or timeout (the run exceeded the per-flow wall-clock cap of 300 seconds). The partial-failure state completed_with_errors is easy to miss in the dashboard because the status filter pills only split running/completed/failed — filter by Failed to catch both hard failures, then scan the Status column for the warning-toned Completed with errors badge when triaging partial failures.

Node-level drill-down

Select any run’s flow name or its View action to open the execution detail dialog. It shows the run’s flow, trigger, total duration, and — when the run failed — a prominent Failure reason banner carrying the run-level error (Last failed node <node_id>: <reason>), so you don’t expand every step hunting for the break. Below that, a step-by-step timeline lists every node in execution order with its per-step status (completed, running, failed, skipped, or pending), node-type badge (Send SMS, WhatsApp, Email, Condition, AI Agent, Webhook, Delay, Transform), and duration. Expand a step to see its recorded input and output snapshots as formatted JSON (one-click copy), plus the per-step error when it failed. skipped means an error edge routed around the node; pending/running means the run is still in flight or parked on a delay.

Stop, cancel, and retry semantics

The dashboard is read-only for executions — there is no stop/cancel control in the Executions tab. To halt a class of failing runs, unpublish the flow from the Builder (or via POST /flows/:id/unpublish) so new triggers are rejected; already-parked waiting runs resume as scheduled. To replay a stuck run parked on a delay node, call the resume endpoint with the delay node’s id — the run continues from the node wired after it:

curl -X POST https://api.orbit.devotel.io/api/v1/flows/executions/exec_xyz789/resume \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"flow_id": "flow_abc123", "resumed_step": "node_delay_1"}'

// The Node SDK has no typed flow-execution helper — reach the resume
// endpoint through the generic orbit.request escape hatch (auth, retries,
// and the same { data, meta } envelope as the typed resources). Paths are
// relative to /api/v1.
const resumed = await orbit.request("POST", "/flows/executions/exec_xyz789/resume", {
  flow_id: "flow_abc123",
  resumed_step: "node_delay_1",
});

# The Python SDK has no typed flow-execution helper either — call the resume
# endpoint through the client.request escape hatch. Keyword args match the
# typed helpers' pass-through shape.
resumed = client.request(
    "POST",
    "/flows/executions/exec_xyz789/resume",
    json_body={"flow_id": "flow_abc123", "resumed_step": "node_delay_1"},
)

Re-triggering a flow (from the dashboard Run button or POST /flows/:id/execute) starts a fresh execution — it does not replay a prior run in place, so retries are naturally idempotent from the executions log’s point of view: each attempt is its own row.

Run timing and filtering

The list’s Duration column shows total wall-clock time; in the detail dialog each step’s duration appears inline next to its name, so you can find which node actually burned the time (durations are 0 for pending/skipped steps). The Started At column shows relative time with an absolute, timezone-aware timestamp on hover. The stat cards at the top (total, successful, failed, average duration) come from the summary endpoint aggregated over your chosen window, not just the loaded rows.

Observing the run — per-execution trace walkthrough

Once you open a run’s detail dialog, the complete step-by-step trace answers which node failed, why it failed, and what state it saw. This section walks the trace grid column by column, explains the state vocabulary and transitions, and works through a stalled-run debugging loop so you can triage a failed or waiting execution in under a minute.

Trace columns

Every row in the execution history table carries these columns, each sortable:

Column	What it tells you
Flow Name	The flow this run belongs to. Click its name or the View button to open the detail dialog.
Trigger	How the run started — `manual` (dashboard Run button or `POST /flows/:id/execute`), `event` (inbound message), `webhook` (a webhook trigger node), `schedule` (cron trigger), or `workflow` (parent workflow invocation).
Status	One of the status values below. A `running` badge pulses with a spinner; a `waiting` badge carries a clock icon and means the run is parked on a delay node.
Steps	A progress bar + `completed/total` count. Hover the bar to see the exact fraction; the bar fills as nodes complete.
Duration	Wall-clock time from start to the last node that finished (or to now, for a `running`/`waiting` run).
Started At	Relative time (“3m ago”) with an absolute, timezone-aware timestamp on hover — matches the format used across the Messages and Voice tables.

State vocabulary and transitions

An execution’s status flows through a fixed state machine. Only these transitions are possible; the UI never shows an invalid edge.

Status	Meaning	Allowed next states
`pending` (internal)	The run has been enqueued but not yet picked up by a worker. You will never see this in the dashboard — almost all runs move to `running` within milliseconds.	`running`
`running`	A worker has picked up the run and is executing nodes.	`completed`, `waiting`, `completed_with_errors`, `failed`, `timeout`
`waiting`	The run reached a Delay node with a scheduled resume time. It is not consuming a worker — it will resume automatically at the deadline. The delay node’s input/output in the detail dialog shows the configured wait duration and the scheduled resume timestamp.	`running` (on resume)
`completed`	All nodes finished successfully — every step in the trace shows `completed`.	terminal
`completed_with_errors`	The run finished, but one or more nodes failed and the failure was routed through an error edge (or fell through to the default-next). The top-level error message in the detail dialog names the last failed node and its reason. Steps that were bypassed by an error edge show `skipped`.	terminal
`failed`	A node threw an unrecoverable error with no error edge wired, so the run was abandoned. The detail dialog surfaces the failure reason as a red banner at the top of the trace.	terminal
`timeout`	Execution exceeded the per-flow wall-clock cap of 300 seconds.	terminal

The terminal set is {completed, completed_with_errors, failed, timeout}. A run in any of these states will never change again. A waiting run is the only non-terminal pause — it will move back to running at the scheduled time.

Filters

Use the controls above the table to narrow the run log to the executions that matter:

Status pills — All, Running, Completed, Failed. Note that completed_with_errors runs appear under Failed (and also under All or Completed), but you can always distinguish them by their Completed with errors badge in the Status column. waiting runs appear under All (there is no dedicated waiting pill, but the clock-icon badge makes them easy to spot).
Date range — Today, 7d, 30d, or All. The stat cards at the top recalculate over the same window.
Search box — free-text search across flow names and trigger types.
Flow scope — deep-link from a flow’s Analytics tab by clicking “View individual runs.” A teal banner shows the scoped flow and a Clear filter button returns you to the tenant-wide log.

Detail-view annotations

When you expand a step in the trace timeline, you see more than just input and output. The detail dialog also surfaces:

Node-type badge — every step carries a badge: Send SMS, WhatsApp, Email, Condition, AI Agent, Webhook, Delay, or Transform. The badge’s tint helps you scan for the node class at a glance.
Per-step duration — each step’s wall-clock time appears next to its name. pending and skipped steps report 0ms.
Failure reason — when the run ended in failed or completed_with_errors, a red banner at the top of the trace carries the full error message (“Last failed node node_send_sms: to must be a valid E.164 phone number”) so you do not need to expand every step hunting for the break.
Waiting state with deadline — a run parked on a delay node shows the delay node as running (the step-level status) while the parent execution shows waiting. Expand the delay step to see the scheduled resume timestamp in its input.
Retry behavior — the flow executor does not retry individual nodes. A failed node with no error edge abandons the run. To retry, re-trigger the flow from the dashboard Run button or POST /flows/:id/execute — each attempt is its own execution row.
External-event nodes — a webhook trigger or an event-listener node that is awaiting an external event shows as pending in the step timeline; the run-level status stays running until the event arrives or the run times out.
Repeating vs. one-shot — every execution row in the history table is a single, one-shot run. There is no repeating execution concept — a flow triggered by a schedule trigger fires a new execution row each time the cron fires, and each row is independently inspectable. The parent flow’s schedule is visible on the Builder page under its trigger configuration.

Reading a stalled run — worked example

A run shows waiting in the history table. You need to know whether it will resume, when, and what fires next.

Open the detail dialog — click the flow name or the View button on the row.
Read the trace timeline — the last running step is the delay node (badge: Delay). Expand it.
Check the delay node’s input — it records the configured wait duration (e.g. {"wait_ms": 3600000} for a 1-hour delay) and the scheduled resume timestamp.
Identify the next node — the node wired after the delay node in the flow definition is the one that will execute when the wait expires. If you need to resume immediately, call the resume endpoint with the delay node’s id — the run continues from the next node.
If the deadline has passed and the run still shows waiting — check whether the flow was unpublished in the Builder while the run was waiting. An unpublished flow rejects new triggers but does not cancel already-waiting runs, which resume as scheduled. If the run is genuinely stuck past its deadline, contact support.

Monitoring loop — from aggregate to root cause

When you are on call and an alert fires, trace the failure from the aggregate to the individual step:

Flows > Analytics tab — pick the failing flow and check the funnel. A sharp drop-off at a specific node narrows the search.
“View individual runs” link — click it to scope the Executions tab to just that flow.
Executions tab — filter by Failed and the relevant date range. Scan the Status column for failed and completed_with_errors badges.
Open the failing execution — the red failure banner tells you which node broke and why. Expand the failed step to see the input that triggered it.
Fix and re-trigger — correct the flow definition in the Builder, re-publish, and re-trigger from the Run button. Each re-trigger starts a fresh execution row — the failed run stays in the log for audit.
Cross-reference the inbox — if the failed run involved an inbound message (trigger: event), open the Inbox to see the original conversation thread and reply to the contact.

Cross-links

Flow Builder — Observability section: the Builder’s Test and Versions toolbar controls feed directly into the executions log; every test run and published-version run appears in this tab.
Flow Analytics reading guide — reading the funnel that sits one tab to the left.
Troubleshooting: a flow execution that failed — guided failure diagnosis runbook.

When to escalate to the API

The dashboard covers interactive triage. For anything automated — building an alerts feed of failed runs, exporting traces to your own observability stack, or reconciling executions against message delivery records — use the API below, or subscribe to the flow.execution.* webhook events. For a guided failure diagnosis, see Troubleshooting: a flow execution that failed.

List recent executions

curl -G https://api.orbit.devotel.io/api/v1/flows/executions \
  -H "X-API-Key: dv_live_sk_..." \
  --data-urlencode "flow_id=flow_abc123" \
  --data-urlencode "status=failed" \
  --data-urlencode "limit=25"

// Query params ride on the escape hatch as plain fields — the client
// encodes them like the cURL --data-urlencode flags above.
const runs = await orbit.request("GET", "/flows/executions", {
  query: { flow_id: "flow_abc123", status: "failed", limit: 25 },
});

for (const run of runs.data) {
  console.log(run.id, run.status, run.duration_ms);
}

# Keyword args match the typed helpers' pass-through shape — the client
# encodes `params` like the cURL --data-urlencode flags above.
runs = client.request(
    "GET",
    "/flows/executions",
    params={"flow_id": "flow_abc123", "status": "failed", "limit": 25},
)

for run in runs["data"]:
    print(run["id"], run["status"], run["duration_ms"])

Response

{
  "data": [
    {
      "id": "exec_xyz789",
      "flow_id": "flow_abc123",
      "flow_name": "Inbound SMS auto-responder",
      "status": "failed",
      "trigger": "event",
      "steps_completed": 4,
      "total_steps": 6,
      "duration_ms": 384,
      "error": "Last failed node node_send_sms: to must be a valid E.164 phone number",
      "started_at": "2026-05-09T10:14:22.103Z",
      "created_at": "2026-05-09T10:14:22.103Z"
    }
  ],
  "meta": {
    "request_id": "req_a1b2c3",
    "timestamp": "2026-05-09T10:15:01.000Z",
    "pagination": {
      "cursor": "2026-05-09T10:14:22.103Z|exec_xyz789",
      "has_more": true
    }
  }
}

Each row carries these fields:

Field	Type	Description
`id`	string	Execution id.
`flow_id`	string	The flow this run belongs to.
`flow_name`	string	Current name of the parent flow (`"Untitled flow"` if the flow was deleted).
`status`	string	One of the status values below.
`trigger`	string	The parent flow’s trigger type — `manual`, `webhook`, `schedule`, `event`, or `workflow`.
`steps_completed`	number	Count of steps recorded in this run’s trace.
`total_steps`	number	Count of nodes in the flow definition.
`duration_ms`	number	Wall-clock duration in milliseconds.
`error`	string \| null	The failure message when the run failed, otherwise `null`.
`started_at`	string	ISO-8601 timestamp when the run began.
`created_at`	string	Alias of `started_at`.

Pagination is keyset-based: pass meta.pagination.cursor back as the cursor query parameter to fetch the next page, and stop when has_more is false.

Get a single execution

curl https://api.orbit.devotel.io/api/v1/flows/executions/exec_xyz789 \
  -H "X-API-Key: dv_live_sk_..."

const { data: trace } = await orbit.request("GET", "/flows/executions/exec_xyz789");

for (const step of trace.steps ?? []) {
  console.log(step.node_id, step.status, step.duration_ms);
}

trace = client.request("GET", "/flows/executions/exec_xyz789")

for step in trace["data"].get("steps", []):
    print(step["node_id"], step["status"], step["duration_ms"])

The single-execution response returns the full trace, including the raw trigger_data context and a steps array — one entry per node that ran, in execution order:

{
  "data": {
    "id": "exec_xyz789",
    "flow_id": "flow_abc123",
    "status": "failed",
    "trigger_data": {
      "channel": "sms",
      "message_id": "msg_sms_abc"
    },
    "steps": [
      {
        "name": "Send Sms",
        "node_id": "node_send_sms",
        "node_type": "sendSms",
        "status": "failed",
        "duration_ms": 42,
        "input": { "to": "+not-a-number" },
        "output": { "error": "to must be a valid E.164 phone number" },
        "error": "to must be a valid E.164 phone number"
      }
    ],
    "error": "Last failed node node_send_sms: to must be a valid E.164 phone number",
    "started_at": "2026-05-09T10:14:22.103Z",
    "updated_at": "2026-05-09T10:14:22.487Z",
    "completed_at": "2026-05-09T10:14:22.487Z"
  },
  "meta": {
    "request_id": "req_a1b2c3",
    "timestamp": "2026-05-09T10:15:01.000Z"
  }
}

Each entry in steps carries a readable name, the originating node_id and node_type so you can correlate against the flow definition, a status (completed, running, failed, skipped, or pending), a duration_ms, and — when the executor recorded them — the step input, output, and a surfaced error message. A pending step has been reached but has not started executing yet; a running step is in progress, which also covers a node parked on a long delay or send-time schedule that will resume automatically. These per-step statuses are narrower than the run-level status values below: a step never reports waiting, completed_with_errors, timeout, or info. Orbit does not expose a streaming (SSE) endpoint for executions. Execution lifecycle events are delivered over webhooks — subscribe an endpoint and Orbit will POST each event as the run progresses:

Event	When
`flow.execution.started`	A flow run was picked up by a worker and began executing.
`flow.execution.completed`	All nodes finished successfully.
`flow.execution.failed`	A node threw an unrecoverable error and the run was abandoned.

See Webhook Events for the full catalog and Event Payloads for the body shape. To pull current state on demand instead, poll GET /flows/executions/:id.

Status values

Status	Meaning
`running`	The run was picked up by a worker and at least one node is currently executing.
`waiting`	Paused on a long delay node; the run will resume automatically at its scheduled time.
`completed`	All nodes finished successfully.
`completed_with_errors`	The run finished, but one or more nodes failed and were routed via an error edge (or fell through to the default-next). The last failure is recorded in `error`.
`failed`	A node threw an unrecoverable error with no error edge, and the run was abandoned.
`timeout`	Execution exceeded the per-flow wallclock cap (300s).

Common errors

Code	HTTP	Cause	Fix
`NOT_FOUND`	404	The execution id doesn’t belong to the calling org, or the id is incorrect.	Verify the execution id and your org id.
`RATE_LIMITED`	429	Per-key request rate exceeds the cap (60 requests/minute on the executions read endpoints).	Honour the `Retry-After` header; the response body also carries a numeric `retry_after` (seconds) inside `error`.

Both responses use the standard error envelope — error.code carries the value above, and meta.request_id echoes the X-Request-Id for support correlation.

Retention

Orbit retains execution traces so you can debug recent runs. There is no self-serve setting to configure an execution-retention window today — flow-execution retention is not exposed in the API or the dashboard. If you have a specific retention or data-residency requirement, contact support.

Getting Started

Channels

Channels (Voice)

AI Agents

Campaigns

Flows

Numbers & Verify

Concepts

Features

Billing

Webhooks

Security & SSO

Compliance

Legal

Brand & press

Tutorials

Changelog

Flow Executions: debug and audit individual flow runs

Flow Executions

Dashboard walkthrough

Open the Executions tab

Run lifecycle states

Node-level drill-down

Stop, cancel, and retry semantics

Run timing and filtering

Observing the run — per-execution trace walkthrough

Trace columns

State vocabulary and transitions

Filters

Detail-view annotations

Reading a stalled run — worked example

Monitoring loop — from aggregate to root cause

Cross-links

When to escalate to the API

List recent executions

Response

Get a single execution

Status values

Common errors

Retention

​Flow Executions

​Dashboard walkthrough

​Open the Executions tab

​Run lifecycle states

​Node-level drill-down

​Stop, cancel, and retry semantics

​Run timing and filtering

​Observing the run — per-execution trace walkthrough

​Trace columns

​State vocabulary and transitions

​Filters

​Detail-view annotations

​Reading a stalled run — worked example

​Monitoring loop — from aggregate to root cause

​Cross-links

​When to escalate to the API

​List recent executions

​Response

​Get a single execution

​Subscribe to execution events

​Status values

​Common errors

​Retention

Flow Executions

Dashboard walkthrough

Open the Executions tab

Run lifecycle states

Node-level drill-down

Stop, cancel, and retry semantics

Run timing and filtering

Observing the run — per-execution trace walkthrough

Trace columns

State vocabulary and transitions

Filters

Detail-view annotations

Reading a stalled run — worked example

Monitoring loop — from aggregate to root cause

Cross-links

When to escalate to the API

List recent executions

Response

Get a single execution

Subscribe to execution events

Status values

Common errors

Retention