---
title: "List runs"
method: GET
path: "/runs"
tags: ["Runs"]
---

# List runs

`GET /runs`

## Request

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

Return the caller's own runs, newest first. Projected from the indexed run row rather than folded from the event log, so it omits `outputs` and `reason` and reports a suspended run as `running` — read GET /runs/{id} for a single run in full. 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.

## Query parameters

- `status` 'pending' | 'running' | 'completed' | 'failed' | 'cancelled': Run status as reported by the run list. A suspended run is reported as `running` — read GET /runs/{id} for the precise state.
- `workflow` string, uuid: Return only runs of this workflow.
- `offset` integer: Pagination offset. Defaults to 0.
- `limit` integer: Page size (max 50). Defaults to 24.

## Response `200`

Paginated run history.

- RunListResponse: Response body for GET /runs.
  - `runs` RunListItem[], required
    - `id` string, uuid, required
    - `status` 'pending' | 'running' | 'completed' | 'failed' | 'cancelled', required: Run status as reported by the run list. A suspended run is reported as `running` — read GET /runs/{id} for the precise state.
    - `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
    - `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.
  - `pagination` Pagination, required: Offset-based pagination cursor for list endpoints.
    - `offset` integer, required: Offset of the first row in this page.
    - `limit` integer, required: Page size actually applied (max 50).
    - `hasMore` boolean, required: True when another page follows this one.

## Other responses

- `400`: Invalid query parameters.
- `401`: Invalid or missing API key.
- `403`: API key is missing the required scope.
- `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)