JSON:API · v1
Runs and monitoring
Follow workflow runs and inspect their per-step outcomes.
Bearer authentication
api_read / api_write by operation
Stable
Operations
GET
List workflow runs
/api/json/v1/workflow_runs
List workflow runs visible to the authenticated service account.
GET
Retrieve a workflow run
/api/json/v1/workflow_runs/{id}
Retrieve one workflow run visible to the authenticated service account.
GET
List workflow run steps
/api/json/v1/workflow_runs/{workflow_run_id}/steps
Inspect status, timing, and safe error metadata for each step in one workflow run.
Objects and fields
These are the reviewed public attributes. Fields omitted from this contract are not part of the API, even when they exist internally.
Workflow run
type: workflow_run
12 fields
Public JSON:API resource object for workflow runs.
| Field | Type | Presence | Description |
|---|---|---|---|
| completed_at | object | null | Optional · nullable | Timestamp when processing reached a terminal state. |
| derivation_semantics_version | integer | null | Optional · nullable | The derivation semantics this run journaled under. A resume that would rebuild a step checks it against the engine reading it; see `Dash.Workflows.Derivation`. Field included by default. |
| error_message | string | null | Optional · nullable | Safe failure summary when processing did not complete. |
| event_id | string | null | Optional · nullable | The ingestion-ledger Event (public schema) this run came from, when it came from an external delivery. Null for a run nothing was delivered for — a scheduled firing, which has no arrival to point at. Field included by default. |
| generation | integer | Required | The executor token for this run. A transition or journal write carrying an older generation has been fenced by a reclaim. Field included by default. |
| parent_run_id | string | null | Optional · nullable | Parent run id returned by the public contract. |
| parent_step_identifier | string | null | Optional · nullable | The subflow step of `parent_run` that is waiting for this run. Set together with parent_run_id, and only on a child run. Field included by default. |
| snapshot_id | string | Required | Snapshot id returned by the public contract. |
| started_at | object | null | Optional · nullable | Timestamp when processing started. |
| state | enum: pending | running | completed | suspended | failed | Required | Current lifecycle or execution state. |
| suspend_reason | enum: delay | yield | rate | provider_unavailable | manual | waiting_child | null | Optional · nullable | Why the run released its slot to wait. Cleared when it resumes. Field included by default. |
| workflow_id | string | Required | Workflow that owns or produced the resource. |