# Requests & rate limits

The monthly request allowance, burst limits, overage, the quota headers and 429 handling.

HTML version: https://fundfactsapi.com/docs/requests · Updated 2026-10-25

## 4. Plan and rate limits

Plans are metered in requests. Free: 5 lookups / month, batch 1.
One request is counted per fund found on `/funds/{isin}`, `POST /funds`, `/portfolio`, `/overlap` and `/reports`, whether the payload comes from the store or is freshly loaded, and one per call on `/funds/{isin}/history` (Pro and up). A `404 fund_not_found` is not counted (up to 15 misses a month or the plan's allowance if larger). `/search`, `/resolve`, `/coverage`, `/watchlist`, `/changes` and `/me` are free. Invalid ISINs, pending entries and rejected (401/429) calls cost nothing. Read the quota from the response headers and never guess:

| Header | Meaning |
|---|---|
| `X-RateLimit-Limit` | Requests per month |
| `X-RateLimit-Remaining` | Requests left this month after this call (0 while running on overage) |
| `X-RateLimit-Reset` | Unix time (seconds) of the next monthly reset |
| `X-Burst-Limit` / `X-Burst-Remaining` | Requests allowed per minute, and how many are left |
| `Retry-After` | Only on 429: seconds to wait (60 for a burst, until the reset when the monthly allowance is used up) |

The same numbers are in the `quota` object of every response (`limit`, `remaining`, `used`, `overageUsed`, `resetAt`, `burst`). A 429 carries `reason`: `burst` (slow down), `quota_exhausted` or `overage_cap` (upgrade or wait for the reset); for the last two it also carries `upgrade` (the next plan, its allowance, price and URL) to show the user. Other plans for reference: Starter: 60 requests / month, batch 10; Pro: 1,000 requests / month, batch 50; Scale: 10,000 requests / month, batch 200. Upgrading is done at https://fundfactsapi.com/dashboard/billing, never from code.

Full reference: https://fundfactsapi.com/llms-full.txt