Start Test Plan Run

curl -X POST "https://nunu.ai/api/v1/project/your-project-id/test-plans/b3f1a2c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c/runs" \
  -H "X-Api-Key: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "deployment_config_id": "456e7890-e89b-12d3-a456-426614174000",
    "additional_tags": ["nightly"]
  }'

curl -X POST "https://nunu.ai/api/v1/project/your-project-id/test-plans/b3f1a2c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c/runs" \
  -H "X-Api-Key: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "deployment_config_id": "456e7890-e89b-12d3-a456-426614174000",
    "slot_deployment_configs": {
      "2": { "deployment_config_id": "9a1b2c3d-4e5f-6789-a0b1-c2d3e4f5a6b7" }
    }
  }'

curl -X POST "https://nunu.ai/api/v1/project/your-project-id/test-plans/b3f1a2c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c/runs" \
  -H "X-Api-Key: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "deployment_config_id": "456e7890-e89b-12d3-a456-426614174000",
    "run_on_all_configured_devices": true
  }'

{
  "job_ids": [
    "cc6e3994-a714-4b6b-9879-0b3e53c0a3af",
    "dd1e4a55-b825-4c8b-baaf-1d4e63d1b4be"
  ],
  "test_plan_execution_id": "abc12345-6789-def0-1234-56789abcdef0"
}

{
  "error": "test plan not found"
}

POST

project

{projectId}

test-plans

{testPlanId}

runs

curl -X POST "https://nunu.ai/api/v1/project/your-project-id/test-plans/b3f1a2c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c/runs" \
  -H "X-Api-Key: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "deployment_config_id": "456e7890-e89b-12d3-a456-426614174000",
    "additional_tags": ["nightly"]
  }'

curl -X POST "https://nunu.ai/api/v1/project/your-project-id/test-plans/b3f1a2c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c/runs" \
  -H "X-Api-Key: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "deployment_config_id": "456e7890-e89b-12d3-a456-426614174000",
    "slot_deployment_configs": {
      "2": { "deployment_config_id": "9a1b2c3d-4e5f-6789-a0b1-c2d3e4f5a6b7" }
    }
  }'

curl -X POST "https://nunu.ai/api/v1/project/your-project-id/test-plans/b3f1a2c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c/runs" \
  -H "X-Api-Key: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "deployment_config_id": "456e7890-e89b-12d3-a456-426614174000",
    "run_on_all_configured_devices": true
  }'

{
  "job_ids": [
    "cc6e3994-a714-4b6b-9879-0b3e53c0a3af",
    "dd1e4a55-b825-4c8b-baaf-1d4e63d1b4be"
  ],
  "test_plan_execution_id": "abc12345-6789-def0-1234-56789abcdef0"
}

{
  "error": "test plan not found"
}

Permission Required: project:operate-runs

Start a run for a specific test plan. This is the test-plan-scoped equivalent of Start a Run: instead of supplying test_plan_id in the body, the plan is identified by the URL path. It is also the only endpoint that accepts slot_deployment_configs for cross-platform plans. The response contains one job_id per test in the plan; poll each one with Get Job Details to wait for completion.

Path Parameters

string

required

The test plan ID (UUID)

Request Body

string

UUID of the deployment configuration for the plan’s default slot (slot 1), used by every player not assigned to an extra slot; for plans without extra slots this is simply the config used by every test. Required unless the plan’s slot assignments cover every player of every test and slot_deployment_configs is supplied.

string

UUID of an agent configuration applied to every test in the plan.

string

UUID of a build from Build Storage for the default slot. Only works with deployment configs that use Build Storage as their build source, and requires deployment_config_id; otherwise the request returns a 400 error.

object

Per-slot deployment configs for cross-platform test plans, keyed by slot index ("2", "3", and so on). Fetch the plan with Get Test Plan to see its slots. Every slot used by the plan’s player assignments needs an entry; keys referencing slots the plan does not define return a 400 error. The key "1" addresses the default slot as an alternative to the top-level deployment_config_id/build_id (supplying both returns a 400 error). Private device configs are allowed, but every player on a private device needs its own device; if the configs of a test cannot give each of its players a distinct device, the request returns a 400 error.

Show entry properties

string

required

Deployment config to use for this slot.

string

Optional Build Storage build for this slot (build-storage configs only).

