Runs endpoints

API endpoints to trigger, monitor, and stop load tests in BrowserStack Load Testing.

Each run has a unique identifier that you use to query its status and retrieve results.

Trigger a load test run

POST /api/v1/runs

Trigger a saved load test and get back a run ID and status URLs. This is asynchronous. The API returns immediately with a 202 and a run_id, and the test starts provisioning in the background.

Request parameters

Request

curl -u $BROWSERSTACK_USERNAME:$BROWSERSTACK_ACCESS_KEY -X POST \
  https://load-api.browserstack.com/api/v1/runs \
  -H "Content-Type: application/json" \
  -d '{
    "project_name": "my-project",
    "test_name": "checkout-flow",
    "test_version": "1.0"
  }'

Response attributes 202 Accepted JSON

The response includes relative endpoint paths. Prepend https://load-api.browserstack.com to construct the full URLs.

Response

{
  "run_id": "run-abc123",
  "status_url": "/api/v1/runs/run-abc123/status",
  "report_url": "/api/v1/runs/run-abc123/report",
  "stop_url": "/api/v1/runs/run-abc123/stop"
}

Poll run status

GET /api/v1/runs/{run_id}/status

Poll every 5 to 10 seconds. The status updates as the test provisions, runs, and is analyzed.

Request parameters

Request

curl -u $BROWSERSTACK_USERNAME:$BROWSERSTACK_ACCESS_KEY \
  https://load-api.browserstack.com/api/v1/runs/{run_id}/status

Response attributes 200 OK JSON

Response

{
  "run_id": "run-abc123",
  "state": "running",
  "terminal_reason": null,
  "report_ready": false,
  "started_at": "2026-08-28T14:32:10Z",
  "completed_at": null,
  "duration_seconds": 125
}

State values

The state field shows where the run is in its lifecycle:

Terminal reasons

When a run reaches a terminal state, terminal_reason explains how it ended:

Fetch run report

GET /api/v1/runs/{run_id}/report

Fetch the full test report once the run is complete. Reports include KPIs, thresholds, and an SLA verdict. The endpoint returns 202 (Not Yet Ready) while the run is still in progress or computing the report.

Request parameters

Request

curl -u $BROWSERSTACK_USERNAME:$BROWSERSTACK_ACCESS_KEY \
  https://load-api.browserstack.com/api/v1/runs/{run_id}/report

Response attributes 200 OK JSON

Response

{
  "run_id": "run-abc123",
  "summary": {
    "duration": 300,
    "users": 100,
    "requests": 50000,
    "errors": 234,
    "error_rate": 0.0047,
    "p95_latency_ms": 2145,
    "p99_latency_ms": 4321
  },
  "thresholds": [
    {
      "name": "error_rate",
      "expected": "< 0.01",
      "actual": 0.0047,
      "passed": true
    },
    {
      "name": "p95_latency",
      "expected": "< 2000",
      "actual": 1850,
      "passed": true
    }
  ],
  "sla_verdict": "passed",
  "report_url": "https://app.browserstack.com/load-testing/reports/run-abc123"
}

SLA verdict values

The sla_verdict field in the report indicates the overall test outcome:

Stop a run

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

Stop a running test. This is idempotent. Calling it multiple times with the same run ID has the same effect as calling it once.

Request parameters

Request

curl -u $BROWSERSTACK_USERNAME:$BROWSERSTACK_ACCESS_KEY -X POST \
  https://load-api.browserstack.com/api/v1/runs/{run_id}/stop

Response attributes 200 OK JSON

Response

{
  "run_id": "run-abc123",
  "state": "aborted",
  "terminal_reason": "user_stopped"
}

Common workflows

The following examples show how to use the Runs API to automate common tasks.

Trigger a test and wait for the report

This bash script triggers a test, polls for completion, and fetches the report:

#!/bin/bash

BROWSERSTACK_USERNAME="..."
BROWSERSTACK_ACCESS_KEY="..."

# 1. Trigger the run
response=$(curl -s -u "$BROWSERSTACK_USERNAME:$BROWSERSTACK_ACCESS_KEY" -X POST \
  https://load-api.browserstack.com/api/v1/runs \
  -H "Content-Type: application/json" \
  -d '{
    "project_name": "my-project",
    "test_name": "checkout-flow"
  }')

run_id=$(echo "$response" | jq -r '.run_id')
echo "Run triggered: $run_id"

# 2. Poll status until complete
while true; do
  status=$(curl -s -u "$BROWSERSTACK_USERNAME:$BROWSERSTACK_ACCESS_KEY" \
    https://load-api.browserstack.com/api/v1/runs/"$run_id"/status)

  state=$(echo "$status" | jq -r '.state')
  report_ready=$(echo "$status" | jq -r '.report_ready')

  if [[ "$state" == "completed" ]] && [[ "$report_ready" == "true" ]]; then
    echo "Test complete"
    break
  fi

  echo "State: $state | Report ready: $report_ready"
  sleep 10
done

# 3. Fetch the report
report=$(curl -s -u "$BROWSERSTACK_USERNAME:$BROWSERSTACK_ACCESS_KEY" \
  https://load-api.browserstack.com/api/v1/runs/"$run_id"/report)

echo "SLA verdict: $(echo "$report" | jq -r '.sla_verdict')"
echo "Full report: $(echo "$report" | jq -r '.report_url')"

Errors

When the API returns an error, the response body contains details:

{
  "error": "Project not found",
  "message": "No project named 'typo-project' exists in your account"
}

Troubleshooting

Refer to these common issues and solutions when working with the Runs API.

Status returns provisioning for a long time

Test infrastructure is warming up. This is expected and can take 30 to 60 seconds depending on the load profile. Once state becomes running, the load test has started.

Report returns 503

The backend reporting service is temporarily unavailable. Retry in 10 to 30 seconds. If 503 persists, contact support.

Report shows sla_verdict: not_evaluated

This means either:

• No thresholds were configured for the test. All requests succeeded and completed, but there are no pass/fail criteria. Add thresholds to your test configuration to enable SLA evaluation.
• The evaluator did not complete before the run ended. Check that the test ran to completion (state is completed, not failed or aborted).

Stop endpoint returns 200 but status still shows running

State transitions are asynchronous. Retry the status endpoint in 2 to 5 seconds. The run will transition to aborted shortly.