Skip to main content
POST
Permission Required: project:operate-runs
Start a new test run using a multiplayer test, a test plan, or ephemeral instructions.

Request Body

Provide exactly one of multiplayer_test_id, test_plan_id, or instructions:
  • multiplayer_test_id: run an existing test
  • test_plan_id: run an existing test plan
  • instructions: run an ephemeral (one-off) test without creating a test case first
string
UUID of the test to run. Mutually exclusive with test_plan_id and instructions.
string
UUID of the test plan to run. Mutually exclusive with multiplayer_test_id and instructions. This endpoint starts test plans with a single deployment config; to supply per-slot configs for a cross-platform plan, use Start Test Plan Run instead.
string
Test instructions to execute as an ephemeral (one-off) test. Mutually exclusive with multiplayer_test_id and test_plan_id.
string
UUID of the deployment configuration, used by every player that has no player_deployment_configs entry. Required, except for multiplayer tests where player_deployment_configs covers every player.
string
Display name for the run. Only applies when using instructions. Defaults to "[api] ephemeral test".
string
UUID of a build from Build Storage to use for this run. Requires deployment_config_id. See Using Build Storage Builds below.
object
Per-player deployment configs for cross-platform multiplayer tests, keyed by player number ("1", "2", and so on). Only applies with multiplayer_test_id, and keys must be within the test’s player count. The map does not need to cover every player: any player without an entry falls back to the default deployment_config_id. Omitting deployment_config_id is only allowed when every player has an entry; a partial map without a default returns a 400 error listing the missing players. Private device configs are allowed, but every player on a private device needs its own device; if the configs cannot give each player a distinct device, the request returns a 400 error.
string
UUID of an agent configuration to use. Applies to all request variants.
string[]
Tags to add to the run. When using instructions (ephemeral), "api" is automatically prepended to the provided tags.
integer
default:"0"
Number of times to retry the run after an execution failure (ERROR, TIMEOUT, STOPPED). Genuine test verdicts (FAILED, BLOCKED, SKIPPED) are final and are not retried. Only applies when using multiplayer_test_id. Must be between 0 and 10.
integer
default:"1"
Number of parallel instances to run. Only applies when using multiplayer_test_id. Must be between 1 and 10.
boolean
default:"false"
Start one independent run on every device configured in deployment_config_id. Supported for mobile deployment configurations with multi-device runs enabled. Requires deployment_config_id and cannot be combined with player_deployment_configs. For existing tests, instances applies independently on each device, so the aggregate run count is instances multiplied by the number of configured devices. Normal concurrency and billing rules apply.
boolean
default:"false"
Enable template rendering
object
Key-value pairs for template variables
object
Per-run override knobs.
The test time budget is not overridable here. It lives on the test version itself (min_seconds / max_seconds on the test body). Edit the test, or create a new version, when you want to change the budget. See Create a Test for the per-framework defaults and rules.

Response

Single-device requests return 201 Created. Multi-device requests return aggregate per-device results; see the fields below. The body contains the started-run data directly (no { ok, status, message, data } envelope).
string[]
required
Array of job IDs created. For a single test, this contains one job. For a test plan, this contains one job per test in the plan. Use with Get Job Details to poll for completion.
string
Build ID used for the run. Returned for multiplayer test and test plan runs.
string
UUID of the created ephemeral test. Only returned for ephemeral (instructions) runs.
string
Optional status message returned for multiplayer test and test plan runs.
boolean
Whether at least one device run started. Returned for multi-device requests.
integer
Number of runs requested across configured devices. Returned for multi-device existing-test and test-plan requests.
integer
Number of runs started successfully. Returned for multi-device existing-test and test-plan requests.
integer
Alias for started_count in multi-device existing-test and test-plan responses.
integer
Number of requested runs that failed to start. Returned for multi-device existing-test and test-plan requests.
object[]
Per-device start results for existing-test and test-plan requests. Each item includes device_label, ok, status, and failure message; successful items may include the upstream response under data.
object[]
Per-device start results for ephemeral (instructions) requests. Each item includes device_label, ok, and, when available, status and message.
Multi-device requests return 201 when every device run starts and 207 when only some start. A request that cannot start any saved-test or test-plan run returns 500.
On failure, returns { "error": "<message>" } with an appropriate HTTP status (400, 401, 403, 404, 500).

Using Build Storage Builds

