POST/api/public/v1/runsruns:write
Start a run of a named plan
Dispatches the plan's automated tests and returns immediately with a runId to poll. Manual cases in the plan are not included — a person walks those. Quarantined tests are excluded.
Requires the runs:write scope. This endpoint spends tokens, at the same price as the same run started in the app; if the workspace balance will not cover it the run is refused with 402 and the body says what it would have cost.
Request body
| Field | Type | Notes |
|---|
planrequired | string | The plan NAME, as shown in the app and returned by GET /plans — not an id, so a pipeline does not hard-code one. Matched exactly, within your workspace. |
browser | string | Defaults to chromium-desktop. |
202 — Accepted and dispatched. Poll GET /runs/{runId} for the result.
| Field | Type | Notes |
|---|
runIdrequired | string | |
statusrequired | "running" | "completed" | "failed" | "cancelled" | |
plan | object | null | The named plan this run executed, when one was named. Null for a run of every active test, or when the plan has since been deleted. |
id | string | |
name | string | |
startedAt | string (date-time) | |
finishedAt | string (date-time) | null | |
totalsrequired | object | |
totalrequired | integer | |
passedrequired | integer | |
failedrequired | integer | |
skippedrequired | integer | |
tests | object[] | |
namerequired | string | The test case title. |
specFile | string | The spec the case belongs to. |
statusrequired | "passed" | "failed" | "skipped" | |
durationMs | integer | How long the case took, in milliseconds. |
error | string | Present only on a failure. |
202400401402403409
GET/api/public/v1/runs/{runId}read
Read a run
What CI polls. While status is running the totals are what has been recorded so far. running is not a failure — fail your build on failed > 0 once status is completed, never on the status alone.
Path parameters
| Field | Type | Notes |
|---|
runIdrequired | string | From the response to POST /runs. |
200 — The run.
| Field | Type | Notes |
|---|
runIdrequired | string | |
statusrequired | "running" | "completed" | "failed" | "cancelled" | |
plan | object | null | The named plan this run executed, when one was named. Null for a run of every active test, or when the plan has since been deleted. |
id | string | |
name | string | |
startedAt | string (date-time) | |
finishedAt | string (date-time) | null | |
totalsrequired | object | |
totalrequired | integer | |
passedrequired | integer | |
failedrequired | integer | |
skippedrequired | integer | |
tests | object[] | |
namerequired | string | The test case title. |
specFile | string | The spec the case belongs to. |
statusrequired | "passed" | "failed" | "skipped" | |
durationMs | integer | How long the case took, in milliseconds. |
error | string | Present only on a failure. |
200401403404
GET/api/public/v1/runs/{runId}/reportread
Read the signed test report for a run
The STR, for a build artifact. Returns the latest revision. 404 when no report has been created for this run — a report is a document somebody produces, and this endpoint will not fabricate one on a GET.
Path parameters
| Field | Type | Notes |
|---|
runIdrequired | string | From the response to POST /runs. |
200 — The report.
| Field | Type | Notes |
|---|
runIdrequired | string | |
titlerequired | string | |
revisionrequired | integer | |
createdAt | string (date-time) | |
signedAt | string (date-time) | null | |
signedName | string | null | |
snapshotrequired | object | The report body as stored. |
200401403404
GET/api/public/v1/plansread
List the plans a run can be started from
So a pipeline can name a suite without hard-coding an id. automatedTests is how many tests a run of this plan would actually dispatch — a plan whose items are all manual reports 0, and starting it would be refused with 409.
200 — The workspace's plans.
| Field | Type | Notes |
|---|
plansrequired | object[] | |
idrequired | string | |
namerequired | string | |
statusrequired | "draft" | "active" | "archived" | |
automatedTestsrequired | integer | |
200401403