Skip to main content
PUT
/
api
/
test-runs
Trigger a test run
curl --request PUT \
  --url https://api.empirical.run/api/test-runs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "environment": "<string>",
  "build": {
    "url": "<string>",
    "branch": "<string>",
    "commit": "<string>",
    "commit_url": "<string>",
    "version": "<string>"
  },
  "metadata": {},
  "environment_variables_overrides": [
    {
      "name": "<string>",
      "value": "<string>"
    }
  ],
  "tags": [
    "<string>"
  ],
  "branch": "<string>",
  "project_id": 2,
  "send_notifications": true,
  "total_shards": 2,
  "rerun_source_id": 2,
  "rerun_only_failed": true,
  "github_actor": "<string>"
}
'
{
  "data": {
    "trigger": {
      "success": true
    },
    "test_run": {
      "id": 123,
      "state": "<string>",
      "test_run_branch": "<string>",
      "created_at": "<string>"
    }
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
environment
string
required

The environment slug to run tests against (e.g., production, staging).

​
build
object

Build information to associate with the test run.

​
metadata
object

Custom key-value pairs to associate with the test run. Values must be strings or numbers.

​
environment_variables_overrides
object[]

Environment variables to override for this test run.

​
tags
string[]

Tags to filter which tests to run (e.g., @smoke, @critical). Only tests matching these tags will be executed.

​
branch
string

Test repo branch to run. Useful for running tests from a feature branch before merging. Cannot be used together with build — pick one.

​
project_id
integer

Legacy project ID; must match the request's resolved project scope when set. The project scope itself comes from the bound principal or the x-project-id header, never from the body.

Required range: x >= 1
​
send_notifications
boolean

Whether to send run notifications. Defaults to true.

​
total_shards
integer

Override the number of shards to split the run across.

Required range: x >= 1
​
rerun_source_id
integer

ID of the test run this run is a rerun of.

Required range: x >= 1
​
rerun_only_failed
boolean

When rerunning, only re-execute the previously failed tests.

​
github_actor
string

GitHub username that triggered the run, for attribution.

Response

The triggered test run.

​
data
object
required