Skip to main content
Your account’s API keys share one rate-limit bucket, included credit allowance, and purchased credit balance.

​
Plan allowances

Read Get usage for your account’s effective limits and reset time rather than hard-coding these values.

​
Credit consumption

Your credit is consumed when authentication and quota admission succeed, before the company handler validates input or retrieves data. You still consume a credit if the handler returns 400, 404, 500, or 502, or if a search returns no matches. Cached company lookups have the same credit cost. Requests rejected for an invalid key, a rate limit, or an exhausted credit quota do not consume a credit. A credit-quota rejection can still consume rate-limit capacity because the rate check happens first. You use your included credits first. After you exhaust them, company requests deduct from your purchased credit balance. The usage field quotas.requests.used counts both kinds of credit consumption, so it can exceed quotas.requests.limit.

​
Quota periods

Your Free allowance resets at the start of each calendar month in UTC. Your effective Plus allowance uses your subscription billing period. Purchased credits are a separate balance; a quota-period reset does not replenish that balance. Use data.resetAt from the usage response for the next included-credit reset. data.period.start and data.period.end are date-only labels for the current period; resetAt gives you the exact boundary.

​
Request rate

Your rate limit uses a token bucket. The bucket holds up to your plan’s requests-per-minute limit, and capacity refills continuously at that rate. It does not reset all at once at the next minute boundary. Every admitted request, including usage checks and company requests that later fail, consumes one rate-limit token. Pace concurrent workers together because all keys on your account share the bucket.

​
Response headers

Authenticated responses include these headers when admission succeeds or a quota/rate limit rejects your request:

​
Handle HTTP 429

Inspect the problem response type to distinguish the two causes: For a credit-quota rejection, Retry-After points to the included allowance’s reset. The problem also includes quota: "monthly_credits", the included limit, and an RFC 3339 UTC reset timestamp. You can still call Get usage when your credit allowance is exhausted, provided you have rate-limit capacity.