---
title: "Get run"
method: GET
path: "/runs/{id}"
tags: ["Runs"]
---

# Get run

`GET /runs/{id}`

## Request

- Base URL: `https://api.edgaze.ai/v1`
- URL: `https://api.edgaze.ai/v1/runs/{id}`
- Auth: HTTP bearer

Read the run's canonical status, sanitized failure reason, buyer-facing displayed charge, and outputs. Rate limiting: reads are not metered per-key today — only POST /runs is (60/minute). Reads may become metered without a breaking change, so treat 429 with `Retry-After` as possible on any endpoint and back off rather than polling in a tight loop. For run progress prefer GET /runs/{id}/stream, or poll GET /runs/{id} no more than once per second.

## Path parameters

- `id` string, required: UUID returned from POST /runs.

## Response `200`

Run detail.

- Run: Response body for GET /runs/{id}.
  - `id` string, uuid, required
  - `status` 'pending' | 'running' | 'suspended' | 'completed' | 'failed' | 'cancelled', required: Canonical run status exposed by the public API.
  - `reason` string, nullable, required: Buyer-safe failure explanation. Non-null only when `status` is `failed`; provider-specific detail is deliberately generalized.
  - `suspended` boolean, required: True exactly when `status` is `suspended`; kept as a separate flag so a caller can test for 'waiting' without matching on the status enum. A run suspends for one of two reasons, reported as `reason` on the `run.suspended` event: `wait_timer` (a delay node) resumes itself when the timer fires, while `wait_signal` (the workflow needs credentials) waits for the buyer to supply them on the web run page. The API cannot resume a run; POST /runs/{id}/cancel is the only way for an API caller to end one early.
  - `workflowId` string, uuid, nullable, required
  - `workflowVersionId` string, uuid, nullable, required
  - `startedAt` string, date-time, nullable, required
  - `completedAt` string, date-time, nullable, required
  - `displayedChargeUsd` number, nullable, required: Buyer-facing charge. `null` until the run settles. USD amount as a JSON number with up to six decimal places. Preserve the documented precision and do not round intermediate calculations to two decimal places.
  - `billingStatus` 'pending' | 'settled' | 'not_charged', required: Whether the buyer-facing charge for this run is still pending, finalized, or not applicable.
  - `outcome` 'completed' | 'completed_with_issues', nullable, required: Set when `status` is `completed`, null otherwise. `completed`: every step finished. `completed_with_issues`: the run returned its outputs but some steps failed; it is charged for the completed steps' compute only, without the creator's price.
  - `queue` RunQueue, required: Edgaze starts runs immediately while it has capacity. At full capacity a run waits in line and starts automatically, in order; nothing is needed from the caller and nothing is charged for waiting. A run that waits past its limit fails with a reason and is not charged.
    - `state` 'waiting' | 'starting', required: `waiting`: in line for capacity. `starting`: it just left the line and is being started.
    - `position` integer, required: Place in line, 1 = next. 0 while starting.
    - `etaSeconds` integer, nullable, required: Estimated seconds until it starts, or null when unknown.
  - `outputs` RunOutputField[], required
    - `nodeId` string, required
    - `name` string, required
    - `type` string, required
    - `value` unknown, required

## Other responses

- `401`: Invalid or missing API key.
- `403`: API key is missing the required scope.
- `404`: Run not found (also returned for cross-tenant reads).
- `413`: The run's outputs are too large to return in one response.
- `500`: Unexpected server error.

---

[API](https://skmtc.dev/edgaze/apis/edgaze-api.md) · [All operations](https://skmtc.dev/edgaze/apis/edgaze-api/llms.txt) · [OpenAPI document](https://skmtc.dev/edgaze/apis/edgaze-api/revisions/cfc6436d2f90?raw)