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>"
],
"test_case_ids": [
"<string>"
],
"branch": "<string>",
"project_id": 2,
"send_notifications": true,
"total_shards": 2,
"rerun_source_id": 2,
"rerun_only_failed": true,
"github_actor": "<string>"
}
'import requests
url = "https://api.empirical.run/api/test-runs"
payload = {
"environment": "<string>",
"build": {
"url": "<string>",
"branch": "<string>",
"commit": "<string>",
"commit_url": "<string>",
"version": "<string>"
},
"metadata": {},
"environment_variables_overrides": [
{
"name": "<string>",
"value": "<string>"
}
],
"tags": ["<string>"],
"test_case_ids": ["<string>"],
"branch": "<string>",
"project_id": 2,
"send_notifications": True,
"total_shards": 2,
"rerun_source_id": 2,
"rerun_only_failed": True,
"github_actor": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
environment: '<string>',
build: {
url: '<string>',
branch: '<string>',
commit: '<string>',
commit_url: '<string>',
version: '<string>'
},
metadata: {},
environment_variables_overrides: [{name: '<string>', value: '<string>'}],
tags: ['<string>'],
test_case_ids: ['<string>'],
branch: '<string>',
project_id: 2,
send_notifications: true,
total_shards: 2,
rerun_source_id: 2,
rerun_only_failed: true,
github_actor: '<string>'
})
};
fetch('https://api.empirical.run/api/test-runs', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.empirical.run/api/test-runs",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'environment' => '<string>',
'build' => [
'url' => '<string>',
'branch' => '<string>',
'commit' => '<string>',
'commit_url' => '<string>',
'version' => '<string>'
],
'metadata' => [
],
'environment_variables_overrides' => [
[
'name' => '<string>',
'value' => '<string>'
]
],
'tags' => [
'<string>'
],
'test_case_ids' => [
'<string>'
],
'branch' => '<string>',
'project_id' => 2,
'send_notifications' => true,
'total_shards' => 2,
'rerun_source_id' => 2,
'rerun_only_failed' => true,
'github_actor' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.empirical.run/api/test-runs"
payload := strings.NewReader("{\n \"environment\": \"<string>\",\n \"build\": {\n \"url\": \"<string>\",\n \"branch\": \"<string>\",\n \"commit\": \"<string>\",\n \"commit_url\": \"<string>\",\n \"version\": \"<string>\"\n },\n \"metadata\": {},\n \"environment_variables_overrides\": [\n {\n \"name\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"tags\": [\n \"<string>\"\n ],\n \"test_case_ids\": [\n \"<string>\"\n ],\n \"branch\": \"<string>\",\n \"project_id\": 2,\n \"send_notifications\": true,\n \"total_shards\": 2,\n \"rerun_source_id\": 2,\n \"rerun_only_failed\": true,\n \"github_actor\": \"<string>\"\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.put("https://api.empirical.run/api/test-runs")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"environment\": \"<string>\",\n \"build\": {\n \"url\": \"<string>\",\n \"branch\": \"<string>\",\n \"commit\": \"<string>\",\n \"commit_url\": \"<string>\",\n \"version\": \"<string>\"\n },\n \"metadata\": {},\n \"environment_variables_overrides\": [\n {\n \"name\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"tags\": [\n \"<string>\"\n ],\n \"test_case_ids\": [\n \"<string>\"\n ],\n \"branch\": \"<string>\",\n \"project_id\": 2,\n \"send_notifications\": true,\n \"total_shards\": 2,\n \"rerun_source_id\": 2,\n \"rerun_only_failed\": true,\n \"github_actor\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.empirical.run/api/test-runs")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"environment\": \"<string>\",\n \"build\": {\n \"url\": \"<string>\",\n \"branch\": \"<string>\",\n \"commit\": \"<string>\",\n \"commit_url\": \"<string>\",\n \"version\": \"<string>\"\n },\n \"metadata\": {},\n \"environment_variables_overrides\": [\n {\n \"name\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"tags\": [\n \"<string>\"\n ],\n \"test_case_ids\": [\n \"<string>\"\n ],\n \"branch\": \"<string>\",\n \"project_id\": 2,\n \"send_notifications\": true,\n \"total_shards\": 2,\n \"rerun_source_id\": 2,\n \"rerun_only_failed\": true,\n \"github_actor\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"trigger": {
"success": true
},
"test_run": {
"id": 123,
"state": "<string>",
"test_run_branch": "<string>",
"created_at": "<string>"
}
}
}{
"data": "<unknown>",
"error": {
"message": "<string>"
}
}{
"data": "<unknown>",
"error": {
"message": "<string>"
}
}Trigger a test run
Triggers a new end-to-end test run for the scoped project against the given environment, resolving the branch/build and dispatching the 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>"
],
"test_case_ids": [
"<string>"
],
"branch": "<string>",
"project_id": 2,
"send_notifications": true,
"total_shards": 2,
"rerun_source_id": 2,
"rerun_only_failed": true,
"github_actor": "<string>"
}
'import requests
url = "https://api.empirical.run/api/test-runs"
payload = {
"environment": "<string>",
"build": {
"url": "<string>",
"branch": "<string>",
"commit": "<string>",
"commit_url": "<string>",
"version": "<string>"
},
"metadata": {},
"environment_variables_overrides": [
{
"name": "<string>",
"value": "<string>"
}
],
"tags": ["<string>"],
"test_case_ids": ["<string>"],
"branch": "<string>",
"project_id": 2,
"send_notifications": True,
"total_shards": 2,
"rerun_source_id": 2,
"rerun_only_failed": True,
"github_actor": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
environment: '<string>',
build: {
url: '<string>',
branch: '<string>',
commit: '<string>',
commit_url: '<string>',
version: '<string>'
},
metadata: {},
environment_variables_overrides: [{name: '<string>', value: '<string>'}],
tags: ['<string>'],
test_case_ids: ['<string>'],
branch: '<string>',
project_id: 2,
send_notifications: true,
total_shards: 2,
rerun_source_id: 2,
rerun_only_failed: true,
github_actor: '<string>'
})
};
fetch('https://api.empirical.run/api/test-runs', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.empirical.run/api/test-runs",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'environment' => '<string>',
'build' => [
'url' => '<string>',
'branch' => '<string>',
'commit' => '<string>',
'commit_url' => '<string>',
'version' => '<string>'
],
'metadata' => [
],
'environment_variables_overrides' => [
[
'name' => '<string>',
'value' => '<string>'
]
],
'tags' => [
'<string>'
],
'test_case_ids' => [
'<string>'
],
'branch' => '<string>',
'project_id' => 2,
'send_notifications' => true,
'total_shards' => 2,
'rerun_source_id' => 2,
'rerun_only_failed' => true,
'github_actor' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.empirical.run/api/test-runs"
payload := strings.NewReader("{\n \"environment\": \"<string>\",\n \"build\": {\n \"url\": \"<string>\",\n \"branch\": \"<string>\",\n \"commit\": \"<string>\",\n \"commit_url\": \"<string>\",\n \"version\": \"<string>\"\n },\n \"metadata\": {},\n \"environment_variables_overrides\": [\n {\n \"name\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"tags\": [\n \"<string>\"\n ],\n \"test_case_ids\": [\n \"<string>\"\n ],\n \"branch\": \"<string>\",\n \"project_id\": 2,\n \"send_notifications\": true,\n \"total_shards\": 2,\n \"rerun_source_id\": 2,\n \"rerun_only_failed\": true,\n \"github_actor\": \"<string>\"\n}")
req, _ := http.NewRequest("PUT", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.put("https://api.empirical.run/api/test-runs")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"environment\": \"<string>\",\n \"build\": {\n \"url\": \"<string>\",\n \"branch\": \"<string>\",\n \"commit\": \"<string>\",\n \"commit_url\": \"<string>\",\n \"version\": \"<string>\"\n },\n \"metadata\": {},\n \"environment_variables_overrides\": [\n {\n \"name\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"tags\": [\n \"<string>\"\n ],\n \"test_case_ids\": [\n \"<string>\"\n ],\n \"branch\": \"<string>\",\n \"project_id\": 2,\n \"send_notifications\": true,\n \"total_shards\": 2,\n \"rerun_source_id\": 2,\n \"rerun_only_failed\": true,\n \"github_actor\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.empirical.run/api/test-runs")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"environment\": \"<string>\",\n \"build\": {\n \"url\": \"<string>\",\n \"branch\": \"<string>\",\n \"commit\": \"<string>\",\n \"commit_url\": \"<string>\",\n \"version\": \"<string>\"\n },\n \"metadata\": {},\n \"environment_variables_overrides\": [\n {\n \"name\": \"<string>\",\n \"value\": \"<string>\"\n }\n ],\n \"tags\": [\n \"<string>\"\n ],\n \"test_case_ids\": [\n \"<string>\"\n ],\n \"branch\": \"<string>\",\n \"project_id\": 2,\n \"send_notifications\": true,\n \"total_shards\": 2,\n \"rerun_source_id\": 2,\n \"rerun_only_failed\": true,\n \"github_actor\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"trigger": {
"success": true
},
"test_run": {
"id": 123,
"state": "<string>",
"test_run_branch": "<string>",
"created_at": "<string>"
}
}
}{
"data": "<unknown>",
"error": {
"message": "<string>"
}
}{
"data": "<unknown>",
"error": {
"message": "<string>"
}
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
The environment slug to run tests against (e.g., production, staging).
Build information to associate with the test run.
Show child attributes
Show child attributes
Custom key-value pairs to associate with the test run. Values must be strings or numbers.
Show child attributes
Show child attributes
Environment variables to override for this test run.
Show child attributes
Show child attributes
Tags to filter which tests to run (e.g., @smoke, @critical). Only tests matching these tags will be executed.
Specific test case ids (Playwright per-project test.id) to run. Only these tests will be executed.
Test repo branch to run. Useful for running tests from a feature branch before merging. Cannot be used together with build — pick one.
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.
x >= 1Whether to send run notifications. Defaults to true.
Override the number of shards to split the run across.
x >= 1ID of the test run this run is a rerun of.
x >= 1When rerunning, only re-execute the previously failed tests.
GitHub username that triggered the run, for attribution.
Response
The triggered test run.
Show child attributes
Show child attributes
Was this page helpful?