Test runs

Test runs are an important component for tracking and managing the testing process. Our REST API provides comprehensive endpoints for handling test runs, enabling you to automate and streamline your testing workflow. With these endpoints, in a project, you can access list of test runs, create new test runs, and add test results to test runs.

Note: For a comprehensive list of default Enum values (such as Priority, State, and Type of Test Case), refer to the System-defined Enum values page.

Get test runs list

GET /api/v2/projects/{project_id}/test-runs

Invoking this API will fetch the list of test runs in a project associated with your username and access key. You will need the id of the project to access its list of test runs.

When requesting a list of test runs using the REST API, you can apply filters to get only the ones you want. Attributes-based filtering allows for selecting test cases by matching one or more attribute values passed as query parameters. The following table lists the available attributes.

When you provide multiple values for the same query parameter, any one value must match the specified attributes. This means that an OR operator is applied within the query parameter. On the other hand, if you include multiple attribute values across different parameters, an AND operator is used across these different parameters. This requires all conditions to be met for a match.

Request Parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
https://test-management.browserstack.com/api/v2/projects/PR-1575/test-runs?run_state=rejected,closed&created_before=2024-11-01&closed_after=2024-11-15&test_plan_id=TP-1&assignee=abc@email.com

Response Attributes 200 OK json

Response

{
  "success": true,
  "test_runs": [
    {
      "active_state": "active",
      "run_state": "done",
      "assignee": "john@email.com",
      "created_at": "2023-11-28T13:33:26.000Z",
      "identifier": "TR-78282",
      "name": "sample build #2",
      "project_id": "PR-1",
      "test_cases_count": 5,
      "configurations": [101, 102, 103],
      "include_closed": true
    }
  ]
}

Create a test run

POST /api/v2/projects/{project_id}/test-runs

Invoking this API will create test runs programmatically, providing flexibility and automation in managing your test cycles. To create a test run, you will need the id of the project in which the test run should be created. If you need to link this test run to a test plan, you will require the id of that test plan.

You can apply filters to get only the test cases you want. Attributes-based filtering allows for selecting test cases by matching one or more attribute values passed as query parameters. When you provide multiple values for the same query parameter, any one value must match the specified attributes. This means that an OR operator applies within the query parameter. On the other hand, if you include multiple attribute values across different parameters, an AND operator is used across these different parameters. This requires all conditions to be met for a match.

By default, the filter_test_cases filters are applied globally across the entire project. To restrict filtering to only the test cases within specified folders, set filter_scope to "within_folders".

Request Parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X POST https://test-management.browserstack.com/api/v2/projects/PR-1/test-runs

Request Body

Request Body

{
  "test_run": {
    "name": "Test Run-29/11/2023",
    "description": "check the performance of the test run",
    "run_state": "new_run",
    "assignee": "john@email.com",
    "test_case_assignee": "john@email.com",
    "tags": [
      "Regression"
    ],
    "issues": ["TASK-309"],
    "issue_tracker": {
      "name": "jira",
      "host": "https://demo.atlassian.net"
    },
    "configurations": [101, 102, 103],
    "test_plan_id" : "TP-20",
    "sub_test_plan_id": "STP-5",
    "test_cases": ["TC-1", "TC-3"],
    "folder_ids": [34, 54, 64],
    "include_all": false,
    "filter_test_cases": {
      "status": ["active", "draft"],
      "priority": ["medium","low" ],
      "case_type": ["regression", "smoke"],
      "owner": ["randomUser@email.com", "uniqueUser@email.com"],
      "tags": ["test", "regression"],
      "custom_fields": {
        "my_custom_field": ["sample_value_1", "sample_value_2"],
        "test": ["a1", "a2"],
        "estimate": [10, 20]
      }
    }
  }
}

Note:

• filter_scope only takes effect when both folder_ids and filter_test_cases are present in the request. If either is absent, filter_scope has no effect.
• When include_all: true is set, it takes precedence over filter_scope and all test cases from the project are included.

