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" }
    }
  }'

{
  "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" }
    }
  }'

{
  "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

testPlanId

string

required

The test plan ID (UUID)

Request Body

deployment_config_id

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.

agent_config_id

string

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

build_id

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.

slot_deployment_configs

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

slot_deployment_configs.{index}.deployment_config_id

string

required

Deployment config to use for this slot.

slot_deployment_configs.{index}.build_id

string

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

additional_tags

string[]

Tags appended to every resulting run.

render_templates

boolean

default:"false"

Enable Handlebars-style templating in test step bodies.

template_data

object

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

options

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).

Response

Returns 201 Created on success. 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.

job_ids

string[]

required

Job IDs created for each test in the plan

test_plan_execution_id

string

ID of the test plan execution

slot_build_ids

object

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

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" }
    }
  }'

{
  "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

Response

Run queued

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.

Show child attributes

message

string

Optional status message returned for multiplayer test and test plan runs.

Delete Test Plan List Test Plan Executions

​Path Parameters

​Request Body

​Response

Authorizations

Path Parameters

Body

Response

Path Parameters

Request Body

Response