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",
    "extra_build_ids": { "1": "123e4567-e89b-12d3-a456-426614174001" },
    "slot_deployment_configs": {
      "2": {
        "deployment_config_id": "9a1b2c3d-4e5f-6789-a0b1-c2d3e4f5a6b7",
        "extra_build_ids": { "2": "123e4567-e89b-12d3-a456-426614174002" }
      }
    }
  }'

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",
    "extra_build_ids": { "1": "123e4567-e89b-12d3-a456-426614174001" },
    "slot_deployment_configs": {
      "2": {
        "deployment_config_id": "9a1b2c3d-4e5f-6789-a0b1-c2d3e4f5a6b7",
        "extra_build_ids": { "2": "123e4567-e89b-12d3-a456-426614174002" }
      }
    }
  }'

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

Nonblank build ID for the default slot. Requires deployment_config_id. The selected config determines its meaning: a Build Storage UUID or the opaque ID returned by an external platform. Get the ID with List Builds. Omit it to use the config’s saved or default selection.

object

Optional Build Storage UUIDs for extra apps in the top-level deployment_config_id, keyed by extra app number ("1", "2", or "3"). These numbers refer to apps within a deployment config; they are independent of the plan’s slot indexes.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. When slot "1" is supplied instead, use extra_build_ids inside that slot entry.

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-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 nonblank build ID for this slot’s main app. Its deployment config determines its meaning: a Build Storage UUID or an opaque ID from an external platform. Omit it to use that config’s saved or default selection.

object

Optional extra-app Build Storage build IDs for this slot’s deployment config, keyed by extra app number ("1"–"3"). These numbers are independent of the slot index. Omitted entries preserve saved selections; {} is a no-op. Each explicit build must belong to the project, be ready, match the extra app platform, and use a Build Storage source. Explicit IDs take precedence over required_tags.

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",
    "extra_build_ids": { "1": "123e4567-e89b-12d3-a456-426614174001" },
    "slot_deployment_configs": {
      "2": {
        "deployment_config_id": "9a1b2c3d-4e5f-6789-a0b1-c2d3e4f5a6b7",
        "extra_build_ids": { "2": "123e4567-e89b-12d3-a456-426614174002" }
      }
    }
  }'

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

Nonblank main-app build ID for the default slot, interpreted by the selected deployment config's source: a UUID for Build Storage or an opaque external-platform ID. Requires deployment_config_id. 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.

Show child attributes

Example:

{
  "1": "33333333-3333-4333-8333-333333333333"
}

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. Extra app numbers in each entry are local to that deployment config, not slot numbers.

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

Minions

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