Note: test_plan_id and sub_test_plan_id are mutually exclusive. Providing both in the same request will return an error. Additionally, passing a parent Test Plan identifier (e.g., TP-20) in the sub_test_plan_id field will also return an error.

Response Attributes 200 OK json

Response

{
  "success": true,
  "testrun": {
      "active_state": "active",
      "run_state": "new_run",
      "created_at": "2023-11-29T06:26:22.215Z",
      "description": "check the performance of the test run",
      "identifier": "TR-78527",
      "name": "Test Run-29/11/2023",
      "assignee": "john@email.com",
      "project_id": "PR-1",
      "tags": ["performance"],
      "test_cases_count": 1,
      "updated_at": "2023-11-29T06:26:22.215Z",
      }
  }

Clone a test run

POST /api/v2/projects/{project_id}/test-runs/{test_run_id}/clone

This endpoint creates a new test run by cloning an existing one. It accepts the same options as the UI’s Clone dialog. Use it to start a regression cycle from an earlier run without re-selecting test cases manually.

The response returns as soon as BrowserStack creates the cloned run. It includes the run’s metadata, such as its name, run state, tags, configurations, and any issues or attachments carried over from the source.

The per-test-case mappings come later. BrowserStack populates them in the background, shortly after it returns the response. If you call GET /test-runs/{test_run_id}/test-cases immediately after cloning, the response may list zero test cases until that background work finishes. The wait is usually under a second.

Note:

• You cannot clone an automated source run.
• The cloned run does not carry over the source run’s test plan associations.
• The cloned run inherits the dynamic-run flag from the source. BrowserStack does not re-evaluate the underlying filter at clone time.

Request Parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X POST https://test-management.browserstack.com/api/v2/projects/PR-1/test-runs/TR-45/clone

Request Body

All fields are optional, so an empty body {} clones the run with the Clone dialog defaults. Those defaults carry over all test cases, tags, and assignees. They also name the new run after the source, with ` - Copy` appended.

Request Body

{
  "test_case_selection": "by_results",
  "statuses": ["failed", "blocked"],
  "copy_tc_assignee": true,
  "copy_tags": true,
  "copy_issues": false,
  "name": "Sprint 24 - Regression Re-Run"
}

Note: Send statuses only when test_case_selection is by_results. The API selects test cases whose latest result on the source run matches one of the listed statuses.

Response Attributes 200 OK json

Response

{
  "success": true,
  "test_run": {
    "identifier": "TR-99",
    "name": "Sprint 24 - Regression Re-Run",
    "run_state": "new_run",
    "active_state": "active",
    "description": "",
    "assignee": "john@email.com",
    "tags": ["Regression"],
    "configurations": [],
    "test_case_summary": {
      "untested": 12,
      "passed": 0,
      "retest": 0,
      "failed": 0,
      "blocked": 0,
      "skipped": 0,
      "in_progress": 0
    },
    "links": {
      "self": "/api/v2/projects/PR-1/test-runs/TR-99",
      "test_cases": "/api/v2/projects/PR-1/test-runs/TR-99/test-cases"
    }
  }
}

The test_case_summary counts show how many test cases will be populated under the new run, all reset to untested. The source run’s pass and fail results do not carry over to the cloned run.

Error responses

Get test run details

GET /api/v2/projects/{project_id}/test-runs/{test_run_id}

Invoking this API will fetch the details of test cases linked to a test run. You will need the id of the project and id of the test run to access the details of test cases. The sample request has PR-1 and TR-78527 as placeholders representing project ID and test run ID, respectively.

Request Parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
https://test-management.browserstack.com/api/v2/projects/PR-1/test-runs/TR-78527

Response Attributes 200 OK json

Response

