Monitoring Runs¶

Audience: Everyone · Tags: monitoring, runs, status, pagination

Purpose. See every time your flows have run, filter down to the ones you care about, and understand at a glance what happened — success, failure, or somewhere in between.

The run list¶

curl "https://api.snaplink.cloudsolutionaccelerators.com/api/v1/runs?workspaceId=ws_92a1c4f0e7b3" \
  -H "Authorization: Bearer $TOKEN"

{ "ok": true, "data": {
  "items": [
    { "runId": "run_00a11b22c33d", "workspaceId": "ws_92a1c4f0e7b3", "flowId": "flow_1a2b3c4d5e6f",
      "flowName": "New lead to Slack", "status": "succeeded", "triggerType": "webhook",
      "startedAt": "2026-07-02T14:05:01.000Z", "completedAt": "2026-07-02T14:05:01.400Z",
      "durationMs": 400, "retryCount": 0, "stepCount": 1, "createdAt": "2026-07-02T14:05:00.900Z" }
  ],
  "total": 42, "limit": 20, "offset": 0
} }

Every run status, and what it means¶

Status	Meaning
`queued`	Accepted, waiting to start.
`running`	Actively executing right now.
`succeeded`	Every step completed without error.
`failed`	A step failed and won't be retried further.
`cancelled`	Stopped via `POST /executions/:id/cancel`.
`retry_pending`	Failed, and a retry is scheduled.
`retry_running`	A retry attempt is currently executing.
`retry_exhausted`	Failed, retried the allowed number of times, still failed.

failed and retry_exhausted both mean "it did not work" — the difference is only whether the engine tried again automatically first.

Filtering¶

All filters are optional query parameters on GET /runs:

Param	Filters to
`flowId`	Runs of one specific flow
`status`	One of the statuses above
`from` / `to`	ISO timestamps — runs created in that window
`connector`	Runs whose steps invoked a given connector key (e.g. `slack`)
`errorCode`	Runs whose steps failed with a specific error code (see Flow Debugging for the full taxonomy)

curl "https://api.snaplink.cloudsolutionaccelerators.com/api/v1/runs?workspaceId=ws_92a1c4f0e7b3&status=failed&connector=hubspot&from=2026-07-01T00:00:00Z" \
  -H "Authorization: Bearer $TOKEN"

Pagination¶

GET /runs pages with limit and offset. Default limit is 20; maximum is 100. The response always tells you exactly what page you got back:

curl "https://api.snaplink.cloudsolutionaccelerators.com/api/v1/runs?workspaceId=ws_92a1c4f0e7b3&limit=50&offset=50" \
  -H "Authorization: Bearer $TOKEN"

{ "ok": true, "data": { "items": [ "..." ], "total": 137, "limit": 50, "offset": 50 } }

Keep incrementing offset by limit until offset + items.length >= total.

Step-by-step¶

Call GET /runs?workspaceId=... (or open the Dashboard's Recent Runs list in the app) to see the latest activity.
Narrow with status, connector, errorCode, or a date range to find what you're looking for.
Pick a runId and open its detail — see Execution History for what each sub-resource shows.

Best practices¶

Check runs regularly rather than only when something's reported broken — a rising failed/retry_exhausted count is an early warning.
Filter by connector when a specific app (say, HubSpot) seems flaky, to isolate its runs from everything else.
Bookmark a runId when contacting support — it's the fastest way to point someone at exactly what happened.

FAQ¶

Can I get a live feed instead of polling? Not yet — poll GET /runs for now; push/streaming updates are Planned. How far back does history go? Runs are retained per your workspace's retention window; see Execution History.

If something goes wrong¶

If runs are failing and you need to understand why, see Execution failures.