Rate Limits

Deployment-managed BiomAI capacity

Public BiomAI requests use a deployment-managed Gemini/Vertex credential. Authenticated API keys can also use deployment-managed routing. In addition to the visible per-IP/per-user buckets below, BiomAPI can enforce internal global daily capacity limits for deployment-managed BiomAI traffic. These internal counters are not exposed by /api/v1/biom/usage.

BYOK requests use your Gemini key and are not counted against deployment-managed Gemini capacity. They still count against the visible biomai_byok user/IP bucket.

---

Four engine buckets

BiomAPI tracks usage across four independent engine types:

Engine	What it covers
biomai	PDF/image extraction using deployment-managed Gemini credentials
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, credential resolution, and before the Gemini call. If the request reaches that point, it counts even if extraction later fails or times out.

Credential routing is exact, not cascading. BYOK failures do not fall back to server-managed credentials.

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.