@lxgicstudios/api-rate

Test and measure API rate limits. Send increasing request bursts, detect when throttling kicks in, and show requests/second before 429 along with retry-after values and rate limit headers.

Install

npm install -g @lxgicstudios/api-rate

Or run directly:

npx @lxgicstudios/api-rate https://api.example.com/endpoint

Usage

# Basic rate limit test
api-rate https://api.example.com/endpoint

# Custom ramp-up pattern
api-rate https://api.example.com --ramp 1,5,10,50,100

# Set test duration
api-rate https://api.example.com --duration 60s

# Add authentication headers
api-rate https://api.example.com -H "Authorization: Bearer your-token"

# POST requests
api-rate https://api.example.com -m POST

# JSON output for analysis
api-rate https://api.example.com --json

Features

• Zero dependencies - uses only Node.js builtins
• Sends increasing concurrent request bursts to detect rate limits
• Shows exactly when throttling kicks in (HTTP 429)
• Displays requests/second you can sustain safely
• Captures rate-limit headers (X-RateLimit-*, Retry-After)
• Warm-up request before testing starts
• Progress bar showing test advancement
• Status code distribution for each burst
• Configurable ramp-up pattern
• Configurable test duration timeout
• JSON output for automated analysis
• Colorful terminal output with clear status indicators

How It Works

1. Sends a warm-up request to verify the endpoint is reachable
2. Runs burst tests with increasing concurrency (1, 5, 10, 25, 50 by default)
3. For each burst, sends all requests concurrently and measures responses
4. Detects HTTP 429 responses and captures rate limit headers
5. Reports the maximum safe request rate before throttling

Options

| Option | Description | Default | |--------|-------------|---------| | --ramp <n,n,n> | Concurrent request counts per burst | 1,5,10,25,50 | | --duration, -d | Max test duration in seconds | 30s | | --method, -m | HTTP method | GET | | --header, -H | Add custom header (repeatable) | - | | --verbose, -v | Show detailed output | false | | --json | Output results as JSON | false | | --help, -h | Show help message | - |

License

MIT

Built by LXGIC Studios