string[]

Tags appended to every resulting run.

boolean

default:"false"

Enable Handlebars-style templating in test step bodies.

object

Key-value pairs for template variables. Used only when render_templates is true.

object

Per-run override knobs, with the same shape as options on Start a Run (performance_monitoring, mobile_auto_grant_permissions, mobile_geolocation, mobile_gpslocation). Time-budget overrides are intentionally not accepted here; the budget lives on the test version itself (min_seconds / max_seconds).

boolean

default:"false"

Start one independent test-plan 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 slot_deployment_configs. Normal concurrency and billing rules apply.

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), typically including job_ids[] (one per test in the plan) and test_plan_execution_id, so the caller can correlate results via List Test Plan Executions.

string[]

required

Job IDs created for each test in the plan

string

ID of the test plan execution

object

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

boolean

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

integer

Number of test-plan runs requested across configured devices.

integer

Number of test-plan runs started successfully.

integer

Alias for started_count in multi-device responses.

integer

Number of test-plan runs that failed to start.

object[]

Per-device start results. Each item includes device_label, ok, status, and failure message; successful items may include the upstream response under data.

Multi-device requests return 201 when every device run starts, 207 when only some start, and 500 when none start.

On failure, returns { "error": "<message>" } with an appropriate HTTP status.

curl -X POST "https://nunu.ai/api/v1/project/your-project-id/test-plans/b3f1a2c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c/runs" \
  -H "X-Api-Key: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "deployment_config_id": "456e7890-e89b-12d3-a456-426614174000",
    "additional_tags": ["nightly"]
  }'

curl -X POST "https://nunu.ai/api/v1/project/your-project-id/test-plans/b3f1a2c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c/runs" \
  -H "X-Api-Key: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "deployment_config_id": "456e7890-e89b-12d3-a456-426614174000",
    "slot_deployment_configs": {
      "2": { "deployment_config_id": "9a1b2c3d-4e5f-6789-a0b1-c2d3e4f5a6b7" }
    }
  }'

curl -X POST "https://nunu.ai/api/v1/project/your-project-id/test-plans/b3f1a2c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c/runs" \
  -H "X-Api-Key: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "deployment_config_id": "456e7890-e89b-12d3-a456-426614174000",
    "run_on_all_configured_devices": true
  }'

{
  "job_ids": [
    "cc6e3994-a714-4b6b-9879-0b3e53c0a3af",
    "dd1e4a55-b825-4c8b-baaf-1d4e63d1b4be"
  ],
  "test_plan_execution_id": "abc12345-6789-def0-1234-56789abcdef0"
}

{
  "error": "test plan not found"
}

Authorizations

X-Api-Key

string

header

required

API key for authentication

Path Parameters

testPlanId

string<uuid>

required

Test plan ID (UUID)

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

Option 1
Option 2

deployment_config_id

string<uuid>

required

UUID of the deployment config for the plan's default slot (slot 1), used by every player not assigned to an extra slot. Required unless the plan's slot assignments cover every player and slot_deployment_configs is supplied.

agent_config_id

string<uuid>

build_id

string<uuid>

UUID of a build from Build Storage for the default slot. Only works with build-storage deployment configs, and requires deployment_config_id.

slot_deployment_configs

object

Per-slot deployment configs for cross-platform test plans, keyed by slot index ("2", "3", and so on; see the plan's slots). The key "1" addresses the default slot and cannot be combined with deployment_config_id/build_id. Every slot used by the plan's player assignments needs an entry. Private device configs are allowed, but every player on a private device needs its own device; if the configs of a test cannot give each of its players a distinct device, the request returns a 400 error.

Show child attributes

additional_tags

string[]

render_templates

boolean

default:false

template_data

object

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.

Show child attributes

run_on_all_configured_devices

boolean

default:false

Response

Run queued

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.

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.

Show child attributes

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.

Show child attributes

device_runs

object[]

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

Show child attributes

Overview

Runs

Jobs

Bugs

Artifacts

Knowledge

Tests

Test Folders

Shared Steps

Test Plans

Configs

Builds

Start Test Plan Run

Path Parameters

Request Body

Response

Authorizations

Path Parameters

Body

Response

​Path Parameters

​Request Body

​Response

Authorizations

Path Parameters

Body

Response

Path Parameters

Request Body

Response