Skip to content
SupaCloud Docs
Select themeSelect language

`GET /api/workflows/runs/{run_id}` — the run (status + timestamps) plus each step's task state so the UI can render per-step progress.

GET
/api/workflows/runs/{run_id}
curl --request GET \
  --url https://example.com/api/workflows/runs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
run_id
required
string format: uuid

Workflow run id

Responses

Section titled “Responses”

200

Section titled “200”
Media typeapplication/json

A workflow run plus its per-node states — GET /api/workflows/runs/{run_id}.

steps keeps the per-node step_key/status/task_id list the web run view consumes; nodes is the typed per-node run view so the UI can show gate branching. Both are built from the workflow run’s child runs.

object
finished_at
string | null format: date-time
id
required
string format: uuid
nodes
required
Array<object>

One node’s typed run-state (ADR 0020 V2/V3) — kind and fired_handle let the UI render which branch a gate or human node took; config carries a human node’s { title, instructions } approval prompt.

object
config
required
fired_handle
string | null
kind
required

The kind of a workflow node.

Doubles as the OpenAPI spec mirror for the closed kind string on the workflow node/step + run-node DTOs: StepResponse.kind / NodeResponse.kind narrow to this via #[schema(value_type = NodeKindSpec)]. The variant set is the workflow_nodes.kind CHECK (migration 157); the serde snake_case rename matches as_db_str one-for-one, so the spec enum equals what the handlers serialize.

string
Allowed values: agent gate human end code notify_telegram notify_email notify_webhook notify_discord loop db_query db_execute http_request transform wait_event llm_classify imap_ack app connector
node_key
required
string
result
required
state
required
string
task_id
string | null format: uuid
started_at
string | null format: date-time
status
required
string
steps
required
Array<object>

The per-node run state of a run — what the UI renders for progress. step_key is the node’s key; task_id is the materialized step-task for an agent node (null for gate/human/end nodes).

object
status
required
string
step_key
required
string
task_id
string | null format: uuid
workflow_id
required
string format: uuid
Example
{
  "nodes": [
    {
      "kind": "agent"
    }
  ]
}

400

Section titled “400”

Structured client error

Media typeapplication/json

The canonical JSON body of every error response — the single source of truth the frontend binds to. Every AppError serializes as this exact shape, and the generated OpenAPI component ApiErrorBody (with its ErrorCode enum) is what the frontend error schema is generated from, so there is no hand-written error schema on either end.

object
code
required

Machine-readable, stable error code.

string
Allowed values: not_found unauthorized forbidden bad_request unprocessable precondition_failed conflict method_not_allowed rate_limited quota_exceeded database_error docker_error vault_error internal_error
details
One of:
null
error
required

Human-readable message (the server’s English text; the client may localize by code).

string
Example
{
  "code": "not_found"
}

401

Section titled “401”

Authentication required

Media typeapplication/json

The canonical JSON body of every error response — the single source of truth the frontend binds to. Every AppError serializes as this exact shape, and the generated OpenAPI component ApiErrorBody (with its ErrorCode enum) is what the frontend error schema is generated from, so there is no hand-written error schema on either end.

object
code
required

Machine-readable, stable error code.

string
Allowed values: not_found unauthorized forbidden bad_request unprocessable precondition_failed conflict method_not_allowed rate_limited quota_exceeded database_error docker_error vault_error internal_error
details
One of:
null
error
required

Human-readable message (the server’s English text; the client may localize by code).

string
Example
{
  "code": "not_found"
}

403

Section titled “403”

Permission denied

Media typeapplication/json

The canonical JSON body of every error response — the single source of truth the frontend binds to. Every AppError serializes as this exact shape, and the generated OpenAPI component ApiErrorBody (with its ErrorCode enum) is what the frontend error schema is generated from, so there is no hand-written error schema on either end.

object
code
required

Machine-readable, stable error code.

string
Allowed values: not_found unauthorized forbidden bad_request unprocessable precondition_failed conflict method_not_allowed rate_limited quota_exceeded database_error docker_error vault_error internal_error
details
One of:
null
error
required

Human-readable message (the server’s English text; the client may localize by code).

string
Example
{
  "code": "not_found"
}

404

Section titled “404”

Run not found

Media typeapplication/json

The canonical JSON body of every error response — the single source of truth the frontend binds to. Every AppError serializes as this exact shape, and the generated OpenAPI component ApiErrorBody (with its ErrorCode enum) is what the frontend error schema is generated from, so there is no hand-written error schema on either end.

object
code
required

Machine-readable, stable error code.

string
Allowed values: not_found unauthorized forbidden bad_request unprocessable precondition_failed conflict method_not_allowed rate_limited quota_exceeded database_error docker_error vault_error internal_error
details
One of:
null
error
required

Human-readable message (the server’s English text; the client may localize by code).

string
Example
{
  "code": "not_found"
}

500

Section titled “500”

Structured server error

Media typeapplication/json

The canonical JSON body of every error response — the single source of truth the frontend binds to. Every AppError serializes as this exact shape, and the generated OpenAPI component ApiErrorBody (with its ErrorCode enum) is what the frontend error schema is generated from, so there is no hand-written error schema on either end.

object
code
required

Machine-readable, stable error code.

string
Allowed values: not_found unauthorized forbidden bad_request unprocessable precondition_failed conflict method_not_allowed rate_limited quota_exceeded database_error docker_error vault_error internal_error
details
One of:
null
error
required

Human-readable message (the server’s English text; the client may localize by code).

string
Example
{
  "code": "not_found"
}