API Limits
Rate Limits
VulnRadar applies rate limits at two levels: per-IP limits on auth endpoints and per-user/per-key daily quotas on scan endpoints.
- Daily Quota
- Per Key
- Burst Limit
- Per IP
- On Every Response
- Headers
Overview
Two separate limit systems protect the platform. They are enforced in different places and behave differently on overflow.
- Named rate limits:
lib/rate-limiting/rate-limit.ts. Sliding window in therate_limitstable. Each one names what it is keyed on, and it is not always the IP: the pre-login auth endpoints (signup, login, forgot-password) key on IP because there is no user yet, while almost everything after sign-in keys on the user id, so rotating source addresses does not reset it. See the table below for which is which. - Per-plan daily quotas:
lib/rate-limiting/daily-limits.ts. Tracks usage per user (session auth) or per API key (Bearer auth) for a 24-hour window. Limits come fromlib/billing/catalog.ts.
Daily Quotas by Plan
Two separate counters: scans/day enforced for session-authenticated users, and API requests/day enforced for Bearer-authenticated API keys.
| Plan | Scans / day (session auth) | API requests / day (Bearer) |
|---|---|---|
| Free | 25 | 25 |
| Core | 100 | 100 |
| Pro | 150 | 5,000 |
| Elite | 500 | Unlimited |
Named Rate Limits
Every named limit below is admin-editable and configured in lib/config/config-values.ts as a CONFIG_RATE_LIMIT_*_ATTEMPTS + _WINDOW_MINUTES pair (the map from limit name to registry keys is CONFIGURABLE_LIMITS in lib/rate-limiting/rate-limit.ts). The window is converted to seconds when the limit is resolved. Every number in the table below is therefore a shipped default, not a constant: the instance you are calling may have been tuned.
The Keyed on column is the part that matters when you are sizing a client or reasoning about abuse. A limit keyed on the user is not reset by changing IP; a limit keyed on the IP is shared by everyone behind the same NAT or proxy. This table previously listed IP for all of them, and omitted nine limits that are enforced.
| Endpoint | Max attempts | Window (min) | Keyed on |
|---|---|---|---|
| POST /api/v3/auth/login | 5 | 15 | IP |
| POST /api/v3/auth/signup | 3 | 60 | IP |
| POST /api/v3/auth/forgot-password | 3 | 10 | IP |
| POST /api/v3/auth/signup (per email address) | 5 | 60 | email address |
| POST /api/v3/auth/forgot-password (per email address) | 3 | 60 | email address |
| POST /api/v3/domains | 20 | 60 | user |
| POST /api/v3/domains/{id}/verify | 30 | 60 | user |
| POST /api/v3/auth/2fa/verify | 5 | 5 | user + IP, and user alone |
| API requests (on rate-limited routes) | 100 | 60 | IP or user, per route |
| POST /api/v3/scan (and friends) | 100 | 60 | user |
| POST /api/v3/scan/bulk | 10 | 60 | user |
| POST /api/v3/browser/sessions | 20 | 60 | user |
| POST /api/v3/ai/chat | 60 | 60 | user |
| POST /api/v3/scan/verify and /api/v3/scan/verify-batch (one shared bucket) | 20 | 60 | user |
| POST /api/v3/history/{id}/summary | 20 | 60 | user |
| Admin PATCH re-auth | 10 | 15 | user + IP |
| POST /api/v3/billing/verify | 5 | 5 | user |
| POST /api/v3/teams/members (invites) | 20 | 60 | user |
| /api/v3/scan/tags | 60 | 60 | user |
| GET /api/v3/public-scans | 60 | 1 | IP |
Rate Limit Headers
A 429 from a scan endpoint carries the full set below. Whether Retry-After comes with it depends on which limit you hit: an API key’s own daily cap adds it, the account quota does not, because that one always resets at midnight UTC. On a successful response the coverage is narrower than you might expect: POST /scan and POST /scan/crawl send Limit, Remaining and Reset only when the caller used a Bearer key; POST /scan/bulk on the session path sends all five. A session-authenticated single scan, and every /history or /scan/status read, sends none. If you are calling with a session cookie, track your own count rather than waiting for a header that will not arrive.
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 150
X-RateLimit-Remaining: 0
X-RateLimit-Used: 150
X-RateLimit-Policy: daily
X-RateLimit-Reset: 2026-03-12T00:00:00.000ZX-RateLimit-LimitYour effective daily limit for this auth contextX-RateLimit-RemainingUnits remaining in the current windowX-RateLimit-UsedUnits consumed in the current windowX-RateLimit-PolicyAlways "daily": distinguishes this from any future per-minute policiesX-RateLimit-ResetISO 8601 timestamp at which the counter resetsRetry-AfterSeconds to wait (only on 429 responses)Handling 429 Responses
When you exceed your quota, the API returns 429 with a structured body.
429 response
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 43200
{
"error": "Daily scan limit reached. Resets at 2026-03-12T00:00:00Z.",
"limit": 150,
"used": 150,
"remaining": 0,
"resets_at": "2026-03-12T00:00:00Z"
}Exponential backoff (TypeScript)
async function scanWithRetry(url: string, maxRetries = 3) {
for (let attempt = 0; attempt < maxRetries; attempt++) {
const response = await fetch('https://vulnradar.dev/api/v3/scan', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({ url }),
});
if (response.status === 429) {
const retryAfter = Number(response.headers.get('Retry-After') ?? '60');
const wait = Math.min(retryAfter * 1000, 2 ** attempt * 1000);
console.log(`Rate limited. Waiting ${wait / 1000}s before retry.`);
await new Promise((r) => setTimeout(r, wait));
continue;
}
return response.json();
}
throw new Error('Rate limit retries exceeded');
}Python
import requests
import time
def scan_with_retry(url, max_retries=3):
for attempt in range(max_retries):
response = requests.post(
'https://vulnradar.dev/api/v3/scan',
headers={'Authorization': 'Bearer YOUR_API_KEY'},
json={'url': url},
)
if response.status_code == 429:
retry_after = int(response.headers.get('Retry-After', 60))
wait = min(retry_after, 2 ** attempt)
print(f"Rate limited. Waiting {wait}s.")
time.sleep(wait)
continue
return response.json()
raise Exception('Rate limit retries exceeded')Best Practices
- 01
Check Remaining proactively. Read X-RateLimit-Remaining after every call. Pause early instead of waiting for 429s.
- 02
Batch via crawl. One crawl call is cheaper than N individual scans and shares one quota unit on the Bearer path.
- 03
Cache results locally. Don't re-scan a target that hasn't changed. The /api/v3/finding-types endpoint exposes stable IDs.
- 04
Spread requests. Distribute scans across the day rather than bursting all at once. It is easier to recover from a single 429.
- 05
Use multiple keys, but know what they split. How many active keys you can hold is per plan, not a flat 3: Free 1, Core Supporter 3, Pro Supporter 10, Elite Supporter unlimited. Going over is a 400 from the key-creation endpoint. Each key carries its own daily API-request budget, so splitting a workload across keys does buy separate request budgets. It does not multiply your scans: the daily scan quota and the named rate limits above are keyed on the account, so a second key shares them.
- 06
Use the demo endpoint for testing. /api/v3/demo-scan is IP-rate-limited (CONFIG_DEMO_SCAN_LIMIT=5 per 12h) and doesn't require an account.