DOCS
Reference

API: Runs

Runs: Run a test, Run a project, List runs, Get a run, Stop a run, Download a run file.

Run a test

POST/api/v1/tests/{testId}/run

Start a run of one test. Runs take minutes: poll get_run until final is true. App tests run the newest build of their app unless buildId names another (see list_builds). REST: send an Idempotency-Key header so a retried request does not start a second run.

MCP tool: run_test. Works with any key, including one that can only run tests and read results. Accepts an Idempotency-Key header.

Path
testIdstringrequired
Test id (t_…)
Body (JSON)
modeauto | cold | warm
auto (default) replays the learned path when it is fresh, else explores; cold always explores; warm only replays.
buildIdstring
Apps: run this build (ab_…)

Returns 201 { runId, mode, overage, link }

Request
curl -X POST https://app.testsy.dev/api/v1/tests/t_mvg0/run \
  -H "Authorization: Bearer $QA_AI_API_KEY" \
  -H "Idempotency-Key: deploy-4812"

Run a project

POST/api/v1/projects/{projectId}/run

Start a run of every test in a project (a suite). buildIds: builds to use; each app test runs the one of its own app. Tests that could not start are listed in skipped with the reason. REST: send an Idempotency-Key header to make a retry safe.

MCP tool: run_project. Works with any key, including one that can only run tests and read results. Accepts an Idempotency-Key header.

Path
projectIdstringrequired
Project id (p_…)
Body (JSON)
modeauto | cold | warm
auto (default) replays the learned path when it is fresh, else explores; cold always explores; warm only replays.
buildIdsstring[]
Build ids (ab_…), optional
buildIdstring
One build id (ab_…), optional

Returns 201 { started: [{ testId, runId, mode, buildId, link }], skipped: [{ testId, reason }] }. Nothing started: 402 not_started (or 400 empty) with the same lists

Request
curl -X POST https://app.testsy.dev/api/v1/projects/p_8f2k/run \
  -H "Authorization: Bearer $QA_AI_API_KEY" \
  -H "Idempotency-Key: deploy-4812"

List runs

GET/api/v1/runs

Recent runs, newest first, optionally for one test or project or with one status; or the runs with the given ids.

MCP tool: list_runs. Works with any key.

Query
idsstring
Comma-separated run ids (j_…, up to 50): returns their full views
testIdstring
Only this test
projectIdstring
Only this project
statusqueued | running | passed | failed | blocked | inconclusive | error | cancelled
Only this status
limitnumber
At most this many (default 50, up to 200)

Returns { runs: [{ id, testId, testTitle, status, mode, source, platform, createdAt, finishedAt, durationMs, … }] }; with ids, each run as in Get a run

Request
curl https://app.testsy.dev/api/v1/runs?ids=… \
  -H "Authorization: Bearer $QA_AI_API_KEY"

Get a run

GET/api/v1/runs/{runId}

A run: its status, and once final the verdict, the headline, each check's result with the reason, the values read, and links to the video, screenshots and the result page.

MCP tool: get_run. Works with any key.

Path
runIdstringrequired
Run id (j_…)

Returns { run: { id, testId, testTitle, url, mode, status, final, createdAt, startedAt, finishedAt, durationMs, error, verdict, headline, requirements, captures, video, screenshots, build, link } }

Request
curl https://app.testsy.dev/api/v1/runs/j_mvg1 \
  -H "Authorization: Bearer $QA_AI_API_KEY"

Stop a run

POST/api/v1/runs/{runId}/stop

Stop a queued or running run. A run you stop is not counted.

MCP tool: stop_run. Works with any key, including one that can only run tests and read results.

Path
runIdstringrequired
Run id (j_…)

Returns { status }

Request
curl -X POST https://app.testsy.dev/api/v1/runs/j_mvg1/stop \
  -H "Authorization: Bearer $QA_AI_API_KEY"

Download a run file

GET/api/v1/runs/{runId}/files/{file}

Download a run's video or screenshot (the links in get_run). Supports Range requests.

REST only. Works with any key.

Path
runIdstringrequired
Run id (j_…)
filestringrequired
File path from get_run

Returns The file (video/mp4, image/png, …); 206 for a Range request

Request
curl https://app.testsy.dev/api/v1/runs/j_mvg1/files/review.mp4 \
  -H "Authorization: Bearer $QA_AI_API_KEY"