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. Use the Executions API to debug flow logic in production, and forward execution events to your observability stack over webhooks.

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"

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_..."

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

AI Agents

Flows

Numbers & Verify

Concepts

Billing

Webhooks

Compliance

Legal

Changelog

Flow Executions

Flow Executions

List recent executions

Response

Get a single execution

Status values

Common errors

Retention

​Flow Executions

​List recent executions

​Response

​Get a single execution

​Subscribe to execution events

​Status values

​Common errors

​Retention

Flow Executions

List recent executions

Response

Get a single execution

Subscribe to execution events

Status values

Common errors

Retention