Credits and limits

Your allowance depends on whether you use public access, a BiomAPI key, or your own Gemini key.

Current public allowances

Operation	Credits per rolling 24 hours, per IP
BiomAI — PDF/image extraction	25
BiomAI with BYOK — extraction using your Gemini key	5,000
BiomJSON / BiomDIRECT — JSON validation, manual entry, and saved edits	1,000
BiomPIN retrieval	5,000

These public allowances are shared by people using the same IP address, such as on a hospital network. Each charge expires after 24 hours; allowances do not reset at midnight.

Standard BiomAI extraction costs 1 credit. Slow costs 0.5 credit. Public managed access allows up to 25 Standard or 50 Slow extractions, subject to shared service capacity.

BYOK has a separate extraction allowance. Google’s usage limits and billing also apply to your Gemini key. BYOK does not increase your BiomJSON allowance.

BiomJSON validates BiomDIRECT manual entries and edits without using AI. These saves share the 1,000-credit BiomJSON allowance.

Authenticated access has custom limits assigned to your BiomAPI key. To request access or discuss your requirements, use the Contact form in the web app.

Check your allowance

Check the web app’s status bar or request your current usage:

curl --fail-with-body https://biomapi.com/api/v1/biom/usage

Add Authorization: Bearer <your-key> to see the quotas assigned to your BiomAPI key. Authentication explains the two kinds of key.

Credit costs

Operation	Credits	Bucket
Standard PDF/image extraction	1	biomai, or biomai_byok with your Gemini key
Slow PDF/image extraction	0.5	biomai, or biomai_byok with your Gemini key
Successful BiomJSON validation, including BiomDIRECT saves	1	biomjson
BiomPIN retrieval attempt admitted by the limiter	1	retrieve

The four quota buckets are independent. JSON validation does not consume your BiomAI allowance. BYOK uses its own BiomAPI bucket and your Google account’s quota. BiomAPI limits still apply.

Standard is the API and CLI default. The web app defaults to Slow for a new multiple-file workflow. Slow can take substantially longer and does not automatically fall back to Standard.

When a request counts

BiomAPI validates the file and selects credentials before reserving PDF/image extraction credits. It reserves credits before extraction begins. After that point, the request counts even if it fails or times out.

JSON uploads and BiomDIRECT saves count only after successful validation. Invalid data does not consume a BiomJSON credit.

Retrieval consumes a credit before PIN validation and decryption. Once the limiter accepts an attempt, it counts even if the PIN is malformed, wrong, expired, or missing. This quota is separate from the wrong-PIN destruction rule.

Whose allowance applies

Public requests use a per-IP allowance, which can be shared by people on the same network. Authenticated requests use the quota assigned to the API user. The service can also limit overall managed BiomAI capacity; those internal limits are not shown in your usage response.

BYOK avoids managed Gemini capacity limits but still uses the applicable biomai_byok allowance. If a BYOK key fails, the request does not switch to a managed credential.

How credits become available again

Limits use a rolling 24-hour window. Each charge expires 24 hours after it was recorded, rather than all credits resetting at midnight.

Usage is stored persistently and survives server restarts. Changing an allowance does not erase charges already recorded within its window.

Each bucket in /usage reports:

Field	Meaning
used	Credits consumed; can include a half credit
limit	Your allowance for the bucket
resets_in_seconds	Time until the oldest charge expires, or null when unused

The first expiry may restore only part of your allowance. A half-credit recovery is enough for Slow, but not necessarily for Standard.

Handle a limit error

A quota rejection returns HTTP 429 with a Retry-After header in seconds and a structured error:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "BiomAI credit limit exceeded",
    "request_id": "3f5e3c51-d0b9-45fd-a7f4-6d7a3b592f42",
    "timestamp": "2026-09-05T10:00:00+00:00"
  }
}

Wait for the indicated delay before retrying. Check the error message as well as the status code. Retrieval also returns 429 when repeated wrong numeric PINs destroy a share. Waiting cannot recover that share.

If quota storage is unavailable, the service returns HTTP 503 rather than admitting requests without accounting for their credits. Usage checks can also return 503 while storage is unavailable.