# Runs

Run history and control. Every run, from any key in your organization, is on record with its attempts, charges and routing reason.

## List runs

```text
GET /v1/runs
```

```bash
curl "https://api.routergrowth.com/v1/runs?status=succeeded&capability=contact.find&limit=50" \
  -H "Authorization: Bearer $ROUTERGROWTH_API_KEY"
```

| Query param | Notes |
| --- | --- |
| `status` | filter by lifecycle status (`succeeded`, `failed`, `no_match`, ...) |
| `capability` | filter by capability slug |
| `provider` | filter by the provider that served the run |
| `limit` | default 50, max 200; newest first |

Returns `{"items": [run, ...]}` where each run has the same shape as the [run response](/docs/api/run).

## Get one run

```text
GET /v1/runs/{run_id}
```

Poll this for runs that returned `202`; add `?wait=60` (max 120) to long-poll until the run finishes. `POST /v1/runs/{run_id}/cancel` stops a run that is still queued (`stoppable: true`); a run already at the provider cannot be stopped. A run that does not exist (or belongs to another organization) returns `invalid_request`.

## Cancel a run

```text
POST /v1/runs/{run_id}/cancel
```

Only runs that have not started executing (`created`, `reserved`, `queued`) can be cancelled. A run already `running` or finished returns `invalid_request` with the current status.