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. Limits and usage are expressed in credits:

• Standard BiomAI or BYOK processing: 1 credit
• Slow BiomAI or BYOK processing: 0.5 credit
• BiomJSON validation and BiomPIN retrieval: 1 credit

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	Deployment setting
biomai	BIOMAI_PUBLIC_DAILY_LIMIT
biomai_byok	BIOMAI_BYOK_PUBLIC_DAILY_LIMIT
biomjson	BIOMJSON_PUBLIC_DAILY_LIMIT
retrieve	RETRIEVE_PUBLIC_DAILY_LIMIT

Call /api/v1/biom/usage without authentication to obtain the public limits of the running deployment.

---

Authenticated limits (per user per day)

Configured per API key in API_KEYS_JSON:

Engine	API_KEYS_JSON quota key
biomai	biomai
biomai_byok	biomai_byok
biomjson	biomjson
retrieve	retrieve

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

---

Rate limit window

All credit limits use a 24-hour sliding window (not a midnight calendar reset). Each consumed credit amount rolls off exactly 24 hours after it was recorded, giving a continuously refreshing window.

---

When rate limits are consumed

BiomAI and BYOK credits 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. Slow consumes 0.5 credit with exact half-credit accounting; there is no rounding or odd-request freebie.

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

Each engine entry reports used, limit, and resets_in_seconds. The response is calculated from the running deployment settings and, when authenticated, the caller’s API_KEYS_JSON quotas.

---

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 credit entry rolls off. used may be an integer or end in .5.