# List runs

> operationId: `listRuns`


## Request

This endpoint lists execution records. The templateId parameter is optional. The status parameter accepts only a single status, not a comma-separated string. The active states are queued/preparing/running/cancel_requested, and all other records are in a terminal state. The failed status includes runs whose stop could not be confirmed and runs that were recovered after the desktop client exited. Neither these records nor stopped records mean that side effects on the website have stopped, so still check isolation.

- **Prerequisites**: The credentials can read runs in the target scope.
- **Authentication**: Same as the rest of the Local API; see [Authentication](/api-reference/getting-started/authentication). Resources belong to the current account/team data scope.
- **Side effects**: None. This call doesn't write business data.
- **Completion signal**: 200 returns run summaries and pagination information.
- **Retries**: Read-only calls can be retried. On 429 or 503, back off as indicated by Retry-After.


### Endpoint

```http
GET /api/rpa/browser/v1/runs
```

Local API: `http://127.0.0.1:<port>/api/rpa/browser/v1/runs`. Use the port configured in the client.

### Headers

| Parameter | Type | Required | Description and constraints |
|  --- | --- | --- | --- |
| `Authorization` | string | When Local API authentication is enabled | See [Authentication](/api-reference/getting-started/authentication). |


### Path parameters

None.

### Query parameters

| Parameter | Type | Required | Description and constraints |
|  --- | --- | --- | --- |
| `page` | integer | No | Page number, starting at 1. Minimum 1; default 1 |
| `pageSize` | integer | No | Items per page. Default 20, maximum 100. Minimum 1; maximum 100; default 20 |
| `templateId` | string | No | Target template ID (the cloud ID of the template in Custom Templates in the client, a numeric string). Min length 1; max length 128 |
| `status` | [RunStatus](/browser-rpa/api/data-types#runstatus) | No | Current status, checked against the model's enum. |


### Request body

No request body.

### Request example

This is a documentation example; it was not sent to a live client. Set `RPA_BASE_URL` as described in [API conventions](/browser-rpa/api/common). Resource variables, the catalog revision, and ETags come from actual responses.

```bash
curl -i -X GET "${RPA_BASE_URL}/runs?page=1&pageSize=20"
```

## Response

### 200

200 returns run summaries and pagination information.

Body: `application/json`. The top-level `data` uses the model below. For `meta`, see [Metadata](/browser-rpa/api/data-types#metadata).

| Field | Type | Required | Description and constraints |
|  --- | --- | --- | --- |
| `items` | array<[RunSummary](/browser-rpa/api/data-types#runsummary)> | Yes | Array of entries on the current page or for the current resource. |
| `total` | integer | Yes | Total number of matches. Minimum 0. |
| `page` | integer | Yes | Page number, starting at 1. Minimum 1. |
| `pageSize` | integer | Yes | Items per page. Default 20, maximum 100. Minimum 1; maximum 100. |


### Response example

All IDs, timestamps, hashes, and run results are sample data. They don't indicate that the sample was executed.

```json
{
  "data": {
    "items": [
      {
        "id": "run_example",
        "status": "queued",
        "template": {
          "id": "template_example",
          "title": "Read the page URL",
          "version": 1,
          "revisionId": "revision_example_1"
        },
        "environment": {
          "id": "environment_example",
          "name": "Example browser profile"
        },
        "createdAt": 1793318400000,
        "startedAt": null,
        "endedAt": null,
        "startAfter": null,
        "hasNodeErrors": false,
        "isolation": null
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 20
  },
  "meta": {
    "requestId": "7d498f20-7bab-4e59-9b05-88daf51230e9",
    "catalogRevision": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  }
}
```

### Error responses

For common 400/401/403/404/429/5xx errors and failure fields, see [Errors and recovery](/browser-rpa/api/common#errors-and-recovery). Error response example (403):

```json
{
  "error": {
    "code": "RPA_PERMISSION_DENIED",
    "message": "The request Host or Origin is not allowed, or the current identity can't access the target environment",
    "retryable": false,
    "issues": [],
    "details": null
  },
  "meta": {
    "requestId": "7d498f20-7bab-4e59-9b05-88daf51230e9",
    "catalogRevision": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  }
}
```

## Related

[Local API reference](/browser-rpa/local-api) · [API conventions](/browser-rpa/api/common) · [Data models](/browser-rpa/api/data-types) · [Workflow structure](/browser-rpa/api/workflow) · [Quickstart](/browser-rpa/quickstart)