API Reference

Rate & Load Tester

Execute controlled rate and load tests against HTTP endpoints with reporting

Run controlled load and rate tests against your HTTP endpoints with configurable concurrency, duration, and request patterns. The Rate Tester measures response times, error rates, and throughput percentiles (p95, p99), giving you the performance data needed to capacity plan, set SLAs, and catch regressions before production.

configurable RPSpercentile metricsscenario builderexecution history

Endpoint

POST /v1/rate/test

Authentication: Include your API key in the X-API-Key header with every request. All requests go through the API gateway which handles authentication, rate limiting, and usage tracking.

Open Swagger UI (interactive docs)

Request

{
  "targetUrl": "https://api.example.com/health",
  "requestsPerSecond": 50,
  "durationSeconds": 30,
  "method": "GET"
}

Request Fields

Field	Type	Description
`targetUrl`	`string`	Field value
`requestsPerSecond`	`integer`	Field value
`durationSeconds`	`integer`	Field value
`method`	`string`	Field value

Response

{
  "executionId": "exec_abc123",
  "status": "COMPLETED",
  "totalRequests": 1500,
  "successCount": 1487,
  "errorCount": 13,
  "avgResponseMs": 142,
  "p95ResponseMs": 310,
  "p99ResponseMs": 520,
  "requestsPerSecond": 49.8
}

Response Fields

Field	Type	Description
`executionId`	`string`	Field value
`status`	`string`	Field value
`totalRequests`	`integer`	Field value
`successCount`	`integer`	Field value
`errorCount`	`integer`	Field value
`avgResponseMs`	`integer`	Field value
`p95ResponseMs`	`integer`	Field value
`p99ResponseMs`	`integer`	Field value
`requestsPerSecond`	`number`	Field value

Error Codes

Status	Meaning
`200`	Request completed successfully
`400`	Bad request — invalid or missing parameters
`401`	Missing or invalid `X-API-Key` header
`429`	Rate limit exceeded — check `Retry-After` header
`500`	Internal server error

Common Error Scenarios

400 Invalid URL

Request that triggers this:

{"url": "not a url", "requestsPerSecond": 10}

Error response:

{"type": "/problems/validation-error", "title": "Invalid URL", "status": 400, "detail": "'not a url' is not a valid URL"}

How to fix: Provide a valid HTTP or HTTPS URL with proper formatting.

429 Rate limit on target

Request that triggers this:

{"url": "https://protected-api.example.com", "requestsPerSecond": 100}

Error response:

{"type": "/problems/rate-limit", "title": "Too Many Requests to Target", "status": 429, "detail": "Target returned 429 - it rate limits requests"}

How to fix: Reduce requestsPerSecond or implement backoff strategy. Check target API rate limits and adjust test parameters.

Code Examples

curl -X POST /v1/rate/test \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
  "targetUrl": "https://api.example.com/health",
  "requestsPerSecond": 50,
  "durationSeconds": 30,
  "method": "GET"
}'

// Node.js (18+) or modern browser
const response = await fetch("/v1/rate/test", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "targetUrl": "https://api.example.com/health",
    "requestsPerSecond": 50,
    "durationSeconds": 30,
    "method": "GET"
}),
});

const data = await response.json();
console.log(response.status, data);

import requests

response = requests.post(
    "/v1/rate/test",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
    "targetUrl": "https://api.example.com/health",
    "requestsPerSecond": 50,
    "durationSeconds": 30,
    "method": "GET"
},
)

print(response.status_code)
print(response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	body := strings.NewReader(`{
  "targetUrl": "https://api.example.com/health",
  "requestsPerSecond": 50,
  "durationSeconds": 30,
  "method": "GET"
}`)
	req, _ := http.NewRequest("POST", "/v1/rate/test", body)
	req.Header.Set("X-API-Key", "YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	data, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode)
	fmt.Println(string(data))
}

{
  "name": "rate_test",
  "description": "Execute controlled rate and load tests against HTTP endpoints with reporting",
  "inputSchema": {
    "type": "object",
    "properties": {
      "api_key": {"type": "string", "description": "Your Orovai API key"},
      "request": {"type": "object", "description": "Request body"}
    },
    "required": ["api_key", "request"]
  },
  "endpoint": "/v1/rate/test",
  "method": "POST",
  "headers": {
    "X-API-Key": "{{api_key}}",
    "Content-Type": "application/json"
  }
}

API Reference