Load Test Your APIs Safely

The Rate Test service lets you send controlled HTTP traffic to your endpoints and measure latency percentiles, error rates, and throughput. Built-in safety guardrails prevent accidental DDoS of your own (or anyone else's) infrastructure.

Safety first: Rate Test enforces a maximum of 100 RPS per test, a 5-minute duration cap, and requires target ownership verification. You can only load-test endpoints you own.

What You'll Learn

  • How to register a target endpoint for load testing
  • How to create a scenario (10 RPS for 30 seconds) and execute it
  • How to read latency percentiles (p50, p95, p99) from the results

Prerequisites

Before you start: You need an API key. Follow the Platform Quick Start to get one.

  • curl (or any HTTP client)
  • A valid API key in the X-API-KEY header
  • An endpoint you own that you want to load-test

Step 1: Create a Target

Register the endpoint you want to test. The service verifies ownership by checking for a verification token at a well-known path.

bash
curl -X POST /api/rate-test/targets \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your-api-key" \
  -d '{
    "baseUrl": "https://api.mycompany.com",
    "verificationMethod": "DNS_TXT"
  }'
Response — 201 Created
{
  "status": "OK",
  "data": {
    "targetId": "tgt_load_1a2b3c",
    "baseUrl": "https://api.mycompany.com",
    "verified": true,
    "createdAt": "2026-03-26T17:30:00Z"
  }
}

Step 2: Create a Scenario

Define the load pattern: request rate, duration, HTTP method, and path. This example sends 10 requests per second for 30 seconds.

bash
curl -X POST /api/rate-test/scenarios \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your-api-key" \
  -d '{
    "targetId": "tgt_load_1a2b3c",
    "name": "Health check baseline",
    "requestsPerSecond": 10,
    "durationSeconds": 30,
    "method": "GET",
    "path": "/health",
    "expectedStatus": 200
  }'
python
import requests

resp = requests.post(
    "/api/rate-test/scenarios",
    headers={"X-API-KEY": "your-api-key"},
    json={
        "targetId": "tgt_load_1a2b3c",
        "name": "Health check baseline",
        "requestsPerSecond": 10,
        "durationSeconds": 30,
        "method": "GET",
        "path": "/health",
        "expectedStatus": 200
    }
)
scenario = resp.json()["data"]
print(f"Scenario ID: {scenario['scenarioId']}")
Response — 201 Created
{
  "status": "OK",
  "data": {
    "scenarioId": "scn_4d5e6f",
    "name": "Health check baseline",
    "requestsPerSecond": 10,
    "durationSeconds": 30,
    "totalRequests": 300
  }
}

Step 3: Execute the Test

Start the load test. The execution runs asynchronously and you can poll for results.

bash
curl -X POST "/api/rate-test/scenarios/scn_4d5e6f/execute" \
  -H "X-API-KEY: your-api-key"
Response — 202 Accepted
{
  "status": "OK",
  "data": {
    "executionId": "run_7g8h9i",
    "state": "RUNNING",
    "startedAt": "2026-03-26T17:35:00Z",
    "estimatedEndAt": "2026-03-26T17:35:30Z"
  }
}

Step 4: View Results with Latency Percentiles

Once the test completes, fetch the results. The key metrics are latency percentiles, throughput, and error rate.

bash
curl -X GET "/api/rate-test/executions/run_7g8h9i" \
  -H "X-API-KEY: your-api-key"
Response — 200 OK
{
  "status": "OK",
  "data": {
    "executionId": "run_7g8h9i",
    "state": "COMPLETED",
    "totalRequests": 300,
    "successCount": 298,
    "errorCount": 2,
    "errorRate": 0.0067,
    "throughputRps": 9.93,
    "latency": {
      "p50": 42,
      "p75": 58,
      "p90": 89,
      "p95": 124,
      "p99": 312,
      "max": 1847,
      "mean": 56
    },
    "durationSeconds": 30.2,
    "completedAt": "2026-03-26T17:35:30Z"
  }
}

Key takeaways from these results:

  • p50 = 42ms: Half of all requests completed in under 42ms — solid baseline.
  • p99 = 312ms: Only 1% of requests took longer than 312ms — check if that outlier is acceptable.
  • Error rate 0.67%: Two failures out of 300 requests. Investigate the error responses for root cause.

Integration Tips

  • CI/CD gates: Run a baseline scenario after each deployment. Fail the pipeline if p95 exceeds your SLA threshold.
  • Ramp-up patterns: Use "rampUp": true to gradually increase from 0 to target RPS over the first 25% of the duration.
  • Custom headers: Pass authentication headers in the scenario config to test authenticated endpoints.
  • Compare runs: Use the /executions/compare?ids=run_a,run_b endpoint to diff two test runs side-by-side.

Next Steps