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 new test run using a multiplayer test, a test plan, or ephemeral instructions.
Request Body
Provide exactly one of multiplayer_test_id, test_plan_id, or instructions:
multiplayer_test_id — run an existing test
test_plan_id — run an existing test plan
instructions — run an ephemeral (one-off) test without creating a test case first
UUID of the test to run. Mutually exclusive with test_plan_id and instructions.
UUID of the test plan to run. Mutually exclusive with multiplayer_test_id and instructions.
Test instructions to execute as an ephemeral (one-off) test. Mutually exclusive with multiplayer_test_id and test_plan_id.
UUID of the deployment configuration
Display name for the run. Only applies when using instructions. Defaults to "[api] ephemeral test".
UUID of an agent configuration to use. Applies to all request variants.
Tags to add to the run. When using instructions (ephemeral), "api" is automatically prepended to the provided tags.
Number of times to retry the test if it fails. Only applies when using multiplayer_test_id. Must be between 0 and 10.
Number of parallel instances to run. Only applies when using multiplayer_test_id. Must be between 1 and 10.
Enable template rendering
Key-value pairs for template variables
Test execution options Minimum test duration in seconds
Maximum test duration (timeout) in seconds
options.performance_monitoring
Enable performance data collection
options.mobile_auto_grant_permissions
Auto-grant app permissions on mobile
options.mobile_geolocation
IP geolocation proxy location (e.g., "United States", "London", "San Francisco, California (US)"). Routes device traffic through a proxy in the specified region.
options.mobile_gpslocation
GPS coordinates to report to the app. Use "auto" to automatically use coordinates matching the selected mobile_geolocation, or provide explicit coordinates: { "lat": "37.7749", "long": "-122.4194" }. Note: "auto" requires mobile_geolocation to be set.
Response
Returns 201 Created on success. The body contains the started-run data
directly (no { ok, status, message, data } envelope).
Array of job IDs created. For a single test, this contains one job. For a
test plan, this contains one job per test in the plan. Use with
Get Job Details to poll for completion.
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.
Optional status message returned for multiplayer test and test plan runs.
On failure, returns { "error": "<message>" } with an appropriate HTTP status
(400, 401, 403, 404, 500).
cURL (Test)
cURL (Ephemeral)
JavaScript
Python
curl -X POST "https://nunu.ai/api/v1/runs" \
-H "X-Api-Key: YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"multiplayer_test_id": "789e0123-e89b-12d3-a456-426614174000",
"deployment_config_id": "456e7890-e89b-12d3-a456-426614174000",
"additional_tags": ["ci", "pr-123"]
}'
201 Success (Test / Test Plan)
201 Success (Ephemeral)
404 Not Found
{
" message " : "successfully queued test!" ,
" build_id " : "f14fa698-ee3e-4a3d-935d-bdbeb874ad25" ,
" job_ids " : [
"cc6e3994-a714-4b6b-9879-0b3e53c0a3af"
]
}
Using Build Storage Builds
You can run tests against a specific build from Build Storage by providing the build_id parameter.
The build_id parameter only works with deployment configs that use Build Storage as their build source. If the deployment config uses a different build source (e.g., direct URL), the request will return a 400 error.
Example: Upload and Test
# 1. Upload a new build (see Build Storage docs)
BUILD_ID = "123e4567-e89b-12d3-a456-426614174000"
# 2. Start a test using that build
curl -X POST "https://nunu.ai/api/v1/runs" \
-H "X-Api-Key: YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"multiplayer_test_id": "789e0123-e89b-12d3-a456-426614174000",
"deployment_config_id": "456e7890-e89b-12d3-a456-426614174000",
"build_id": "123e4567-e89b-12d3-a456-426614174000",
"additional_tags": ["ci", "build-test"]
}'
Complete CI/CD Example
Here’s a complete example that starts a test and polls for completion:
JavaScript/TypeScript
Python
Shell Script
const API_TOKEN = process . env . NUNU_API_TOKEN ;
const BASE_URL = "https://nunu.ai/api/v1" ;
async function startAndWaitForTest (
testId : string ,
deploymentConfigId : string
) : Promise < any > {
// Start the test
const startResponse = await fetch ( ` ${ BASE_URL } /runs` , {
method : "POST" ,
headers : {
"X-Api-Key" : API_TOKEN ,
"Content-Type" : "application/json" ,
},
body : JSON . stringify ( {
multiplayer_test_id : testId ,
deployment_config_id : deploymentConfigId ,
} ) ,
} ) ;
const startResult = await startResponse . json () ;
if ( ! startResponse . ok) {
throw new Error ( `Failed to start test: ${ startResult . error } ` ) ;
}
const jobId = startResult . job_ids[ 0 ] ;
console . log ( `Test started with job: ${ jobId } ` ) ;
// Poll job for completion
while ( true ) {
const jobResponse = await fetch ( ` ${ BASE_URL } /jobs/ ${ jobId } ` , {
headers : { "X-Api-Key" : API_TOKEN },
} ) ;
const job = await jobResponse . json () ;
if (job . status === "COMPLETED" ) {
const result = job . runs[ 0 ] ?. result ?? "unknown" ;
console . log ( `Test completed with result: ${ result } ` ) ;
return job ;
}
console . log ( `Test still running... (status: ${ job . status } )` ) ;
await new Promise ( ( resolve ) => setTimeout (resolve , 30000 )) ;
}
}
API key for authentication
UUID of the deployment configuration
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)
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.
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.
Required range: 0 <= x <= 10
Number of parallel instances to run. Only applies when using multiplayer_test_id.
Required range: 1 <= x <= 10
Enable template rendering
Key-value pairs for template variables
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.
Optional status message returned for multiplayer test and test plan runs.