Rate Limits

Shared BiomAI capacity

Non-BYOK BiomAI requests use BiomAPI’s shared server Gemini quota. In addition to the visible per-IP/per-user buckets below, BiomAPI enforces internal global daily capacity limits for all non-BYOK BiomAI traffic and for public non-BYOK BiomAI traffic. These internal counters are not exposed by /api/v1/biom/usage.

BYOK requests use your Gemini key and are not counted against the shared server Gemini capacity.

---

Four engine buckets

BiomAPI tracks usage across four independent engine types:

Engine	What it covers
biomai	PDF/image extraction using shared Gemini quota
biomai_byok	PDF/image extraction using your own Gemini key (BYOK)
biomjson	JSON upload validation (no LLM call)
retrieve	BiomPIN retrieval

---

Public limits (per IP per day)

Engine	Default limit
biomai	15
biomai_byok	1,000
biomjson	300
retrieve	1,000

---

Authenticated limits (per user per day)

Configured per API key in API_KEYS_JSON. Typical quota:

Engine	Default
biomai	300
biomai_byok	3,000
biomjson	3,000
retrieve	10,000

Authenticated requests are tracked by user ID. Public requests are tracked by IP address.

---

Rate limit window

All limits use a 24-hour sliding window (not a midnight calendar reset). Usage timestamps roll off exactly 24 hours after they were recorded, giving a continuously refreshing window.

---

When rate limits are consumed

BiomAI and BYOK limits protect external Gemini cost and quota. They are consumed after local extension/content validation and before the Gemini call. If the request reaches that point, it counts even if extraction later fails or times out.

BiomJSON is a local validation path. JSON uploads consume quota only after successful validation/processing. Malformed JSON and failed BiomJSON validation do not count.

---

Checking your usage

GET /api/v1/biom/usage

{
  "auth_type": "public",
  "user_id": null,
  "engines": {
    "biomai":       { "used": 5,  "limit": 15,   "resets_in_seconds": 72400 },
    "biomai_byok":  { "used": 0,  "limit": 1000, "resets_in_seconds": 72400 },
    "biomjson":     { "used": 2,  "limit": 300,  "resets_in_seconds": 72400 },
    "retrieve":     { "used": 12, "limit": 1000, "resets_in_seconds": 72400 }
  },
  "keys": {
    "biomapi": { "provided": false },
    "gemini":  { "provided": false }
  }
}

---

Rate limit errors

When a limit is exceeded, the API returns HTTP 429 Too Many Requests:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded for biomai engine",
    "request_id": "3f5e3c51-d0b9-45fd-a7f4-6d7a3b592f42",
    "timestamp": "2026-05-24T12:00:00+00:00"
  }
}

The resets_in_seconds field in /usage tells you how long until the oldest tracked request rolls off.