---
title: List Runs
description: Page through your account's run history, filtered by status or workflow.
source: https://www.edgaze.ai/docs/api/list-runs
section: api
---
# List Runs

> Page through your account's run history, filtered by status or workflow.

```apibar
list-runs
```

## Overview

**Audience: Developers building a run history view.**

Returns the runs owned by the API key's account, newest first. Every run counts: those started by any key on the account and those started from the web UI both appear here.

Rows are projected from the indexed run record rather than folded from the event log, which keeps the endpoint cheap enough to poll on a dashboard. The trade-off is that `outputs` and `reason` are omitted. Read [Get Run](/docs/api/get-run) when you need a single run in full.

Runs are scoped to the API key owner, so this endpoint never returns another account's runs.

```doccallout
{"variant":"info","text":"Page with offset and limit while pagination.hasMore is true. Narrow with status or workflow. Read GET /runs/{id} for outputs and failure reasons."}
```

## Authorization

```apiscopes
list-runs
```

## Parameters

```apiparams
list-runs
```

## Response

Example payloads are in the request/response panel above.

Each row carries `id`, `status`, `workflowId`, `workflowVersionId`, `startedAt`, `completedAt`, `displayedChargeUsd`, and `billingStatus`. The `pagination` object reports the `offset` and `limit` that were applied plus `hasMore`.

## Edge cases

```apiedges
list-runs
```

---

## Endpoint reference
- **Method:** `GET`
- **Path:** `https://api.edgaze.ai/v1/runs`
- **Scopes:** `run:read`
## Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `Authorization` | header | string | yes | Bearer token with run:read scope. |
| `status` | query | string | no | Filter by status: pending, running, completed, failed, or cancelled. |
| `workflow` | query | string | no | Only return runs of this workflow id. |
| `offset` | query | integer | no | Pagination offset. Defaults to 0. |
| `limit` | query | integer | no | Page size from 1 to 50. Defaults to 24. |
## Example responses

### 200 Success
```json
{
  "runs": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "status": "completed",
      "workflowId": "550e8400-e29b-41d4-a716-446655440000",
      "workflowVersionId": "ver_abc123",
      "startedAt": "2026-07-08T10:00:00.000Z",
      "completedAt": "2026-07-08T10:00:42.000Z",
      "displayedChargeUsd": 2.5,
      "billingStatus": "settled"
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 24,
    "hasMore": false
  }
}
```

### 400 Invalid query
```json
{
  "error": {
    "code": "invalid_request",
    "message": "limit must be an integer from 1 to 50."
  }
}
```

## Edge cases

### Suspended runs read as running

Suspension is only visible in the event log, so a suspended run is reported as running here. GET /runs/{id} reports the precise state.

### Owner-scoped

Only runs belonging to the API key's account are returned, including runs started from the web UI.

### No outputs

Rows omit outputs and reason to keep the query flat. Fetch GET /runs/{id} for those fields.