# List Runs

List the current account's Runs with optional filters and cursor pagination.

## Endpoint

items contains Run summaries, not full output. Retrieve an individual Run to read its result. nextCursor is null when no further page exists.

Use RFC3339 timestamps for createdFrom and createdTo. Keep filters unchanged while following a cursor. activeOnly selects Runs with HELD or REVIEW billing, including Runs whose execution has ended. status filters execution state; when both are supplied, both filters apply.

```
GET /v1/runs
```

## Parameters

| Name | Location | Type | Required | Constraints |
| --- | --- | --- | --- | --- |
| cursor | query | string | Optional | — |
| limit | query | integer | Optional | Minimum: 1; Maximum: 100; Default: 20 |
| status | query | string | Optional | QUEUED \| SUBMITTING \| RUNNING \| WAITING_PROVIDER \| SUCCEEDED \| FAILED \| CANCELED \| TIMED_OUT \| UNKNOWN |
| activeOnly | query | boolean | Optional | — |
| toolId | query | string | Optional | — |
| createdFrom | query | string | Optional | date-time |
| createdTo | query | string | Optional | date-time |

## Request example

Set PURRKEY_API_KEY in your trusted server or terminal environment. Replace any angle-bracket placeholders with values from your own inspection or Run.

```
curl --fail-with-body --request GET 'https://api.purrkey.app/v1/runs' \
  -H "Authorization: Bearer $PURRKEY_API_KEY"
```

## Successful response

Success HTTP status: 200. Top-level response fields are listed below. Conditional and nested requirements are defined in the downloadable OpenAPI contract.

| Field | Type | Required | Constraints |
| --- | --- | --- | --- |
| items | object[] | Required | — |
| nextCursor | string \| null | Required | — |

## Errors and related reading

- [Error handling](/docs/guides/errors): Read requestId, business codes and safe retry behavior.
- [Download OpenAPI](/docs/openapi.yaml): The complete HTTP contract, version 0.4.3.