Skip to main content
POST
/
runs
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"]
  }'
{
  "message": "successfully queued test!",
  "build_id": "f14fa698-ee3e-4a3d-935d-bdbeb874ad25",
  "job_ids": [
    "cc6e3994-a714-4b6b-9879-0b3e53c0a3af"
  ]
}

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
multiplayer_test_id
string
UUID of the test to run. Mutually exclusive with test_plan_id and instructions.
test_plan_id
string
UUID of the test plan to run. Mutually exclusive with multiplayer_test_id and instructions.
instructions
string
Test instructions to execute as an ephemeral (one-off) test. Mutually exclusive with multiplayer_test_id and test_plan_id.
deployment_config_id
string
required
UUID of the deployment configuration
name
string
Display name for the run. Only applies when using instructions. Defaults to "[api] ephemeral test".
build_id
string
UUID of a build from Build Storage to use for this run. See Using Build Storage Builds below.
agent_config_id
string
UUID of an agent configuration to use. Applies to all request variants.
additional_tags
string[]
Tags to add to the run. When using instructions (ephemeral), "api" is automatically prepended to the provided tags.
retries
integer
default:"0"
Number of times to retry the test if it fails. Only applies when using multiplayer_test_id. Must be between 0 and 10.
instances
integer
default:"1"
Number of parallel instances to run. Only applies when using multiplayer_test_id. Must be between 1 and 10.
render_templates
boolean
default:"false"
Enable template rendering
template_data
object
Key-value pairs for template variables
options
object
Test execution options

Response

Returns 201 Created on success. The body contains the started-run data directly (no { ok, status, message, data } envelope).
job_ids
string[]
required
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
string
Build ID used for the run. Returned for multiplayer test and test plan runs.
test_id
string
UUID of the created ephemeral test. Only returned for ephemeral (instructions) runs.
message
string
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 -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"]
  }'
{
  "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:
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));
  }
}

Authorizations

X-Api-Key
string
header
required

API key for authentication

Body

application/json
deployment_config_id
string
required

UUID of the deployment configuration

multiplayer_test_id
string

UUID of the test to run (provide this OR test_plan_id OR instructions)

test_plan_id
string

UUID of the test plan to run (provide this OR multiplayer_test_id OR instructions)

instructions
string

Test instructions to execute as an ephemeral (one-off) test. Mutually exclusive with multiplayer_test_id and test_plan_id.

build_id
string<uuid>

UUID of a build from Build Storage to use for this run. Only works with build-storage deployment configs.

name
string

Display name for the run. Only applies when using instructions. Defaults to '[api] ephemeral test'.

agent_config_id
string<uuid>

UUID of an agent configuration to use

additional_tags
string[]

Tags to add to the run. When using instructions (ephemeral), the tag 'api' is automatically prepended.

retries
integer
default:0

Number of times to retry the test if it fails. Only applies when using multiplayer_test_id.

Required range: 0 <= x <= 10
instances
integer
default:1

Number of parallel instances to run. Only applies when using multiplayer_test_id.

Required range: 1 <= x <= 10
render_templates
boolean
default:false

Enable template rendering

template_data
object

Key-value pairs for template variables

options
object

Response

Run started successfully

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.