`GET /api/runs` — list workspace-scoped runs, newest first, with optional `status` / `kind` / `project_id` / `task_id` filters. Top-level runs only by default; `include_children=true` also surfaces workflow node child runs.

GET

/api/runs

const url = 'https://example.com/api/runs';
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 \
  --cookie supacloud_session=<supacloud_session>

Authorizations

cookie_auth

Parameters

Query Parameters

status

string

kind

string

project_id

string format: uuid

task_id

string format: uuid

app_id

string format: uuid

include_children

boolean

Include workflow node child runs. Default lists only top-level runs.

top_level

boolean

Force parent_run_id IS NULL regardless of include_children — the V13 Agents tab uses this to keep child agent runs of a workflow out of the top-level Agents listing.

since

string format: date-time

Lower bound on created_at (RFC3339) — the time-range preset the runs view’s scatter and the dashboard’s last-24h widget drive (R6).

until

string format: date-time

Upper bound on created_at (RFC3339) — paired with since (R6).

trigger

string

#358 trigger-source filter id (manual/schedule/webhook/linear/notion) — mapped to the matching trigger_kind set server-side (was client-side).

limit

integer format: int64

offset

integer format: int64

Responses

200

List of runs in the active workspace

application/json

Array<object>

object

app_id

string | null format: uuid

attempt

required

integer format: int32

autonomy_policy_json

One of:

null
object

null

#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

ask_threshold

required

Which tool calls raise a human clarification ask (relaxes as autonomy rises).

string

Allowed values: always risky_only never

dispatch_enabled

required

false ⇒ the global/auto dispatcher does nothing (manual trigger only).

boolean

effort_bias

required

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.

integer format: int32

merge_ceiling

required

The upper bound the merge step is clamped to.

string

Allowed values: none pr_only auto_on_green full_auto

container_id

string | null

cost_usd

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.

number | null format: double

created_at

required

string format: date-time

deadline_at

string | null format: date-time

error_message

string | null

finished_at

string | null format: date-time

fired_handle

string | null

git_branch

string | null

required

string format: uuid

input

#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.

input_tokens

integer | null format: int64

iteration_index

integer | null format: int32

kind

required

The run kind (runs.kind CHECK). Runtime stays String; the spec narrows it to the closed [RunKindSpec].

string

Allowed values: agent workflow script app 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 connector

output_tokens

integer | null format: int64

parent_run_id

string | null format: uuid

project_id

string | null format: uuid

queued_at

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.

string | null format: date-time

result

required

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.

retries

#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.

Array<object> | null

#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

attempt

required

integer format: int32

error_message

string | null

finished_at

string | null format: date-time

started_at

string | null format: date-time

status

required

The attempt’s run status (runs.status CHECK), spec-narrowed.

string

Allowed values: pending starting running waiting completed failed cancelled skipped queued

script_id

string | null format: uuid

source_issue

One of:

null
object

null

The source issue (id/url/title) this run was launched from, projected from trigger_context; None for runs with no issue source. (#532 WS-1-runs.)

object

string | null

title

string | null

url

string | null

started_at

string | null format: date-time

status

required

The run status (runs.status CHECK). Runtime stays String; the spec narrows it to the closed [RunStatusSpec].

string

Allowed values: pending starting running waiting completed failed cancelled skipped queued

task_id

string | null format: uuid

trigger_kind

string | null

workflow_id

string | null format: uuid

workflow_node_key

string | null

workspace_id

required

string format: uuid

Example

[
  {
    "autonomy_policy_json": {
      "ask_threshold": "always",
      "merge_ceiling": "none"
    },
    "kind": "agent",
    "retries": [
      {
        "status": "pending"
      }
    ],
    "status": "pending"
  }
]

400

Structured client error

application/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
object

null

Present only on a quota-exceeded 403 — the inline upgrade-CTA payload.

object

key

required

The entitlement feature key that was hit, e.g. apps.max_count.

string

limit

required

The plan’s limit for this key.

integer format: int64

upgrade_url

required

Where to send the user to upgrade.

string

used

required

Current usage (count or bytes, per the key).

integer format: int64

error

required

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

string

Example

{
  "code": "not_found"
}

401

Authentication required

application/json

object

code

required

Machine-readable, stable error code.

string

details

One of:

null
object

null

Present only on a quota-exceeded 403 — the inline upgrade-CTA payload.

object

key

required

The entitlement feature key that was hit, e.g. apps.max_count.

string

limit

required

The plan’s limit for this key.

integer format: int64

upgrade_url

required

Where to send the user to upgrade.

string

used

required

Current usage (count or bytes, per the key).

integer format: int64

error

required

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

string

Example

{
  "code": "not_found"
}

403

Permission denied

application/json

object

code

required

Machine-readable, stable error code.

string

details

One of:

null
object

null

Present only on a quota-exceeded 403 — the inline upgrade-CTA payload.

object

key

required

The entitlement feature key that was hit, e.g. apps.max_count.

string

limit

required

The plan’s limit for this key.

integer format: int64

upgrade_url

required

Where to send the user to upgrade.

string

used

required

Current usage (count or bytes, per the key).

integer format: int64

error

required

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

string

Example

{
  "code": "not_found"
}

500

Structured server error

application/json

object

code

required

Machine-readable, stable error code.

string

details

One of:

null
object

null

Present only on a quota-exceeded 403 — the inline upgrade-CTA payload.

object

key

required

The entitlement feature key that was hit, e.g. apps.max_count.

string

limit

required

The plan’s limit for this key.

integer format: int64

upgrade_url

required

Where to send the user to upgrade.

string

used

required

Current usage (count or bytes, per the key).

integer format: int64

error

required

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

string

Example

{
  "code": "not_found"
}