Execution History¶

Audience: Everyone / Developers · Tags: runs, history, audit, timeline

Purpose. Once you have a runId (from Monitoring Runs or a webhook response), this is where you go deep — every step, every retry, every event, in order. Nothing about a run happens invisibly.

The sub-resources, and when to use each¶

Endpoint	Shows	Look here when…
`GET /runs/:id`	The run record itself, plus its steps and retries in one call	You want the full picture in one request
`GET /runs/:id/timeline`	A single time-ordered list merging events, steps, and retries	You want to read the run top-to-bottom as a story
`GET /runs/:id/events`	Raw, append-only lifecycle events (`eventType`, `payload`, `createdAt`)	You need the lowest-level record of what the engine did and when
`GET /runs/:id/audit`	Audit entries (`auditType`, `details`) for compliance/traceability	You need to show who/what triggered an action, for a review or an incident
`GET /runs/:id/retries`	Every retry attempt and its outcome	The run shows `retryCount > 0` and you want to see each attempt

All of these require Authorization: Bearer $TOKEN; a run from a workspace you're not a member of returns 404, not 403 — SnapLink doesn't reveal that a run exists if you can't see it.

Run detail¶

curl https://api.snaplink.cloudsolutionaccelerators.com/api/v1/runs/run_00a11b22c33d \
  -H "Authorization: Bearer $TOKEN"

{ "ok": true, "data": {
  "run": { "id": "run_00a11b22c33d", "workspaceId": "ws_92a1c4f0e7b3", "flowId": "flow_1a2b3c4d5e6f",
    "flowVersionId": "ver_00002", "status": "succeeded", "triggerType": "webhook",
    "attempts": 1, "startedAt": "2026-07-02T14:05:01.000Z", "completedAt": "2026-07-02T14:05:01.400Z",
    "failureReason": null, "createdAt": "2026-07-02T14:05:00.900Z" },
  "steps": [
    { "id": "step_1", "executionRunId": "run_00a11b22c33d", "stepNumber": 1, "stepType": "action",
      "connectorKey": "slack", "actionType": "send_message", "status": "succeeded", "attempt": 1,
      "startedAt": "2026-07-02T14:05:01.100Z", "completedAt": "2026-07-02T14:05:01.400Z",
      "errorCode": null, "failureReason": null }
  ],
  "retries": [],
  "restInvocations": [],
  "webhookInvocations": [ { "...": "the inbound trigger call metadata" } ]
} }

Notice what's not there: no request bodies, no response bodies, no secrets — just status, timing, and error codes. That's deliberate (see Security).

Timeline¶

curl https://api.snaplink.cloudsolutionaccelerators.com/api/v1/runs/run_00a11b22c33d/timeline \
  -H "Authorization: Bearer $TOKEN"

{ "ok": true, "data": { "timeline": [
  { "at": "2026-07-02T14:05:00.900Z", "kind": "event", "type": "run.created", "label": "Run created", "detail": { "...": "..." } },
  { "at": "2026-07-02T14:05:01.100Z", "kind": "step", "type": "step.started", "label": "Slack: send message — started", "detail": { "...": "..." } },
  { "at": "2026-07-02T14:05:01.400Z", "kind": "step", "type": "step.succeeded", "label": "Slack: send message — succeeded", "detail": { "...": "..." } }
] } }

This is the fastest way to read "what happened, in order" without cross-referencing steps, events, and retries yourself.

Events¶

curl https://api.snaplink.cloudsolutionaccelerators.com/api/v1/runs/run_00a11b22c33d/events \
  -H "Authorization: Bearer $TOKEN"

Returns { events: [ { id, executionRunId, workspaceId, eventType, payload, createdAt } ] } — the raw, append-only record the timeline is built from. Reach for this when you're debugging the engine's behavior itself, not just the outcome of a run.

Audit¶

curl https://api.snaplink.cloudsolutionaccelerators.com/api/v1/runs/run_00a11b22c33d/audit \
  -H "Authorization: Bearer $TOKEN"

Returns { audit: [ { id, executionRunId, workspaceId, auditType, details, createdAt } ] } — entries meant for compliance and traceability rather than debugging: who/what caused this run, and what actions it was authorized to take.

Retries¶

curl https://api.snaplink.cloudsolutionaccelerators.com/api/v1/runs/run_00a11b22c33d/retries \
  -H "Authorization: Bearer $TOKEN"

Empty if the run succeeded on the first attempt; otherwise one entry per retry attempt with its own status. Cross-reference with POST /executions/:id/retry, which starts a brand-new run (a fresh runId) rather than mutating the original.

Best practices¶

Start with /timeline for a human read; drop to /events or /audit only when you need the raw record.
Grab the runId any time you contact support — it's the single fastest way to point someone at exactly what happened.
Remember runs are pinned to the flowVersionId that produced them — a run's history never silently changes because you edited the flow later.

FAQ¶

How long is history kept? Runs are retained per your workspace's retention window. Can I export this? Yes, via these API endpoints; a UI export button is Planned.

If something goes wrong¶

If you're staring at a failed or retry_exhausted run and need to know why, the Flow Debugger turns this same data into a plain-English failure cause and suggested fix. For broader failure patterns, see Execution failures.

Related: Monitoring Runs · Flow Debugging · Security