{
   "success":true,
   "test_run":{
      "active_state":"active",
      "run_state":"new_run",
      "created_at":"2023-11-29T06:26:22.215Z",
      "description":"",
      "identifier":"TR-78527",
      "name":"Test Run-29/11/2023",
      "assignee":"john@email.com",
      "project_id":"PR-1",
      "configurations":[101, 102, 103],
      "test_cases":[
         {
            "assignee":"john@email.com",
            "case_type":"other",
            "priority":"High",
            "status":"Active",
            "description":"",
            "identifier":"TC-1",
            "name":"Assign tags to user and then re-open the modal",
            "latest_status":"Passed",
            "configuration_id":101,
            "latest_result_id":108767
         }
      ],
      "links":{
         "test_cases":"/api/v2/projects/PR-1/test-runs/TR-78527/test-cases"
      },
      "tags":["ttt"],
      "test_cases_count":3,
      "updated_at":"2023-11-29T06:26:22.215Z",
      "passed_count":1,
      "failed_count":1,
      "customstatus_count":1,
      "overall_progress":{
         "untested":0,
         "passed":2,
         "retest":0,
         "failed":0,
         "blocked":0,
         "skipped":0,
         "in_progress":0
      }
   }
}

Get test run details minified

GET /api/v2/projects/PR-1/test-runs/TR-5/test-cases?minify=true

This endpoint returns minified details for a specific test run. The response contains only essential fields for the test run, making it suitable for scenarios where you need a lightweight payload (for example, quick status checks or summary views).

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
https://test-management.browserstack.com/api/v2/projects/PR-75/test-runs/TR-152?minify=true

Response attributes 200 OK json

Response

{
   "success":true,
   "test_run":{
      "active_state":"active",
      "run_state":"new_run",
      "created_at":"2025-08-20T10:27:03.000Z",
      "updated_at":"2025-08-20T10:27:03.000Z",
      "description":"",
      "identifier":"TR-152",
      "name":"Test Run-20/08/2025",
      "assignee":"user@email.com",
      "project_id":"PR-75",
      "overall_progress":{
         
      },
      "tags":[
         
      ],
      "configurations":[
         
      ],
      "links":{
         "self":"/api/v1/projects/10075/test-runs/TR-152",
         "test_cases":"/api/v2/projects/PR-75/test-runs/TR-152/test-cases"
      }
   }
}

Get test cases of a test run

GET /api/v2/projects/{project_id}/test-runs/{test_run_id}/test-cases

Invoking this API will fetch the details of all the test cases linked to a test run. You will need the id of the project and id of the test run to access the details of test cases. Using this endpoint, you can retrieve the first thirty test cases. This list is paginated; for more information, refer Pagination.

Each test case includes a source_project_id. For a shared test case, this is the project the test case was shared from. For a test case that is not shared, source_project_id matches project_id.

• The sample request has PR-1 and TR-78527 as placeholders representing project ID and test run ID, respectively.

• Use fetch_steps query parameter in the API to get test case steps. When the fetch_steps query parameter is used, the API returns the first 30 test case steps. Pagination is not supported for requests that include this parameter. The steps array is populated with step objects, each containing its own id and order.
  

  Example: https://test-management.browserstack.com/api/v2/projects/PR-1/test-runs/TR-78527/test-cases?fetch_steps=true

Request Parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
https://test-management.browserstack.com/api/v2/projects/PR-1/test-runs/TR-78527/test-cases?p=1

Response Attributes 200 OK json

Response

