`GET /api/runs/{id}` -- one run plus its descendant run tree. A run outside the caller's workspace maps to `NotFound`.
const url = 'https://example.com/api/runs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0';const options = {method: 'GET', headers: {cookie: 'supacloud_session=<supacloud_session>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url https://example.com/api/runs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \ --cookie supacloud_session=<supacloud_session>Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Run ID
Responses
Section titled “Responses”Run detail with descendant tree
A run plus its descendant runs – the GET /api/runs/{id} body.
children is flattened for presentation, so loop frames expose iteration
anchors and their per-iteration node runs in the same drill-down response.
object
#708 M2 — the autonomy policy SNAPSHOT this run was BOUND to at launch
(runs.autonomy_policy_json, ADR 0045 §11.4). The run/task-detail drift view
diffs it against the currently-resolved policy to mark axes that changed since the
run launched. None for a run with no bound snapshot (a legacy pre-Stage-4 run).
object
Which tool calls raise a human clarification ask (relaxes as autonomy rises).
false ⇒ the global/auto dispatcher does nothing (manual trigger only).
Signed nudge intended for the router’s effort selection (-1 economical · 0
balanced · +1 generous). An i8 (not an enum) so a consumer can add it to a
numeric effort index and clamp; it is intentionally a small bounded range.
NOTE: this axis is currently snapshot-only / informational (the sole such axis;
[AskThreshold] and [MergePolicy] are wired) — it is resolved, override-clamped and
recorded into runs.autonomy_policy_json (and exposed in the FE policy
preview), but no router pass reads it yet (routing effort is still derived
solely from item severity). It is a forward axis not yet consumed; wiring it
into classify_routing is a follow-up phase.
The upper bound the merge step is clamped to.
Agent cost + token usage for this run’s task (task_id), folded in by the
list handler for the runs-board cost column. None for a run with no task
(workflow / script / app / node runs) or no recorded outcome.
#626 (S1 contract-request, §28 StepInspector) — this run’s input payload,
projected from trigger_context.input (the raw trigger_context stays
unexposed — only this declared-input sub-key is surfaced, mirroring
source_issue); None when the step recorded no input.
The run kind (runs.kind CHECK). Runtime stays String; the spec
narrows it to the closed [RunKindSpec].
Issue #110: when this run was parked in queued. Stays set after the
run promotes to starting so the runs view can surface the wait time.
The run’s output JSON — for a human child run this is the approval
prompt ({ title, instructions }) while waiting, and the recorded
decision once decided. The runs view renders the human approve/reject
affordance from it.
#626 (S1 contract-request, §28 StepInspector) — the per-attempt retry
history of this workflow-node step (every attempt sharing this run’s
workflow_node_key + iteration_index in the same run tree), sorted by
attempt; None for a step that never retried (single attempt) or a
non-step run. Populated by the GET /api/runs/{id} detail handler, which
alone has the sibling attempt rows.
#626 (S1 contract-request, §28 StepInspector) — one attempt of a retried
workflow-node step, for the inspector’s retry-history tab. Derived from the
per-attempt runs rows of the same workflow_node_key + iteration_index.
object
The attempt’s run status (runs.status CHECK), spec-narrowed.
The run status (runs.status CHECK). Runtime stays String; the spec
narrows it to the closed [RunStatusSpec].
object
#708 M2 — the autonomy policy SNAPSHOT this run was BOUND to at launch
(runs.autonomy_policy_json, ADR 0045 §11.4). The run/task-detail drift view
diffs it against the currently-resolved policy to mark axes that changed since the
run launched. None for a run with no bound snapshot (a legacy pre-Stage-4 run).
object
Which tool calls raise a human clarification ask (relaxes as autonomy rises).
false ⇒ the global/auto dispatcher does nothing (manual trigger only).
Signed nudge intended for the router’s effort selection (-1 economical · 0
balanced · +1 generous). An i8 (not an enum) so a consumer can add it to a
numeric effort index and clamp; it is intentionally a small bounded range.
NOTE: this axis is currently snapshot-only / informational (the sole such axis;
[AskThreshold] and [MergePolicy] are wired) — it is resolved, override-clamped and
recorded into runs.autonomy_policy_json (and exposed in the FE policy
preview), but no router pass reads it yet (routing effort is still derived
solely from item severity). It is a forward axis not yet consumed; wiring it
into classify_routing is a follow-up phase.
The upper bound the merge step is clamped to.
Agent cost + token usage for this run’s task (task_id), folded in by the
list handler for the runs-board cost column. None for a run with no task
(workflow / script / app / node runs) or no recorded outcome.
#626 (S1 contract-request, §28 StepInspector) — this run’s input payload,
projected from trigger_context.input (the raw trigger_context stays
unexposed — only this declared-input sub-key is surfaced, mirroring
source_issue); None when the step recorded no input.
The run kind (runs.kind CHECK). Runtime stays String; the spec
narrows it to the closed [RunKindSpec].
Issue #110: when this run was parked in queued. Stays set after the
run promotes to starting so the runs view can surface the wait time.
The run’s output JSON — for a human child run this is the approval
prompt ({ title, instructions }) while waiting, and the recorded
decision once decided. The runs view renders the human approve/reject
affordance from it.
#626 (S1 contract-request, §28 StepInspector) — the per-attempt retry
history of this workflow-node step (every attempt sharing this run’s
workflow_node_key + iteration_index in the same run tree), sorted by
attempt; None for a step that never retried (single attempt) or a
non-step run. Populated by the GET /api/runs/{id} detail handler, which
alone has the sibling attempt rows.
#626 (S1 contract-request, §28 StepInspector) — one attempt of a retried
workflow-node step, for the inspector’s retry-history tab. Derived from the
per-attempt runs rows of the same workflow_node_key + iteration_index.
object
The attempt’s run status (runs.status CHECK), spec-narrowed.
The run status (runs.status CHECK). Runtime stays String; the spec
narrows it to the closed [RunStatusSpec].
Example
{ "autonomy_policy_json": { "ask_threshold": "always", "merge_ceiling": "none" }, "kind": "agent", "retries": [ { "status": "pending" } ], "status": "pending", "children": [ { "autonomy_policy_json": { "ask_threshold": "always", "merge_ceiling": "none" }, "kind": "agent", "retries": [ { "status": "pending" } ], "status": "pending" } ]}Structured client error
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
Machine-readable, stable error code.
Present only on a quota-exceeded 403 — the inline upgrade-CTA payload.
object
The entitlement feature key that was hit, e.g. apps.max_count.
The plan’s limit for this key.
Where to send the user to upgrade.
Current usage (count or bytes, per the key).
Human-readable message (the server’s English text; the client may localize
by code).
Example
{ "code": "not_found"}Authentication required
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
Machine-readable, stable error code.
Present only on a quota-exceeded 403 — the inline upgrade-CTA payload.
object
The entitlement feature key that was hit, e.g. apps.max_count.
The plan’s limit for this key.
Where to send the user to upgrade.
Current usage (count or bytes, per the key).
Human-readable message (the server’s English text; the client may localize
by code).
Example
{ "code": "not_found"}Permission denied
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
Machine-readable, stable error code.
Present only on a quota-exceeded 403 — the inline upgrade-CTA payload.
object
The entitlement feature key that was hit, e.g. apps.max_count.
The plan’s limit for this key.
Where to send the user to upgrade.
Current usage (count or bytes, per the key).
Human-readable message (the server’s English text; the client may localize
by code).
Example
{ "code": "not_found"}Structured server error
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
Machine-readable, stable error code.
Present only on a quota-exceeded 403 — the inline upgrade-CTA payload.
object
The entitlement feature key that was hit, e.g. apps.max_count.
The plan’s limit for this key.
Where to send the user to upgrade.
Current usage (count or bytes, per the key).
Human-readable message (the server’s English text; the client may localize
by code).
Example
{ "code": "not_found"}