<< Back to Getting Started

 

Rate limiting

The Twitter API only allows clients to make a limited number 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 150 requests per hour. The REST API does account- and IP-based rate limiting. Authenticated API calls are charged to the authenticating user's limit while unauthenticated API calls are deducted from the calling IP address' allotment.

 

Rate limiting only applies to methods that request information with the HTTP GET command. API methods that use HTTP POST to submit data to Twitter, such as statuses/update do not affect rate limits. Additionally, requests to account/rate_limit_status are not charged to a 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 begins to receive HTTP 400 response codes. It is best practice for applications to monitor their current rate limit status and dynamically throttle requests if necessary. The REST API offers two ways to observe this status:

 

1. The account/rate_limit_status method. Calling this method does not count against the requestor's API limit.
2. HTTP response headers included in all REST API responses which count against the rate limit: 

• X-RateLimit-Limit the current limit in effect
• X-RateLimit-Remaining the number of hits remaining before you are rate limited
• X-RateLimit-Reset the time the current rate limiting period ends in epoch time.

 

Whitelisting

Some applications find that the default limit proves insufficient. Under such circumstances, we offer whitelisting. It is possible to whitelist both accounts and IP addresses. Each whitelisted entity, whether an account or IP address, is allowed 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. Approval or rejection for whitelisting requests is emailed to the email address associated with the account that filed the application.

 

IP whitelisting takes precedence to account rate limits. GET 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 request many users' data.

 

Whitelisting does not removed the daily update and follower limits associated with POST requests; these limits are administered on a per account basis.

 

If you have received verification from Twitter that your account and/or IP address has been whitelisted you can verify your whitelisting with the accounts/rate_limit_status method. Calling this method with credentials will return the rate limit status of the authenticating user and invoking this method without credentials will return the rate limit status of the calling IP address. 

 

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 against the search rate limiter. The specific number of requests a client is able to make to the Search API for a given hour is not released. Note that the Search API is not limited by the same 150 requests per hour limit as the REST API. The number is quite a bit higher and we feel it is both liberal and sufficient for most applications. We do not give the exact number because we want to discourage unnecessary search usage.

 

Search API usage requires that applications include a unique and identifying User Agent string. A HTTP Referrer is expected but is not required. Consumers using the Search API but failing to include a User Agent string will receive a lower rate limit.

 

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. The Retry-After header's value is the number of seconds your application should wait before submitting another query (for example: Retry-After: 67).

 

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. We do not give preemptive whitelisting for the Search API. You must have a working application that has proven need (users) for more capacity before we will discuss whitelisting. If you feel that your application is doing everything it can to limit and combine queries where appropriate, please contact Twitter to discuss your needs. The Search API is only able to whitelist IP addresses, not user accounts. This works in most situations but for cloud platforms like Google App Engine, applications without a static IP addresses cannot receive Search whitelisting.

 

Avoiding the Rate Limiter

The same general techniques and design decisions can be used to avoid the crunch of 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 infrequently, cache the response on your end, and display the local version on page loads.
2. Prioritize active users: If your site keeps track of many Twitter users (for example, fetching their current status or statistics about their Twitter usage), consider only requesting data for users who have recently signed into your site.
3. Search back-offs: 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 automatically blacklist your application. You know that you are blacklisted if your client is unable to get a response for a request sent to the API. It appears 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 our support folks so we can get you back online.

 

<< Back to Getting Started