Like all modern web platforms, NS1 employs rate limiting to control the number of API calls users can issue to the platform over a given period of time. Doing so allows us to distribute resources equitably amongst users and also protect the platform.
NS1’s implementation is quite flexible and nuanced. It is based on the token bucket algorithm, which allows a certain number of tokens for some period of time. Each token represents a request. Available tokens may be used as quickly as your automation is capable of sending requests.
Note
Automatic abuse thresholds are in place to protect the platform, and hard rate-limiting by these mechanisms is possible if abusive request rates are received.
Tokens will only be replenished at a rate equal to the number of tokens allowed per period divided by the number of seconds in a period. For example, an API route with a rate limit set at 300 tokens per 60-second period would allow you to make up to 300 requests as fast as you wish, but depleted tokens will only be replenished at a rate of 5 per second (300 divided by 60).
When a user makes a request to the NS1 API, the response includes additional headers which provide precise API rate-limiting information, including:
-
The number of tokens per rate-limit period for the endpoint
-
The number of seconds in the rate-limit period
-
The number of tokens remaining in the current period
The number of tokens per period varies by API endpoint. For example, a simple GET request might allow the user a maximum of 900 tokens with a rate-limit period of 300 seconds. The user may approach the 900-token limit as fast as they’d like as each call will decrement the “remaining” amount by a single token. The replenish rate for this route would be 900 / 300 = 3 tokens per second. This allows the user to either pace their application to steadily make requests while avoiding the limit, or fire off a large number of requests in bursts and simply wait for the tokens to replenish.
Other routes, such as an API POST or PUT, are more computationally expensive and therefore have lower rate limits. POST requests, for example, might have a rate limit closer to 300 requests per 300 seconds; therefore, tokens would only be restored to the account at a rate of 1 request per second. It is best to strategically develop your applications to work with this implementation and avoid interruptions while making changes.
Current rate limit data for all requests can be found in each API response by including the "-v" flag in your cURL command. For example,
curl -v -X GET -H 'X-NSONE-Key: $NSONE_API_KEY' https://api.nsone.net/v1/monitoring/regions
The response will include the following headers, which you can check and use to adjust your automation:
> GET /v1/monitoring/regions HTTP/1.1 < HTTP/1.1 200 OK ... < X-RateLimit-Remaining: 899 < X-RateLimit-By: customer < X-RateLimit-Limit: 900 < X-RateLimit-Period: 300