{
   "success":true,
   "info":{
      "page":1,
      "page_size":30,
      "count":94,
      "prev":null,
      "next":2
   },
   "test_cases":[
      {
         "case_type":"Destructive",
         "priority":"High",
         "status":"Active",
         "description":"Subject the password reset system to sustained high load over an extended period and monitor for any degradation in performance or stability issues. This test is important to ensure the system can maintain performance during extended periods of high usage.",
         "identifier":"TC-972133",
         "name":"Verify system stability during prolonged high load",
         "project_id":"PR-1",
         "source_project_id":"PR-9",
         "steps":[
            {
               "id":34001057,
               "order":1,
               "description":"Initiate a high-load scenario using the load testing tool, simulating a consistently high number of password reset requests over an extended period (e.g., 24 hours).",
               "result":"The system should accept and process reset requests consistently throughout the test period without significant degradation in performance."
            },
            {
               "id":34001061,
               "order":5,
               "description":"Regularly check the email sending process, measuring the time to generate, queue, and send recovery emails throughout the test period.",
               "result":"Email processing should keep pace with incoming requests, maintaining consistent performance (e.g., < 1 minute from request to email sent) throughout the test."
            }
         ],
         "latest_status":"untested",
         "latest_result_id":null,
         "assignee":null,
         "folder_path":[
            10456816
         ],
        "configuration_id": 44028850,
            "dataset": [
              {
                "variable": "col1",
                "row": "1"
              },
              {
                "variable": "col1",
                "row": "2"
              }
            ], 
        "created_at": "2025-09-03T11:20:52.000Z",
        "last_updated_at": "2025-09-03T11:29:34.000Z",
        "created_by": "user1@email.com",
        "last_updated_by": "user2@email.com",
      }
   ]
}

Get test cases of a test run minified

GET /api/v2/projects/PR-75/test-runs/TR-152?minify=true

Invoking this API fetches only the essential fields of all the test cases linked to a test run, such as test case ID, description, title and the latest status. You will need the id of the project and id of the test run to access the details of test cases.

Request parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
https://test-management.browserstack.com/api/v2/projects/PR-1/test-runs/TR-5/test-cases?minify=true

Response attributes 200 OK json

Response

{
   "success":true,
   "info":{
      "page":1,
      "page_size":30,
      "count":1,
      "prev":null,
      "next":null
   },
   "test_cases":[
      {
         "description":"WINDOWS,Unknown - Edge,110",
         "identifier":"TC-98",
         "name":"Check whether the application has secure protocols like HTTPS.",
         "latest_status":"untested"
      }
   ]
}

Update a test run (PATCH)

PATCH /api/v2/projects/{project_id}/test-runs/{test_run_id}/update

Use this API to update an existing test run. Unlike the POST method which requires all fields to be present, this PATCH endpoint only updates the fields that are provided in the request body. This allows for partial updates to a test run without needing to resend all the data. To update a test run, you will need both the id of the project (eg: PR-2134) and the id of the test run (eg: TR-2343) within that project.

Note:

• To clear an array field (like tags or issues), you must send an empty array ([]) in the request body.
• Omitting a field from the request body will leave that field unchanged.
• The PATCH API endpoint is used to update specific fields. Include only the fields you wish to modify in the request body.

Request Parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X PATCH https://test-management.browserstack.com/api/v2/projects/{project_id}/test-runs/{test_run_id}/update

Request Body

Request Body

{
  "test_run": {
    "name": "Test Run-29/11/2023",
    "run_state": "new_run",
    "tags": ["ttt"],
    "sub_test_plan_id": "STP-5",
    "configurations": [101, 102, 103],
    "configuration_map": [
      {
        "test_case_id": ["TC-11", "TC-15"],
        "configuration_ids": [231, 235]
      },
      {
        "test_case_id": "TC-1103745",
        "configuration_ids": [240]
      }
    ],
    "folder_ids": [34, 54, 64],
    "include_all": false,
    "filter_test_cases": {
      "status": ["active", "draft"],
      "priority": ["medium", "low"],
      "case_type": ["regression", "smoke"],
      "owner": ["randomUser@email.com", "uniqueUser@email.com"],
      "tags": ["test", "regression"]
    }
  }
}

Response Attributes 200 OK json

Response

{
  "success": true,
  "testrun": {
    "name": "Test Run-29/11/2023",
    "run_state": "new",
    "tags": ["ttt"]
  }
}

Update a test run (POST)

POST /api/v2/projects/{project_id}/test-runs/{test_run_id}/update

