<< Back to the Orientation

Rate limiting

The Twitter API only allows clients to make a limited allotment of calls in a given hour. This policy affects the two APIs in different ways. 

REST API Rate Limiting

The default rate limit for calls to the REST API is 100 requests per hour. The REST API does account- and IP-based rate limiting. Authenticated API calls are charged to the authenticating user while unauthenticated API calls come from the calling IP address' limit.

Rate limiting only applies to methods that request information. API methods that POST data to Twitter, such as statuses/update, do not result in debiting. Additionally, requests to account/rate_limit_status is not charged to an account or IP address' limit. These unlimited methods are still subject to daily update and follower limits to promote healthy use and discourage spam.

Your application should recognize it is being rate-limited by the REST API if it receives HTTP 400 response codes to requests. For more mature applications, it is a best practice to monitor the account/rate_limit_status method and dynamically throttle requests.

Whitelisting

Some applications find that the default limit proves terribly insufficient. Under such circumstances, we offer whitelisting which will raise an accout or IP address' rate limit to 20000 requests per hour. If you are developing an application that should be considered for whitelisting, please fill out the whitelisting request form. Our manual review process can take up to a week. If you have a whitelisting that needs to be updated through the addition or removal of IP addresses, reapply with an explanation of the change.

IP whitelisting takes precedence to account rate limits. Requests from a whitelisted IP address made on a user's behalf will be deducted from the whitelisted IP's limit, not the users. Therefore, IP-based whitelisting is a best practice for applications that interact with many users' data.

Search API Rate Limiting

The Search API is rate limited by IP address. The number of search requests that originate from a given IP address are counted. The specific number of requests a client is able to make to the Search API for a given hour is not released. However we feel it is liberal and sufficient for most applications.

An application that exceeds the rate limitations of the Search API will receive HTTP 503 response codes to requests. It is a best practice to watch for this error condition and honor the Retry-After header that instructs the application when it is safe to continue.

Whitelisting

There is no general idea of a whitelist for the Search API as with the REST API. However, under extraordinary circumstances we work with developers to raise rate limiting for Search requests. If you feel that your application is doing everything it can to limit and combine queries where appropriate, please email api@twitter.com to discuss your needs.

Avoiding the Rate Limiter

The same general techniques and design decisions can be used to avoid both the rate limiter.

1. Caching: Store API responses in your application or on your site if you expect high-volume usage. For example, don't try to call the Twitter API on every page load of your hugely popular website. Instead, call our API once a minute and save the response on your end, displaying your cached version on your site.
2. Intellegent requesting: If your site keeps track of many Twitter users (for example, fetching their current status or statistics about their Twitter usage), please consider only requesting data for users who have recently signed in to your site. Or if your application monitors a high volume of search terms, query less often for searches that have no results than for those that do. By using a back-off you can keep up to date on queries that are hot but not waste cycles requesting queries that very rarely change.

Blacklisting

We ask that you honor the rate limit. Consistent failure to avoid the rate-limiter will signal Twitter to blacklist your application. You know that you are blacklisted if your client is unable to get a response for any request sent to the API. It will appear as if API calls are sent down a blackhole.

If your application has been blacklisted and you would like service reinstated please do the following:

1. If you are using the REST API, make a call to the account/rate_limit_status from the account or computer in question.
2. Explain why you think your application was blacklisted.
3. Describe how you have fixed the problem that resulted in blacklisting.

Send that information in an email to api@twitter.com.