Fair use & rate limits
The published request limits, request costs, and caching behavior. These are the numbers the gateway actually enforces.
These are the limits the API enforces, published so you can build against them instead of discovering them. The same numbers live in the gateway configuration; when they change, this page changes in the same commit.
Keyless (open tier)
Current-state reads work with no key at all.
- 60 requests per hour per IP. One identifier per call; bulk endpoints require a key.
- Responses are cached at the edge (
s-maxage=300, stale-while-revalidate=600) with weak ETags. SendIf-None-Matchand a304costs you nothing. - When the limit store is unreachable the open tier fails closed with
503 rate_limiter_unavailableand aRetry-After.
Keyed tiers
Credits are the unit. Every response reports its own cost in X-Bixel-Request-Cost and your remaining allowance in X-Bixel-Quota-Remaining.
| Tier | Credits / month | Burst (per minute) |
|---|---|---|
| Free | 1,000 | 60 |
| Starter | 25,000 | 300 |
| Pro | 150,000 (pooled) | 900 |
| Scale | 1,000,000 (pooled) | 2,000 |
Request costs
- Current-state reads: 1 credit.
- History, diffs, and change queries: 3 credits.
POST /v1/resolve/batchis batch-weighted: roughly 1 credit per 100 identifiers, capped at 10 credits for a full 1,000-row call. A 1,000-row list is not one request.- Reading your own usage meter and managing watch subscriptions: 0 credits. Webhook delivery is always free.
- Read now (
POST /v1/companies/{company}/reads, a fresh full read of one company, once): 25 credits, settled only when the record lands with facts. The read captures the company's live pages first, then reads them, so a company new to Bixel lands with a full record rather than a thin one. A record read within the last 7 days is served as it is for the normal 1 credit. Free accounts get 5 reads a month. Keeping a company checked on a schedule is coverage, not a read: free inside your plan's allowance, 75 credits per company beyond it.
When you hit a limit
Every 429 carries Retry-After (seconds) plus the standard RateLimit-* headers. Honor them and you will never be blocked for long. Exhausting monthly credits with burst to spare answers credits_exhausted; a funded prepaid balance is drawn automatically first.
Misses are demand
A resolve of a live domain Bixel does not cover yet answers honestly (unresolved, or a tracked envelope with zero facts) and, for keyed callers, can queue the company for coverage: the answer says queued_for_capture: true with a request_id to poll at GET /v1/coverage/requests/{request_id}. Free accounts may queue 5 a day; paid plans are uncapped and drain first. Keyless misses are never used to trigger ingestion.