Invoking this API allows you to update test runs in a given project. When you update the test run, the new test cases in the update test run request will replace all the existing test cases. To update a test run, you will need both the id of the project (eg: PR-2134) and the id of the test run (eg: TR-2343) within that project.

Note: The POST API endpoint requires a complete request body. All listed parameters must be included in your Request Body, even if they have null or default values.

Request Parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X POST https://test-management.browserstack.com/api/v2/projects/{project_id}/test-runs/{test_run_id}/update

Request Body

Request Body

{
  "test_run": {
    "name": "Test Run-29/11/2023",
    "description": "gas",
    "run_state": "new_run",
    "assignee": "john@email.com",
    "test_case_assignee": "john@email.com"
    "tags": [
      "ttt"
    ],
    "issues": [
      "XYZ-1"
    ],
    "issue_tracker": {
      "name": "jira",
      "host": "https://demo.atlassian.net"
    },
    "test_plan_id" : "TP-20",
    "sub_test_plan_id": "STP-5",
    "configurations": [101, 102],
    "test_cases": ["TC-1", "TC-3"],
    "folder_ids": [34,54,64],
    "include_all": false,
    "filter_test_cases": {
      "status": ["active", "draft"],
      "priority": ["medium","low" ],
      "case_type": ["regression", "smoke"],
      "owner": ["randomUser@email.com", "uniqueUser@email.com"],
      "tags": ["test", "regression"]
  }
}

Response Attributes 200 OK json

Response

{
  "success": true,
  "testrun": {
    "active_state": "active",
    "run_state": "new_run",
    "created_at": "2023-11-29T06:26:22.215Z",
    "description": "gas",
    "identifier": "TR-78527",
    "name": "Test Run-29/11/2023",
    "assignee": "john@email.com",
    "project_id": "PR-1",
    "test_plan": {
      "identifier": "TP-20",
      "name": "Test plan6"
    },
    "tags": [
      "ttt"
    ],
    "issues": [
      "XYZ-1"
    ],
    "test_cases_count": 2,
    "updated_at": "2023-11-29T06:26:22.215Z"
  }
}

Update assignee of test cases within a test run

POST /api/v2/projects/PR-5512/test-runs/TR-126509/assign

Invoking this API will update assignees of test cases within a test run. To do so, you will need the id of the project, the id of the test run (eg: TR-2343), the id of test cases, and the email of assignees.

Request Parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X POST https://test-management.browserstack.com/api/v2/projects/PR-5512/test-runs/TR-126509/assign

Request Body

Request Body

{
  "assign_to": [
    {
      "test_case_id": "TC-337204",
      "configuration_id": 2,
      "assignee": "john@email.com"
    },
    {
      "test_case_id": "TC-337205",
      "configuration_id": 1,
      "assignee": "randomUser@email.com"
    },
    {
      "test_case_id": "TC-337203",
      "configuration_id": 1,
      "assignee": "uniqueUser@email.com"
    }
  ]
}

Response Attributes 200 OK json

Response

{
    "success": true
}

Add or remove test cases in a test run

PATCH /api/v2/projects/{project_id}/test-runs/{test_run_id}/update-test-cases

Use this API to change the set of test cases included in a test run. You can add test cases, remove test cases, or do both in one request. Existing execution results stay intact, which is the main difference between this API and an update that overwrites the whole run.

To call this API, you need the id of the project and the id of the test run. A project ID such as PR-2134 and a test run ID such as TR-2343 must both belong to the same project. Cross-project links fail.

Operations go inside a test_run object. Use add_test_cases to append test cases and remove_test_cases to detach them. Each entry pairs a test_case_ids array with the configuration_ids that those test cases should apply under. When an entry has no configuration_ids, the API targets only the test cases that carry no configuration.

Set preserve_existing_results to true to keep the execution results of the test cases that remain in the run after your changes. The test run is not reset. Removing a test case detaches only that test case and its results. Other test cases keep their results.

Note:

• Send at least one test case in add_test_cases or remove_test_cases. An empty request returns operation_required.
• A test_case_ids array cannot list the same ID twice. A duplicate returns duplicate_test_case_id.
• Every test case ID and configuration ID must be valid and accessible to you. The API rejects an invalid ID with a 400 before it changes anything.
• Adding a test case that is already in the run has no effect. Removing a test case that is not in the run has no effect either. The API skips these pairs instead of failing the request.
• You need permission to modify the run and to access every referenced test case. The API checks your access before it changes the run.

Request Parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X PATCH https://test-management.browserstack.com/api/v2/projects/{project_id}/test-runs/{test_run_id}/update-test-cases

Request Body

Request Body

{
  "test_run": {
    "add_test_cases": [
      {
        "test_case_ids": ["TC-101", "TC-102"],
        "configuration_ids": [1, 2]
      },
      {
        "test_case_ids": ["TC-103"]
      }
    ],
    "remove_test_cases": [
      {
        "test_case_ids": ["TC-104", "TC-105"],
        "configuration_ids": [1, 2]
      }
    ],
    "preserve_existing_results": true
  }
}

Response Attributes 202 Accepted json

The API validates the request, then runs the add and remove operations asynchronously. A 202 Accepted response confirms that the request passed validation and was queued. It does not confirm that every pair was applied. To see what changed, track the asynchronous result.

Response

{
  "success": true,
  "async": true,
  "unique_id": "c6d0b247-3f5e-447a-91f8-a8f12848b8b9"
}

Track the asynchronous result

The 202 response returns a unique_id. When the work finishes, the result is delivered asynchronously. It carries the same unique_id, so you can match it to the request you sent. The result reports the operation that ran, either add or remove, and an affected_mapping_count.

Each test case under each configuration counts as one pair. The affected_mapping_count parameter is the number of these pairs that changed. Skipped pairs do not count. So you can compare affected_mapping_count against the number of pairs you sent. When the count is lower than expected, the missing pairs were already in the target state. That is normal.

Error responses

When validation fails, the API returns a synchronous 400. The body names the failure in error and describes it in message.

Response

{
  "success": false,
  "error": "invalid_test_case_id",
  "message": "One or more test case IDs are invalid."
}

Close a test run

POST /api/v2/projects/{project_id}/test-runs/{test_run_id}/close

Invoking this API will close test runs in a given project. To close a test run, you will need the id of test run and id of the project in which the test run exists.

Request Parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X POST https://test-management.browserstack.com/api/v2/projects/PR-13/test-runs/TR-128/close

Response Attributes 200 OK json

Response

{
  "success": true,
  "testrun": {
    "active_state": "closed",
    "run_state": "closed",
    "created_at": "2023-12-21T09:03:10.000Z",
    "updated_at": "2023-12-28T11:45:22.000Z",
    "description": "Login functionality under user load",
    "identifier": "TR-128",
    "name": "Test Run-05/12/2023",
    "assignee": "john@email.com",
    "project_id": "PR-13",
    "tags": ["test", "regression"],
    "configurations": [101, 102, 103],
    "filter_test_cases": {
      "is_dynamic": false
    },
    "links": {
      "self": "/api/v2/projects/PR-13/test-runs/TR-128",
      "test_cases": "/api/v2/projects/PR-13/test-runs/TR-128/test-cases"
    },
    "urls": {
      "self": "https://test-management.browserstack.com/projects/13/test-runs/TR-128"
    }
  }
}

Delete a test run

POST /api/v2/projects/{project_id}/test-runs/{test_run_id}/delete

Invoking this API will delete a test run. You will need the id of the project and id of the test run to delete a test run.

Request Parameters

Request

curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
-X POST https://test-management.browserstack.com/api/v2/projects/PR-1/test-runs/TR-1234/delete

Response Attributes 200 OK json

Response

{
    "success": true,
    "message": "Test Run TR-1234 has been deleted successfully"
}