Skip to main content
PUT
/
api
/
test-runs
Create 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>"
}
'
{
  "data": {
    "trigger": {
      "success": true
    },
    "test_run": {
      "id": 456,
      "state": "queued",
      "test_run_branch": "main",
      "created_at": "2024-01-15T10:30:00.000Z"
    }
  }
}
Triggers a new test run for the specified project and environment. 
{
  "data": {
    "trigger": {
      "success": true
    },
    "test_run": {
      "id": 456,
      "state": "queued",
      "test_run_branch": "main",
      "created_at": "2024-01-15T10:30:00.000Z"
    }
  }
}

​
Minimal request

curl -X PUT \
  https://api.empirical.run/api/test-runs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $EMPIRICALRUN_KEY" \
  -d '{
    "environment": "production"
  }'

​
With build info

The build URL is passed to tests as the BUILD_URL environment variable, unless BUILD_URL is explicitly set in environment_variables_overrides. 
curl -X PUT \
  https://api.empirical.run/api/test-runs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $EMPIRICALRUN_KEY" \
  -d '{
    "environment": "production",
    "build": {
      "url": "https://app.example.com",
      "branch": "main",
      "commit": "abc123",
      "commit_url": "https://github.com/org/repo/commit/abc123"
    },
    "metadata": {
      "deployed_by": "alice"
    }
  }'

​
With environment variables

Overrides the environment’s configured variables for this run. If the environment slug is not found, the error response lists the available environment slugs for the project. 
curl -X PUT \
  https://api.empirical.run/api/test-runs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $EMPIRICALRUN_KEY" \
  -d '{
    "environment": "staging",
    "environment_variables_overrides": [
      { "name": "BASE_URL", "value": "https://staging.example.com" }
    ]
  }'

​
With tags

curl -X PUT \
  https://api.empirical.run/api/test-runs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $EMPIRICALRUN_KEY" \
  -d '{
    "environment": "production",
    "tags": ["@smoke", "@critical"]
  }'

​
With a custom test repo branch

If branch is not mentioned, test run is triggered on default project branch. Use this param for running tests from a branch currently you are working on before merging. This param works only if this branch exists on the remote repository. Cannot be used together with build parameter — pick one. 
curl -X PUT \
  https://api.empirical.run/api/test-runs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $EMPIRICALRUN_KEY" \
  -d '{
    "environment": "production",
    "branch": "feat/new-checkout-tests"
  }'

Authorizations

​
Authorization
string
header
required

Project API key from the Empirical dashboard.

Body

application/json

Test run to create.

​
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.

Response

Created test run.

​
data
object
required