Rate Limit & Quotas
You can use a certain number of requests per month, defined by your plan.
Once you go over this quota, the API returns a 429 HTTP status code, and you either need to upgrade your plan or wait until the end of the month. We also enforce a minute rate limit on the free plan: up to 10 requests per minute. If you exceed this, the API returns a 429 HTTP status code. You then have to wait until the end of the minute to make more requests. Not every request counts towards your monthly request volume.
Without an API key, each client IP address gets 10 lookups an hour of the info endpoint (GET /v2/info). Every request counts at least once, including errors, calls to the status endpoint and requests to an endpoint that needs a key: batches and every endpoint but /v2/info and /v2/status answer 401 without one. Once the lookups are used up, the API returns a 429 with the error code rate_limit_exceeded.
Not every request counts
With an API key, only successful calls count against your quota. Any error on our side or validation errors (e.g., wrong parameter) will NOT count against your quota or rate limit.
Example request
curl "https://api.ipbase.com/v2/info?ip=80.110.0.1&apikey=YOUR-API-KEY"
Response Headers
Every metered response carries headers that tell you your monthly quota and how many requests you have remaining in the current period:
X-RateLimit-Limit-Quota-Month: 150
X-RateLimit-Remaining-Quota-Month: 49
On the free plan, matching -Minute variants of these headers are included as well. The minute headers count on the gateway node that answered the request: X-RateLimit-Limit-Quota-Minute shows that node's limit (5), and with our two gateway nodes that makes the 10 requests per minute of the free plan. X-RateLimit-Remaining-Quota-Minute is what is left on that node.
Each response also includes an X-Cost header stating how many requests the call counted against your quota — 1 for a normal billed request, one per IP address for a batch request, 0 for requests that are free of charge (e.g. requests made with a sandbox API key):
X-Cost: 1
If you are currently consuming a grace quota (e.g. while a payment is being completed), the monthly headers are replaced by their -Grace- variants:
X-RateLimit-Limit-Grace-Month: 100
X-RateLimit-Remaining-Grace-Month: 42
If overages are enabled for your plan and you exceed your monthly quota, the overage headers are sent in addition to the (exhausted) monthly headers:
X-RateLimit-Limit-Overage-Month: 500
X-RateLimit-Remaining-Overage-Month: 350
You can also check your current quota usage at any time — without spending a request — via the status endpoint.