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"]
  }'
{
  "ok": true,
  "status": 200,
  "message": "successfully queued test!",
  "data": {
    "message": "successfully queued test!",
    "build_id": "f14fa698-ee3e-4a3d-935d-bdbeb874ad25",
    "job_ids": [
      "cc6e3994-a714-4b6b-9879-0b3e53c0a3af"
    ]
  }
}
Permission Required: project:operate-runs
Start a new test run using either a multiplayer test or a test plan.

Request Body

Provide either multiplayer_test_id or test_plan_id, not both.
multiplayer_test_id
string
UUID of the test to run. Required if test_plan_id is not provided.
test_plan_id
string
UUID of the test plan to run. Required if multiplayer_test_id is not provided.
deployment_config_id
string
required
UUID of the deployment configuration
build_id
string
UUID of a build from Build Storage to use for this run. See Using Build Storage Builds below.
additional_tags
string[]
Tags to add to the run
render_templates
boolean
default:"false"
Enable template rendering
template_data
object
Key-value pairs for template variables
options
object
Test execution options

Response

ok
boolean
required
Whether the request succeeded
status
integer
required
HTTP status code
message
string
required
Status message (e.g., queued)
data
object
required
Response data
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"]
  }'
{
  "ok": true,
  "status": 200,
  "message": "successfully queued test!",
  "data": {
    "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 (!startResult.ok) {
    throw new Error(`Failed to start test: ${startResult.error}`);
  }

  const jobId = startResult.data.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)

test_plan_id
string

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

build_id
string<uuid>

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

additional_tags
string[]

Tags to add to the run

render_templates
boolean
default:false

Enable template rendering

template_data
object

Key-value pairs for template variables

options
object

Response

Run started successfully

ok
boolean
status
integer
message
string
data
object