Aller au contenu principal
LoadLab

API Reference

Complete reference for the Loadlab REST API. All endpoints return JSON responses.

Base URL:https://api.loadlab.dev

Authentication

LoadLab supports two authentication methods: JWT tokens (for web app) and API keys (for CI/CD). For CI/CD integration, create an API key in Settings → API Keys.

Authorization header

Authorization: Bearer <your-api-key>
Note: API keys start with 'lt_' and should be kept secure. Never commit them to version control - use environment variables or secrets.

Projects

Manage your projects and their settings.

MethodEndpointDescriptionAuth
GET/projectsList all projectsRequired
POST/projectsCreate a new projectRequired
GET/projects/:idGet project detailsRequired
DELETE/projects/:idDelete a projectRequired

Scenarios

Create and manage load test scenarios.

MethodEndpointDescriptionAuth
GET/projects/:projectId/scenariosList scenariosRequired
POST/projects/:projectId/scenariosCreate a scenarioRequired
GET/projects/:projectId/scenarios/:idGet scenario detailsRequired
DELETE/projects/:projectId/scenarios/:idDelete a scenarioRequired

Request body

POST /projects/:projectId/scenarios
{
  "name": "Homepage load test",
  "vus": 100,
  "durationSeconds": 300,
  "mode": "DURATION",  // or "BURST"
  "environmentId": "env_xxx",
  "endpoints": [
    { "endpointId": "ep_xxx", "weight": 3 }
  ]
}

Endpoints

Define API endpoints to include in your tests.

MethodEndpointDescriptionAuth
GET/projects/:projectId/endpointsList endpointsRequired
POST/projects/:projectId/endpointsCreate an endpointRequired
DELETE/projects/:projectId/endpoints/:idDelete an endpointRequired

Request body

POST /projects/:projectId/endpoints
{
  "method": "GET",  // GET, POST, PUT, PATCH, DELETE
  "path": "/api/users",
  "name": "List users"  // optional
}

Environments

Configure target environments with base URLs and headers.

MethodEndpointDescriptionAuth
GET/projects/:projectId/environmentsList environmentsRequired
POST/projects/:projectId/environmentsCreate an environmentRequired
DELETE/projects/:projectId/environments/:idDelete an environmentRequired

Request body

POST /projects/:projectId/environments
{
  "name": "Production",
  "baseUrl": "https://api.example.com",
  "headers": {
    "Authorization": "Bearer xxx"
  }
}

Runs

Create, monitor, and retrieve test run results.

MethodEndpointDescriptionAuth
GET/runsList all runsRequired
POST/runsCreate and enqueue a new runRequired
GET/runs/:idGet run details with metricsRequired
GET/runs/:id/streamSSE stream for live metricsRequired
POST/runs/:id/cancelCancel a running testRequired
POST/projects/:projectId/scenarios/:scenarioId/runTrigger a run for a scenarioRequired

Response body

GET /runs/:id
{
  "id": "run_xxx",
  "status": "COMPLETED",
  "p95LatencyMs": 145,
  "p99LatencyMs": 289,
  "throughputRps": 523,
  "errorRate": 0.002,
  "totalRequests": 15690
}
SSE Stream: Use the /runs/:id/stream endpoint to receive real-time metrics via Server-Sent Events (SSE).

Baselines

Set and retrieve baseline runs for comparison.

MethodEndpointDescriptionAuth
GET/runs/:runId/baselineGet baseline for a runRequired
POST/projects/:projectId/scenarios/:scenarioId/baselineSet baseline runRequired

Performance Badge

Embed a performance badge in your README or documentation.

MethodEndpointDescriptionAuth
GET/badge/perfGet performance badge SVGOptional

Markdown

![Performance](https://api.loadlab.dev/badge/perf?project=your-project-key)
Badge examples:
perf | PASSperf | WARNperf | FAIL

With scenario filter

![Performance](https://api.loadlab.dev/badge/perf?project=my-project&scenario=checkout)

CI/CD Integration

Integrate LoadLab into your CI/CD pipeline to automatically run load tests on every deployment. Use API keys for authentication (create them in Settings → API Keys).

MethodEndpointDescriptionAuth
POST/ci/runTrigger a load test runRequired
GET/ci/runs/:idGet run results with verdictRequired
Authentication: CI endpoints use API keys instead of JWT tokens. Create an API key in your project settings and use it as a Bearer token.

Trigger a Run

Request

POST /ci/run
Authorization: Bearer lt_xxxxxxxxxxxx

{
  "projectKey": "my-project",
  "scenarioKey": "checkout-flow",
  "branch": "feature/new-api",
  "commitSha": "abc123",
  "baseBranch": "main"
}

Response

{
  "runId": "run_xxx",
  "status": "PENDING"
}

Get Run Results

Response

GET /ci/runs/:id

{
  "id": "run_xxx",
  "status": "COMPLETED",
  "verdict": "PASS",              // PASS, WARN, or FAIL
  "verdictReasons": [
    "All metrics within acceptable thresholds"
  ],
  "metrics": {
    "p95LatencyMs": 145,
    "p99LatencyMs": 289,
    "errorRate": 0.002,
    "throughputRps": 523,
    "totalRequests": 15690
  },
  "baseline": {                   // If baseline exists
    "id": "run_yyy",
    "metrics": { ... }
  },
  "diff": {                       // Comparison with baseline
    "p95LatencyMs": -5.2,
    "errorRate": 0.1
  }
}

Verdict Criteria

VerdictCondition
PASSError rate < 1% and P95 within 10% of baseline
WARNError rate 1-5% or P95 regressed 10-25% vs baseline
FAILError rate > 5% or P95 regressed > 25% vs baseline

GitHub Actions Example

.github/workflows/load-test.yml

name: Load Test
on:
  push:
    branches: [main]
  pull_request:

jobs:
  load-test:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger LoadLab test
        id: trigger
        run: |
          RESPONSE=$(curl -s -X POST https://api.loadlab.dev/ci/run \
            -H "Authorization: Bearer ${{ secrets.LOADLAB_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{
              "projectKey": "my-project",
              "scenarioKey": "api-stress-test",
              "branch": "${{ github.ref_name }}",
              "commitSha": "${{ github.sha }}"
            }')
          echo "run_id=$(echo $RESPONSE | jq -r '.runId')" >> $GITHUB_OUTPUT

      - name: Wait for results
        run: |
          while true; do
            RESULT=$(curl -s \
              -H "Authorization: Bearer ${{ secrets.LOADLAB_API_KEY }}" \
              https://api.loadlab.dev/ci/runs/${{ steps.trigger.outputs.run_id }})

            STATUS=$(echo $RESULT | jq -r '.status')

            if [[ "$STATUS" == "COMPLETED" || "$STATUS" == "FAILED" ]]; then
              VERDICT=$(echo $RESULT | jq -r '.verdict')
              echo "## Load Test Results" >> $GITHUB_STEP_SUMMARY
              echo "**Verdict:** $VERDICT" >> $GITHUB_STEP_SUMMARY
              echo $RESULT | jq -r '.verdictReasons[]' >> $GITHUB_STEP_SUMMARY

              if [[ "$VERDICT" == "FAIL" ]]; then
                echo "::error::Performance regression detected!"
                exit 1
              fi
              break
            fi

            echo "Status: $STATUS - waiting..."
            sleep 10
          done
Tip: Add LOADLAB_API_KEY to your repository secrets. You can find your project key and scenario key in the scenario details page.
API Reference - Loadlab | Loadlab