# Runs

Scenario and routine runs, reports and artifacts.

Scenario and routine runs, reports and artifacts.

## listRuns

`GET /v1/runs`

Run history

| Parameter | In | Required | Type | What it is |
|---|---|---|---|---|
| `status` | query | no | `queued`, `binding`, `running`, `passed`, `failed`, `errored`, `cancelled` |  |
| `limit` | query | no | integer |  |
| `cursor` | query | no | string |  |

| Response | Means |
|---|---|
| 200 | Runs, newest first. |
| 4XX | Error (RFC 9457). |
| 5XX | Error (RFC 9457). |

MCP tools on this operation: [`list_runs`](/reference/mcp/list-runs/).

## startRun

`POST /v1/runs`

Start a scenario run on bound devices

Request body: `application/json` (`RunRequest`).

| Field | Type | What it is |
|---|---|---|
| `scenario` | one of several shapes |  |
| `routineId` | string |  |
| `bindings` | object | Role name to device id (or to a list for many-users roles). Unbound roles are matched automatically. |
| `params` | object |  |
| `record` | boolean |  |
| `tags` | array of string |  |

| Response | Means |
|---|---|
| 202 | Run started. `Run` |
| 4XX | Error (RFC 9457). |
| 5XX | Error (RFC 9457). |

MCP tools on this operation: [`run_scenario`](/reference/mcp/run-scenario/).

## getRun

`GET /v1/runs/{runId}`

Run status, per-role progress, failures

| Parameter | In | Required | Type | What it is |
|---|---|---|---|---|
| `runId` | path | yes | string |  |

| Response | Means |
|---|---|
| 200 | Run. `Run` |
| 4XX | Error (RFC 9457). |
| 5XX | Error (RFC 9457). |

MCP tools on this operation: [`get_run`](/reference/mcp/get-run/).

## cancelRun

`DELETE /v1/runs/{runId}`

Cancel a running scenario

| Parameter | In | Required | Type | What it is |
|---|---|---|---|---|
| `runId` | path | yes | string |  |

| Response | Means |
|---|---|
| 204 | Cancelled. |
| 4XX | Error (RFC 9457). |
| 5XX | Error (RFC 9457). |

## getReport

`GET /v1/runs/{runId}/report`

Run report as HTML, JUnit XML, or JSON

| Parameter | In | Required | Type | What it is |
|---|---|---|---|---|
| `runId` | path | yes | string |  |
| `format` | query | no | `html`, `junit`, `json` |  |

| Response | Means |
|---|---|
| 200 | Report. `RunReport` |
| 4XX | Error (RFC 9457). |
| 5XX | Error (RFC 9457). |

MCP tools on this operation: [`get_report`](/reference/mcp/get-report/).

## listArtifacts

`GET /v1/runs/{runId}/artifacts`

Screenshots, videos, logs and trees produced by a run

| Parameter | In | Required | Type | What it is |
|---|---|---|---|---|
| `runId` | path | yes | string |  |

| Response | Means |
|---|---|
| 200 | Artifacts. |
| 4XX | Error (RFC 9457). |
| 5XX | Error (RFC 9457). |