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
multiplayer_test_id
string
UUID of the test to run. Mutually exclusive with test_plan_id and instructions.
test_plan_id
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.
instructions
string
Test instructions to execute as an ephemeral (one-off) test. Mutually exclusive with multiplayer_test_id and test_plan_id.
deployment_config_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.
name
string
Display name for the run. Only applies when using instructions. Defaults to "[api] ephemeral test".
build_id
string
UUID of a build from Build Storage to use for this run. Requires deployment_config_id. See Using Build Storage Builds below.
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, 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.
agent_config_id
string
UUID of an agent configuration to use. Applies to all request variants.
additional_tags
string[]
Tags to add to the run. When using instructions (ephemeral), "api" is automatically prepended to the provided tags.
retries
integer
default:"0"
Number of times to retry the test if it fails. Only applies when using multiplayer_test_id. Must be between 0 and 10.
instances
integer
default:"1"
Number of parallel instances to run. Only applies when using multiplayer_test_id. Must be between 1 and 10.
render_templates
boolean
default:"false"
Enable template rendering
template_data
object
Key-value pairs for template variables
options
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

Returns 201 Created on success. The body contains the started-run data directly (no { ok, status, message, data } envelope).
job_ids
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.
build_id
string
Build ID used for the run. Returned for multiplayer test and test plan runs.
test_id
string
UUID of the created ephemeral test. Only returned for ephemeral (instructions) runs.
message
string
Optional status message returned for multiplayer test and test plan runs.
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 test if it fails. 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
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. Returned with HTTP 201 on success. The body contains the started-run data directly (no { ok, status, message, data } envelope).

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.