Skip to main content
POST
/
test-plans
/
{testPlanId}
/
runs
curl -X POST "https://nunu.ai/api/v1/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"]
  }'

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

Documentation Index

Fetch the complete documentation index at: https://api-docs.nunu.ai/llms.txt

Use this file to discover all available pages before exploring further.

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. 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
required
UUID of the deployment configuration to use for every test in the plan.
​
agent_config_id
string
UUID of an agent configuration applied to every test in the plan.
​
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
Test execution overrides — same shape as options on Start a Run (min_time_seconds, max_time_seconds, performance_monitoring, mobile_auto_grant_permissions, mobile_geolocation, mobile_gpslocation).

​
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
On failure, returns { "error": "<message>" } with an appropriate HTTP status. 
curl -X POST "https://nunu.ai/api/v1/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"]
  }'

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

Authorizations

​
X-Api-Key
string
header
required

API key for authentication

Path Parameters

​
testPlanId
string<uuid>
required

Test plan ID (UUID)

Body

application/json
​
deployment_config_id
string<uuid>
required
​
agent_config_id
string<uuid>
​
additional_tags
string[]
​
render_templates
boolean
default:false
​
template_data
object
​
options
object

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.

​
message
string

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