Start a Run
Start a new test run using a multiplayer test, a test plan, or ephemeral instructions.
project:operate-runsRequest Body
multiplayer_test_id, test_plan_id, or instructions:multiplayer_test_id: run an existing testtest_plan_id: run an existing test planinstructions: run an ephemeral (one-off) test without creating a test case first
test_plan_id and instructions.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.multiplayer_test_id and test_plan_id.player_deployment_configs entry. Required, except for multiplayer tests
where player_deployment_configs covers every player.instructions. Defaults to "[api] ephemeral test".deployment_config_id. See Using Build Storage Builds below."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.instructions (ephemeral), "api" is automatically prepended to the provided tags.multiplayer_test_id. Must be between 0 and 10.multiplayer_test_id. Must be between 1 and 10.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
Returns201 Created on success. The body contains the started-run data
directly (no { ok, status, message, data } envelope).
instructions) runs.{ "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 thebuild_id parameter.
Example: Upload and Test
Complete CI/CD Example
Here’s a complete example that starts a test and polls for completion:Authorizations
API key for authentication
Path Parameters
The project ID. You can copy it from the project settings page or the project URL in the dashboard.
Body
- Option 1
- Option 2
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.
UUID of the test to run (provide this OR test_plan_id OR instructions)
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.
Test instructions to execute as an ephemeral (one-off) test. Mutually exclusive with multiplayer_test_id and test_plan_id.
UUID of a build from Build Storage to use for this run. Only works with build-storage deployment configs, and requires deployment_config_id.
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.
Display name for the run. Only applies when using instructions. Defaults to '[api] ephemeral test'.
UUID of an agent configuration to use
Tags to add to the run. When using instructions (ephemeral), the tag 'api' is automatically prepended.
Number of times to retry the test if it fails. Only applies when using multiplayer_test_id.
0 <= x <= 10Number of parallel instances to run. Only applies when using multiplayer_test_id.
1 <= x <= 10Enable template rendering
Key-value pairs for template variables
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).
Array of job IDs created. Single test returns 1 job; test plan returns one job per test.
Build ID used for the run. Returned for multiplayer test and test plan runs.
UUID of the created ephemeral test. Only returned for ephemeral (instructions) runs.
Test plan execution ID. Returned for test plan runs.
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.
Optional status message returned for multiplayer test and test plan runs.