Rate limits + credits

Three layers — monthly quota, concurrent cap, and credit overflow.

Monthly quota

Each plan has a fixed number of requests per UTC month. The counter resets at the start of every month. Check current usage anytime via GET /v1/usage.

Plan	Requests / month
Free	1,000
Starter	10,000
Growth	100,000
Scale	500,000
Enterprise	Unlimited

When you cross the cap, behaviour depends on the tier: Free is hard-capped (returns RATE_LIMITED 429); paid tiers fall through to credit overflow.

Concurrent requests

Independent of the monthly counter — limits how many requests can be in flight at the same instant per API key.

Plan	Concurrent
Free	2
Starter	5
Growth	20
Scale	50
Enterprise	100

Exceed it and you get CONCURRENT_LIMIT 429 with retry_after: 1. Slots free as fast as requests complete (typically < 1s). Implementation: atomic Redis INCR with 30s safety TTL — a crashed function never permanently consumes a slot.

ℹ

Concurrency is per API key, not per IP. Multiple processes sharing the same key all share the cap. Issue separate keys to parallelize beyond your tier limit.

Credits (overflow)

Paid tiers run as soft caps. Once you cross the monthly quota, each extra request debits 1 credit from your balance. Out of plan + out of credits → 402 PAYMENT_REQUIRED. Buy credit packs from /read/billing#credits:

Pack	Price	Credits	Per credit	Bonus
Top-up S	$5	500	$0.0100	—
Top-up M	$20	2,200	$0.0091	10% bonus
Top-up L	$50	6,000	$0.0083	20% bonus
Top-up XL	$200	28,000	$0.0071	40% bonus

◈

Free plan can receive credits but not buy them. Launch promos and goodwill grants apply to Free accounts; only paid tiers can purchase top-ups. Hits 402 stop the moment you upgrade or credits arrive.

Per-request response headers tell you which bucket got billed: X-Onto-Billed: plan (in quota) or X-Onto-Billed: credit (overflow). When credits are debited, X-Credits-Remaining shows the new balance.

Cache behavior

Successful /v1/read and /v1/read-and-score responses are cached for 1 hour per (URL, engine version). Cache hits are near-zero latency and still count against your monthly quota (one debit per request, hit or miss). Set "fresh": true in the body to bypass.

The cache key includes a server-side engine version, so when we ship cleaning-engine improvements, the next call gets a fresh extraction automatically.