Rate Limits

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	30
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, not IP. Both IP and user counters are maintained; whichever applies is checked.

---

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.

---

Rate limits are applied after processing

Rate limits are consumed only after a successful extraction. Files that fail validation, parse errors, or LLM failures do not count against your quota — only successful results do.

---

Checking your usage

GET /api/v1/biom/usage

{
  "auth_type": "public",
  "user_id": null,
  "engines": {
    "biomai":       { "used": 5,  "limit": 30,   "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"
  }
}

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