You can run tests against a specific build from Build Storage by providing the build_id parameter.
The build_id parameter only works with deployment configs that use Build Storage as their build source. If the deployment config uses a different build source (e.g., direct URL), the request will return a 400 error.

Example: Upload and Test


Complete CI/CD Example

Here’s a complete example that starts a test and polls for completion:

Authorizations

X-Api-Key
string
header
required

API key for authentication

Path Parameters

projectId
string
required

The project ID. You can copy it from the project settings page or the project URL in the dashboard.

Body

application/json
deployment_config_id
string
required

UUID of the deployment configuration, used by every player that has no player_deployment_configs entry. Required, except for multiplayer tests where player_deployment_configs covers every player.

multiplayer_test_id
string

UUID of the test to run (provide this OR test_plan_id OR instructions)

test_plan_id
string

UUID of the test plan to run (provide this OR multiplayer_test_id OR instructions). This endpoint starts test plans with a single deployment config; to supply per-slot configs for a cross-platform plan, use POST /test-plans/{testPlanId}/runs instead.

instructions
string

Test instructions to execute as an ephemeral (one-off) test. Mutually exclusive with multiplayer_test_id and test_plan_id.

build_id
string<uuid>

UUID of a build from Build Storage to use for this run. Only works with build-storage deployment configs, and requires deployment_config_id.

player_deployment_configs
object

Per-player deployment configs for cross-platform multiplayer tests, keyed by player number ("1", "2", and so on). Only applies with multiplayer_test_id. The map does not need to cover every player: any player without an entry falls back to the default deployment_config_id. Omitting deployment_config_id is only allowed when every player has an entry; a partial map without a default returns a 400 error. Private device configs are allowed, but every player on a private device needs its own device; if the configs cannot give each player a distinct device, the request returns a 400 error.

name
string

Display name for the run. Only applies when using instructions. Defaults to '[api] ephemeral test'.

agent_config_id
string<uuid>

UUID of an agent configuration to use

additional_tags
string[]

Tags to add to the run. When using instructions (ephemeral), the tag 'api' is automatically prepended.

retries
integer
default:0

Number of times to retry the run after an execution failure (ERROR, TIMEOUT, STOPPED). Genuine test verdicts (FAILED, BLOCKED, SKIPPED) are final and are not retried. Only applies when using multiplayer_test_id.

Required range: 0 <= x <= 10
instances
integer
default:1

Number of parallel instances to run. Only applies when using multiplayer_test_id.

Required range: 1 <= x <= 10
run_on_all_configured_devices
boolean
default:false

Start one independent run on every device configured in deployment_config_id. Supported for mobile deployment configurations with multi-device runs enabled. Requires deployment_config_id; for multiplayer tests, cannot be combined with player_deployment_configs. For multiplayer tests, instances applies independently on each device.

render_templates
boolean
default:false

Enable template rendering

template_data
object

Key-value pairs for template variables

options
object

Per-run override knobs. The time budget is intentionally not overridable here; it lives on the test version itself (see min_seconds / max_seconds on the test body), so callers should edit the test (or create a new version) when they want to change the budget.

Response

Run started successfully

Response body for POST /runs and POST /test-plans/{testPlanId}/runs. Single-device responses are returned with HTTP 201. Multi-device responses include per-device results and aggregate counts; HTTP 201 means all devices started, HTTP 207 means partial success, and HTTP 500 means none started.

ok
boolean

Whether at least one device run started. Returned for multi-device requests.

job_ids
string<uuid>[]

Array of job IDs created. Single test returns 1 job; test plan returns one job per test.

build_id
string<uuid>

Build ID used for the run. Returned for multiplayer test and test plan runs.

test_id
string<uuid>

UUID of the created ephemeral test. Only returned for ephemeral (instructions) runs.

test_plan_execution_id
string<uuid>

Test plan execution ID. Returned for test plan runs.

slot_build_ids
object

For cross-platform test plan runs: the build pinned for each extra slot, keyed by slot index. Only present when slot configs resolved to builds.

message
string

Optional status message returned for multiplayer test and test plan runs.

requested_count
integer

Number of runs requested across configured devices. For multiplayer tests, includes the instances multiplier.

started_count
integer

Number of runs started successfully. For multiplayer tests, includes the instances multiplier.

successful_count
integer

Alias for started_count in multi-device existing-test and test-plan responses.

failed_count
integer

Number of requested runs that failed to start.

results
object[]

Per-device start results for existing-test and test-plan requests.

device_runs
object[]

Per-device start results for ephemeral (instructions) requests.