API ReferenceTest Runs

Test Runs API

Create and manage test runs. List runs with status summaries, create new runs from test case selections, and close completed runs.

Base URL:https://api.testably.app/v1

GET/v1/projects/:pid/runs

List all test runs in a project. Returns runs sorted by creation date (newest first), including status summary and assignee information.

Response

{
  "data": [
    {
      "id": "run_501",
      "name": "Sprint 12 Regression",
      "status": "active",
      "total": 45,
      "passed": 32,
      "failed": 5,
      "blocked": 2,
      "retest": 1,
      "not_tested": 5,
      "milestone_id": "ms_v2",
      "created_by": "user_abc",
      "created_at": "2026-03-25T09:00:00Z",
      "updated_at": "2026-03-28T16:45:00Z"
    }
  ],
  "meta": {
    "total": 38,
    "page": 1,
    "per_page": 20
  }
}

GET/v1/projects/:pid/runs/:id

Retrieve a single test run by its ID, including all individual test results with their current status, notes, and elapsed time.

Response

{
  "data": {
    "id": "run_501",
    "name": "Sprint 12 Regression",
    "status": "active",
    "total": 45,
    "passed": 32,
    "failed": 5,
    "blocked": 2,
    "retest": 1,
    "not_tested": 5,
    "milestone_id": "ms_v2",
    "created_by": "user_abc",
    "created_at": "2026-03-25T09:00:00Z",
    "updated_at": "2026-03-28T16:45:00Z",
    "results": [
      {
        "id": "res_001",
        "test_case_id": "tc_001",
        "test_case_title": "Login with valid credentials",
        "status": "passed",
        "note": "Verified on Chrome 120",
        "elapsed": 45,
        "tested_by": "user_xyz",
        "tested_at": "2026-03-26T10:15:00Z"
      },
      {
        "id": "res_002",
        "test_case_id": "tc_002",
        "test_case_title": "Login with invalid password",
        "status": "failed",
        "note": "Error message not displayed correctly",
        "elapsed": 30,
        "tested_by": "user_xyz",
        "tested_at": "2026-03-26T10:20:00Z"
      }
    ]
  }
}

POST/v1/projects/:pid/runsComing Soon

Create a new test run by selecting test cases to include. Optionally link the run to a milestone for release tracking.

Parameters

Name	Type	Required	Description
`name`	string	Required	Name for the test run
`test_case_ids`	string[]	Required	Array of test case IDs to include
`milestone_id`	string	Optional	Link to a milestone (optional)

Request Body

{
  "name": "Sprint 13 Smoke Tests",
  "test_case_ids": ["tc_001", "tc_002", "tc_005", "tc_010"],
  "milestone_id": "ms_v2"
}

Response

{
  "data": {
    "id": "run_502",
    "name": "Sprint 13 Smoke Tests",
    "status": "active",
    "total": 4,
    "passed": 0,
    "failed": 0,
    "blocked": 0,
    "retest": 0,
    "not_tested": 4,
    "milestone_id": "ms_v2",
    "created_by": "user_abc",
    "created_at": "2026-03-29T10:00:00Z",
    "updated_at": "2026-03-29T10:00:00Z"
  }
}

PATCH/v1/projects/:pid/runs/:idComing Soon

Update an existing test run. You can rename the run or change the linked milestone.

Parameters

Name	Type	Required	Description
`name`	string	Optional	Updated run name
`milestone_id`	string	Optional	Updated milestone link (set to null to unlink)

Request Body

{
  "name": "Sprint 13 Smoke Tests (Final)"
}

Response

{
  "data": {
    "id": "run_502",
    "name": "Sprint 13 Smoke Tests (Final)",
    "status": "active",
    "updated_at": "2026-03-29T11:00:00Z"
  }
}

POST/v1/projects/:pid/runs/:id/closeComing Soon

Close a test run. Once closed, no further result updates can be made. The run becomes read-only and its pass rate is finalized.

Response

{
  "data": {
    "id": "run_502",
    "name": "Sprint 13 Smoke Tests (Final)",
    "status": "closed",
    "total": 4,
    "passed": 3,
    "failed": 1,
    "blocked": 0,
    "retest": 0,
    "not_tested": 0,
    "pass_rate": 75.0,
    "closed_at": "2026-03-29T15:00:00Z",
    "updated_at": "2026-03-29T15:00:00Z"
  }
}

Test Cases API Test Results API