Skip to main content
PUT
/
api
/
test-runs
Create Test Run
curl --request PUT \
  --url https://api.example.com/api/test-runs \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "environment": "<string>",
  "build": {
    "build.url": "<string>",
    "build.branch": "<string>",
    "build.commit": "<string>",
    "build.commit_url": "<string>",
    "build.version": "<string>"
  },
  "metadata": {},
  "environment_variables_overrides": [
    {
      "name": "<string>",
      "value": "<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.

​
Examples

​
Request

​
Authorization
string
required
Bearer token for authentication. Format: Bearer <your-api-key>
​
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.
{
  "deployed_by": "alice",
  "ticket": "JIRA-1234"
}
​
environment_variables_overrides
array
Environment variables to override for this test run.

​
Response

​
data.trigger.success
boolean
Whether the test run was triggered successfully.
​
data.test_run
object
The created test run object.
{
  "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://dash.empirical.run/api/test-runs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $EMPIRICALRUN_KEY" \
  -d '{
    "environment": "production"
  }'

​
With build info

curl -X PUT \
  https://dash.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

curl -X PUT \
  https://dash.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" }
    ]
  }'