Test Runs

A test run groups test results for a specific execution session (e.g., a CI build, a sprint, or a manual regression pass).

Endpoints

Method	Path	Scope	Description
GET	/api/v1/runs	read	List test runs
POST	/api/v1/runs	write	Create a test run
GET	/api/v1/runs/{id}	read	Get a test run
PATCH	/api/v1/runs/{id}	write	Update a test run

List test runs

GET /api/v1/runs?project_id=clxyz123&status=COMPLETED
Authorization: Bearer qh_...

Query parameters

Parameter	Type	Description
project_id	string	Filter by project
status	string	PENDING, IN_PROGRESS, COMPLETED, or SYNCED

Create a test run

POST /api/v1/runs
Authorization: Bearer qh_...
Content-Type: application/json

{
  "name": "Sprint 24 regression — staging",
  "project_id": "clxyz123",
  "environment": "staging",
  "test_case_ids": ["clcase001", "clcase002", "TC-003"]
}

Fields

Field	Type	Required	Description
name	string	Yes	Display name for the run
project_id	string	Yes	Project to associate with
environment	string	No	Environment label
test_case_ids	string[]	No	Pre-populate with specific test cases. Accepts cuid or code.

Update a test run

PATCH /api/v1/runs/clrun001
Authorization: Bearer qh_...
Content-Type: application/json

{
  "status": "COMPLETED"
}

Updatable fields: name, environment, status

Run object schema

{
  "id": "string (cuid)",
  "name": "string",
  "project_id": "string",
  "environment": "string | null",
  "status": "PENDING | IN_PROGRESS | COMPLETED | SYNCED",
  "created_at": "ISO 8601 datetime",
  "updated_at": "ISO 8601 datetime"
}

CI/CD shortcut

For ingesting CI results, use the /api/v1/ingest endpoint instead — it creates the run and populates all results in a single request.