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": 201,
  "message": "queued",
  "data": {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "multiplayer_run_id": "1g20ccrgksb"
  }
}
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
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": 201,
  "message": "queued",
  "data": {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "multiplayer_run_id": "1g20ccrgksb"
  }
}

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 runId = startResult.data.multiplayer_run_id;
  console.log(`Test started: ${runId}`);

  // Poll for completion
  while (true) {
    const detailsResponse = await fetch(`${BASE_URL}/runs/${runId}`, {
      headers: { "X-Api-Key": API_TOKEN },
    });

    const details = await detailsResponse.json();

    if (details.state === "completed") {
      console.log(`Test completed with result: ${details.result}`);
      return details;
    }

    console.log(`Test still running... (state: ${details.state})`);
    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)

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