Skip to main content

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 the rate_limits table. 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 from lib/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.

25/dayFree
100/dayCore
150/dayPro
500/dayElite
PlanScans / day (session auth)API requests / day (Bearer)
Free2525
Core100100
Pro1505,000
Elite500Unlimited

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.

Every enforced named rate limit, its shipped default, and what it counts against
EndpointMax attemptsWindow (min)Keyed on
POST /api/v3/auth/login515IP
POST /api/v3/auth/signup360IP
POST /api/v3/auth/forgot-password310IP
POST /api/v3/auth/signup (per email address)560email address
POST /api/v3/auth/forgot-password (per email address)360email address
POST /api/v3/domains2060user
POST /api/v3/domains/{id}/verify3060user
POST /api/v3/auth/2fa/verify55user + IP, and user alone
API requests (on rate-limited routes)10060IP or user, per route
POST /api/v3/scan (and friends)10060user
POST /api/v3/scan/bulk1060user
POST /api/v3/browser/sessions2060user
POST /api/v3/ai/chat6060user
POST /api/v3/scan/verify and /api/v3/scan/verify-batch (one shared bucket)2060user
POST /api/v3/history/{id}/summary2060user
Admin PATCH re-auth1015user + IP
POST /api/v3/billing/verify55user
POST /api/v3/teams/members (invites)2060user
/api/v3/scan/tags6060user
GET /api/v3/public-scans601IP

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
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.000Z
X-RateLimit-LimitYour effective daily limit for this auth context
X-RateLimit-RemainingUnits remaining in the current window
X-RateLimit-UsedUnits consumed in the current window
X-RateLimit-PolicyAlways "daily": distinguishes this from any future per-minute policies
X-RateLimit-ResetISO 8601 timestamp at which the counter resets
Retry-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
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)

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

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

  1. 01

    Check Remaining proactively. Read X-RateLimit-Remaining after every call. Pause early instead of waiting for 429s.

  2. 02

    Batch via crawl. One crawl call is cheaper than N individual scans and shares one quota unit on the Bearer path.

  3. 03

    Cache results locally. Don't re-scan a target that hasn't changed. The /api/v3/finding-types endpoint exposes stable IDs.

  4. 04

    Spread requests. Distribute scans across the day rather than bursting all at once. It is easier to recover from a single 429.

  5. 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.

  6. 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.

Rate Limits: Per-Plan Request and Scan Caps | VulnRadar