Free tools Windows power users keep installed
One-click scans. No signup required.
Use BrowserStack’s Test Management API to create, find, inspect, update, close, or delete test runs associated with a project. The routes in this guide manage Test Management records and results; they do not launch tests on BrowserStack browsers or devices. The examples use HTTP Basic authentication with your BrowserStack username and access key, and the API returns JSON by default.
What the Test Run API manages
BrowserStack describes its Test Runs API as providing endpoints for handling test runs and streamlining testing workflows. In practical terms, a run is a project-scoped Test Management record that can contain metadata and selected test cases, and whose cases and results can be retrieved separately. Use the API when you need to manage those records programmatically; use BrowserStack’s separate execution and reporting workflows when you need to run tests or ingest automated test reports.
The documented host is https://test-management.browserstack.com. The routes below use the /api/v2/projects/{project_id} prefix. Replace the brace-delimited values with the actual project and test-run identifiers.
Authentication and request basics
BrowserStack’s documented curl examples authenticate with HTTP Basic authentication using the account username and access key. The API follows REST conventions, uses standard HTTP response codes, and returns JSON by default. The documentation referenced here does not establish a complete account-entitlement or permissions matrix, so confirm that the relevant account can access Test Management if a request is rejected.
#1 Best Overall
export BROWSERSTACK_USERNAME="YOUR_USERNAME"
export BROWSERSTACK_ACCESS_KEY="YOUR_ACCESS_KEY"
export PROJECT_ID="PR-1"
curl -u "$BROWSERSTACK_USERNAME:$BROWSERSTACK_ACCESS_KEY"
"https://test-management.browserstack.com/api/v2/projects/$PROJECT_ID/test-runs"Keep credentials in environment variables or a secrets manager rather than committing them to source control or printing them in logs. This request lists runs for the project; it does not create or execute a test.
Find the endpoint for the operation
| Task | Method and path | Important detail |
|---|---|---|
| List project runs | GET /api/v2/projects/{project_id}/test-runs |
Project-scoped; the reference supports filters. |
| Create a run | POST /api/v2/projects/{project_id}/test-runs |
Request body places run attributes under test_run. |
| Get a run | GET /api/v2/projects/{project_id}/test-runs/{test_run_id} |
Requires both project and run IDs. |
| List cases in a run | GET /api/v2/projects/{project_id}/test-runs/{test_run_id}/test-cases |
Paginated; the initial response contains up to 30 cases. |
| Get run results | GET /api/v2/projects/{project_id}/test-runs/{test_run_id}/results |
Paginated results endpoint. |
| Partially update a run | PATCH /api/v2/projects/{project_id}/test-runs/{test_run_id}/update |
Only supplied fields change. |
| Fully update a run | POST /api/v2/projects/{project_id}/test-runs/{test_run_id}/update |
Requires a complete body; supplied test cases replace existing membership. |
| Close a run | POST /api/v2/projects/{project_id}/test-runs/{test_run_id}/close |
Requires project and run IDs. |
| Delete a run | POST /api/v2/projects/{project_id}/test-runs/{test_run_id}/delete |
Destructive; verify the target before sending. |
For the exact parameters and accepted values, consult BrowserStack’s current Test Management API reference. The endpoint map above identifies the documented routes, not every optional query parameter.
Create a test run
Send a POST request to the project’s test-runs route. The documented example nests run attributes inside a test_run JSON object. Depending on the workflow, the reference shows attributes such as name, description, run state, assignees, tags, linked issues, configurations, test-plan ID, test-case identifiers, folder IDs, and include_all. Check the reference for the required fields and valid enum values for your account and use case.
curl -u "$BROWSERSTACK_USERNAME:$BROWSERSTACK_ACCESS_KEY"
-X POST "https://test-management.browserstack.com/api/v2/projects/$PROJECT_ID/test-runs"
-H "Content-Type: application/json"
-d '{"test_run":{"name":"Regression run"}}'This is an illustrative request skeleton showing the documented route and body shape. It is not a guarantee that a name-only body will be accepted in every account configuration. If your run needs a defined set of cases, assignees, configurations, or a test plan, include those values as described by the current API reference.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallOutdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchHow case filters combine
When selecting test cases through filters during run creation, multiple values for a single query parameter match with OR logic, while conditions on different parameters combine with AND logic. By default, filtering applies across the project. Set filter_scope to within_folders to constrain filtering to selected folders. Check the reference for the filter parameter names and accepted values before building a dynamic request.
Read runs, cases, and results
List and inspect runs
Use GET /api/v2/projects/{project_id}/test-runs to list a project’s runs and apply supported filters when needed. To retrieve one record, add its run ID: GET /api/v2/projects/{project_id}/test-runs/{test_run_id}. The documented detail example includes fields such as identifiers, name, run state, creation time, assignee, progress, tags, configurations, and related links.
Retrieve test cases
Call the run’s /test-cases subresource to inspect its associated cases. The initial response contains up to 30 cases, and the endpoint is paginated. The documented fetch_steps=true option includes case steps, but returns up to 30 steps and does not support pagination on that request. A minified option is also documented for core case fields, including the test-case identifier, description, title, and latest status. Because the available pagination parameters are not established here, use the linked API reference to determine how to request later pages.
Retrieve results
Use GET /api/v2/projects/{project_id}/test-runs/{test_run_id}/results for a run’s results. This endpoint is paginated too; account for more than one page when consuming a large result set rather than treating the first response as necessarily complete.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsRank #3
Choose PATCH or POST for an update
Both update methods use the same /update path, but they have materially different effects. Use PATCH for a targeted edit. Use POST only when you intend to submit the complete run representation described by the reference.
| Behavior | PATCH /update |
POST /update |
|---|---|---|
| Update type | Partial: changes supplied fields. | Full: complete request body expected. |
| Omitted fields | Remain unchanged. | Provide the complete body, including required null or default values as applicable. |
| Test-case membership | Only change it if you explicitly include the relevant field as documented. | Supplied test cases replace the run’s existing test cases. |
| Clearing an array | Send an empty array for an array field such as tags or issues. | Follow the full-body requirements and verify every array value before sending. |
Example: change only the run name
curl -u "$BROWSERSTACK_USERNAME:$BROWSERSTACK_ACCESS_KEY"
-X PATCH "https://test-management.browserstack.com/api/v2/projects/$PROJECT_ID/test-runs/$TEST_RUN_ID/update"
-H "Content-Type: application/json"
-d '{"test_run":{"name":"Regression run - nightly"}}'Because PATCH preserves omitted fields, this form is appropriate when the intended change is narrow. To clear a tag array, for example, explicitly send the empty array in the documented request structure; omitting the field is not the same as clearing it.
Before using full update
Build the complete body from the current run state and the values you intend to keep. In particular, inspect the test-case list: the new list supplied to POST replaces existing case membership. Do not reuse a partial PATCH body with POST on the assumption that omitted fields will be preserved.
Other documented run operations
- Add or remove cases: The reference documents operations to add or remove test cases, with one action per request. A separate remove-by-identifier endpoint accepts up to 100 unique identifiers and is synchronous and atomic: if an identifier is invalid or absent from the run, the request is rejected without removing any of them.
- Assign cases: The reference documents an operation to assign test-case assignees.
- Close a run: Send
POSTto the run’s/closeroute. - Clone a run: Case mappings are added in the background, so an immediate case-list request may temporarily return zero cases. Automated source runs cannot be cloned, and cloned runs do not retain test-plan associations.
- Delete a run: The reference documents a
POSTdelete route and a success response. Verify project and run identifiers carefully; no recovery or undo process is established in the documentation summarized here.
Use with automated test results
Managing a test run through the Test Management API is distinct from sending automated execution results. BrowserStack documents importing JUnit-XML or BDD-JSON reports with curl, and integrating Test Reporting & Analytics through BrowserStack SDK. Its documented framework integrations include TestNG, WebdriverIO, Nightwatch, Appium, Cypress, Mocha, pytest, Playwright, Espresso, XCUITest, and Cucumber. Those report-ingestion paths are not the test-run endpoints described above; choose the documented integration for the report format and framework you use.
Python and Node.js request examples
The API reference examples establish the route, Basic authentication pattern, and JSON request shape. These equivalent client examples show how to send a request using credentials from environment variables. As with the curl creation skeleton, confirm required fields and account configuration in the current reference.
Python
import os
import requests
username = os.environ["BROWSERSTACK_USERNAME"]
access_key = os.environ["BROWSERSTACK_ACCESS_KEY"]
project_id = os.environ.get("PROJECT_ID", "PR-1")
url = f"https://test-management.browserstack.com/api/v2/projects/{project_id}/test-runs"
response = requests.post(
url,
auth=(username, access_key),
headers={"Content-Type": "application/json"},
json={"test_run": {"name": "Regression run"}},
timeout=30,
)
print(response.status_code)
print(response.text)
response.raise_for_status()Node.js
const username = process.env.BROWSERSTACK_USERNAME;
const accessKey = process.env.BROWSERSTACK_ACCESS_KEY;
const projectId = process.env.PROJECT_ID || 'PR-1';
if (!username || !accessKey) throw new Error('Set BrowserStack credentials in the environment');
const credentials = Buffer.from(`${username}:${accessKey}`).toString('base64');
const url = `https://test-management.browserstack.com/api/v2/projects/${projectId}/test-runs`;
const response = await fetch(url, {
method: 'POST',
headers: {
'Authorization': `Basic ${credentials}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({ test_run: { name: 'Regression run' } })
});
console.log(response.status, await response.text());
if (!response.ok) throw new Error(`Request failed with HTTP ${response.status}`);These examples print the response body for inspection and fail on an unsuccessful HTTP response. Avoid logging the authorization header or secret values. The minimal creation payload remains illustrative rather than a claim about every account’s required fields.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshooting and operational care
Authentication or access is rejected
Check that the username and access key are both present, that they are being sent as the Basic-auth pair rather than as query parameters, and that no whitespace or quoting error altered them. Confirm account access with the administrator or BrowserStack if credentials appear correct; a full permissions matrix is not established here.
The API cannot find the project or run
Verify that the project ID is in the path and that the run ID belongs to that project. Run-specific routes require both identifiers. Avoid relying only on a display name when constructing these URLs.
Recommended Free Tools
An update changed more than intended
Check which method was sent. PATCH changes supplied fields and preserves omitted ones; POST expects a complete body, and a supplied test-case list replaces current membership. For an array you mean to clear, include an explicit empty array in the appropriate request.
A case list looks incomplete or empty
The case and result endpoints are paginated, and the first case response includes at most 30 cases. Request later pages using the documented pagination parameters. If you just cloned a run, an immediate case request may return zero while mappings are populated in the background.
A request fails for an unknown reason
Inspect the HTTP status and JSON response body, then compare the method, path, content type, request fields, and identifiers with the current BrowserStack API reference. The API uses standard HTTP response codes, but a complete endpoint-by-endpoint error table and all rate limits are not established here; avoid assuming a particular status code maps to one cause.
Or skip the browser setup
BrowserStack’s Test Run API is for managing test records, not generating screenshots. If your workflow also needs a clean screenshot as visual evidence for a test, ScreenshotNeo is a separate website screenshot API and MCP server. One GET request can return an image or PDF; its clean-shot options address cookie banners, popups, and chat widgets.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
For a single capture, use cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options. Cookie banners, popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents use screenshot tools. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000. Sign up for free.
Frequently Asked Questions
Can I use these routes to start a browser or device test?
No. These routes manage Test Management runs and results; they are separate from the APIs and workflows that launch test execution.
Does the API documentation establish rate limits or a full permission matrix?
Not in the documented material summarized here. Check BrowserStack’s current reference or account administrator for those account-specific details.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
