> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwairy.co/llms.txt
> Use this file to discover all available pages before exploring further.

# List runs

> List the recent runs of a workspace from newest to oldest with status, outcome counts and cursor pagination to follow answer collection after a run starts.

Lists workspace runs from newest to oldest. Use this endpoint to follow answer
collection after a run has been accepted. Read access is available from Growth
and Agency Growth.

**Authorization** `string` *required*

Bearer token for your team.

**brandId** `string` *required*

Workspace identifier. The workspace must belong to the token's team.

**limit** `integer` (default: 20)

Number of runs per page, from 1 to 20.

**cursor** `string`

Opaque `nextCursor` from the previous page. Omit for the first page.

## Response

Returns `200` with `success`, `runs`, `nextCursor`, `totalCount` and
`activeCount`. Counts describe the workspace, not only the returned page.
`nextCursor: null` means there is no further page. Responses are
`private, no-store`.

Each run includes identity and timestamps, `purpose`, `priority`, nullable
`scheduledFrequency`, `questionCount`, `modelCount`, `requestedCount`,
`plannedCount`, `planningCompletedAt`, `planningFailed`, `status`,
`counts`, `terminalCount` and `progressPercentage`.

Status is one of `QUEUED`, `PROCESSING`, `COMPLETED`,
`COMPLETED_WITH_WARNINGS`, `FAILED`, `CANCELLED` or `NO_WORK`.
`counts` distinguishes `success`, `warning`, `failed`, `cancelled`,
`processing`, `queued` and `skipped`. Progress is not a guarantee that every
requested answer succeeded; inspect the status and outcome counts.

## Synthetic request and response

```bash theme={null}
curl "https://www.qwairy.co/api/v1/brands/$BRAND_ID/runs?limit=20" \
  -H "Authorization: Bearer $QWAIRY_API_TOKEN"
```

```json theme={null}
{
  "success": true,
  "totalCount": 1,
  "activeCount": 0,
  "runs": [
    {
      "id": "55555555-0000-4000-8000-000000000000",
      "purpose": "MANUAL",
      "priority": "URGENT",
      "scheduledFrequency": null,
      "questionCount": 12,
      "modelCount": 2,
      "requestedCount": 24,
      "plannedCount": 24,
      "planningCompletedAt": "2026-09-01T09:00:01.000Z",
      "planningFailed": false,
      "createdAt": "2026-09-01T09:00:00.000Z",
      "updatedAt": "2026-09-01T09:03:00.000Z",
      "status": "COMPLETED",
      "counts": {
        "success": 24,
        "warning": 0,
        "failed": 0,
        "cancelled": 0,
        "processing": 0,
        "queued": 0,
        "skipped": 0
      },
      "terminalCount": 24,
      "progressPercentage": 100
    }
  ],
  "nextCursor": null
}
```

## Errors

Invalid cursors or limits return `400 INVALID_PARAMETER`; an inaccessible
workspace returns `404 BRAND_NOT_FOUND`. See [Error codes](https://docs.qwairy.co/developers/errors.md)
and honor `Retry-After` on `429`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.