Run Tests

Trigger one or more test plans programmatically.

POST https://test-lab.ai/api/v1/run

Authentication

Authorization: Bearer tl_xxxxx

Request Body

Field	Type	Required	Description
`testPlanId`	number	One of these	Run a single test plan
`testPlanIds`	number[] \| string	One of these	Run multiple test plans
`projectId`	number	One of these	Run all test plans for a project
`testType`	string	No	`"quickTest"` or `"deepTest"` (default: plan's default)
`buildId`	string	No	CI build/commit identifier (max 100 chars)
`cookies`	array	No	Authentication cookies to inject (see below)

Exactly one of testPlanId, testPlanIds, or projectId must be provided.

Field	Type	Required	Description
`name`	string	Yes	Cookie name
`value`	string	Yes	Cookie value
`domain`	string	Yes	Domain (e.g. `.example.com`)

Cookies can also be configured at the project or test plan level in the dashboard. Runtime cookies override stored cookies.

Examples

Single Test Plan

curl -X POST https://test-lab.ai/api/v1/run \
  -H "Authorization: Bearer tl_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "testPlanId": YOUR_TEST_PLAN_ID,
    "testType": "quickTest"
  }'

Response:

{
  "jobId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "running",
  "testPlanId": YOUR_TEST_PLAN_ID,
  "testType": "quickTest"
}

Multiple Test Plans

Using an array:

curl -X POST https://test-lab.ai/api/v1/run \
  -H "Authorization: Bearer tl_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "testPlanIds": [ID_1, ID_2, ID_3],
    "testType": "deepTest"
  }'

Using a comma-separated string:

curl -X POST https://test-lab.ai/api/v1/run \
  -H "Authorization: Bearer tl_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "testPlanIds": "ID_1,ID_2,ID_3"
  }'

Response (multiple plans):

{
  "jobs": [
    {
      "jobId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "status": "running",
      "testPlanId": YOUR_TEST_PLAN_ID,
      "testPlanName": "Login Flow",
      "testType": "deepTest"
    },
    {
      "jobId": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
      "status": "running",
      "testPlanId": ID_2,
      "testPlanName": "Signup Flow",
      "testType": "deepTest"
    }
  ],
  "triggered": 2,
  "failed": 0
}

All Plans for a Project

curl -X POST https://test-lab.ai/api/v1/run \
  -H "Authorization: Bearer tl_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": YOUR_PROJECT_ID
  }'

With Build ID (CI Integration)

curl -X POST https://test-lab.ai/api/v1/run \
  -H "Authorization: Bearer tl_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "testPlanId": YOUR_TEST_PLAN_ID,
    "buildId": "abc123"
  }'

Response with buildId:

With Authentication Cookies

curl -X POST https://test-lab.ai/api/v1/run \
  -H "Authorization: Bearer tl_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "testPlanId": YOUR_TEST_PLAN_ID,
    "cookies": [
      { "name": "session", "value": "abc123xyz", "domain": ".myapp.com" }
    ]
  }'

Response:

{
  "jobId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "running",
  "testPlanId": YOUR_TEST_PLAN_ID,
  "testType": "quickTest",
  "buildId": "abc123"
}

Response Fields

Single Plan Response

Field	Type	Description
`jobId`	string	UUID of the created job
`status`	string	`"running"`, `"queued"`, or `"pending"`
`testPlanId`	number	ID of the test plan
`testType`	string	Test mode used
`buildId`	string	Build ID if provided

Multiple Plans Response

Field	Type	Description
`jobs`	array	Array of job objects
`jobs[].jobId`	string	UUID of each job
`jobs[].status`	string	Status of each job
`jobs[].testPlanId`	number	Test plan ID
`jobs[].testPlanName`	string	Test plan name
`jobs[].testType`	string	Test mode
`jobs[].error`	string	Error if job failed to start
`triggered`	number	Count of successfully triggered jobs
`failed`	number	Count of failed jobs
`buildId`	string	Build ID if provided

Error Responses

Invalid API Key

{
  "error": "Invalid API key"
}

Status: 401

Insufficient Credits

{
  "error": "Insufficient credits. Please top up to continue running tests."
}

Status: 402

Test Plan Not Found

{
  "error": "No test plans found"
}

Status: 404

Invalid Parameters

{
  "error": "One of testPlanId, testPlanIds, or projectId is required"
}

Status: 400

Code Examples

JavaScript/Node.js

const response = await fetch('https://test-lab.ai/api/v1/run', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.TESTLAB_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    testPlanId: YOUR_TEST_PLAN_ID,
    testType: 'quickTest',
    buildId: process.env.GITHUB_SHA,
  }),
});

const data = await response.json();
console.log('Job started:', data.jobId);

Python

import requests
import os

response = requests.post(
    'https://test-lab.ai/api/v1/run',
    headers={
        'Authorization': f'Bearer {os.environ["TESTLAB_API_KEY"]}',
        'Content-Type': 'application/json',
    },
    json={
        'testPlanId': YOUR_TEST_PLAN_ID,
        'testType': 'quickTest',
        'buildId': os.environ.get('GITHUB_SHA'),
    }
)

data = response.json()
print(f'Job started: {data["jobId"]}')

Run Tests

Run Tests

Authentication

Request Body

Examples

Single Test Plan

Multiple Test Plans

All Plans for a Project

With Build ID (CI Integration)

With Authentication Cookies

Response Fields

Single Plan Response

Multiple Plans Response

Error Responses

Invalid API Key

Insufficient Credits

Test Plan Not Found

Invalid Parameters

Code Examples

JavaScript/Node.js

Python

Next Steps

Set Up Webhooks

CI Integration

On this page