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
Nonblank build ID to use for the main app. Requires deployment_config_id. The selected deployment config determines its meaning: Build Storage uses a UUID, while an external-platform source uses the opaque ID returned by List Builds. Extra apps use extra_build_ids. Omit build_id to use the config’s saved or default selection.
object
Optional Build Storage UUIDs for extra apps on the selected deployment config, keyed by extra app number ("1", "2", or "3"). The number is the app’s position in that config’s summary.extra_apps; it is independent of the player number. Supported for existing tests, test plans, and ephemeral runs (instructions). The main app can use skip_install while extra apps are pinned.Omit an entry to keep that app’s saved build selection. Omitting the whole field preserves all saved extra-app selections; {} is a no-op. A non-empty top-level map requires top-level deployment_config_id.
Explicit extra build IDs work only when the corresponding extra app uses Build Storage. Each build must belong to the project, be ready, and match the extra app’s platform. An explicit ID takes precedence over that app’s required_tags filter.
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. Required when using instructions for an ephemeral run; optional as an override for existing test and test plan runs.
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, interpreted by the selected deployment config’s source. 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).

Selecting a Build

Use build_id to select the main app build for the deployment config. For a Build Storage source, pass its UUID from List Builds. For an external-platform source, pass the nonblank opaque ID returned by that endpoint with deployment_config_id. The same source-aware rule applies to the default deployment config, per-player configs, and ephemeral runs. Omitting build_id uses the selected config’s saved or default build selection. extra_build_ids remains limited to Build Storage UUIDs for extra apps.

Example: Build Storage 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

Nonblank main-app build ID interpreted by the selected deployment config's source: a UUID for Build Storage or an opaque external-platform ID. Requires deployment_config_id; applies to the default config and ephemeral runs. Omit it to use the config's saved or default selection.

Minimum string length: 1
Pattern: \S
extra_build_ids
object

Build pins for extra apps in the top-level deployment_config_id. A nonempty map requires that config ID; put per-player or per-slot pins inside their respective entries. Supported for all request variants.

Example:
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. Required when using instructions for an ephemeral run; optional as an override for existing test and test plan runs.

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.