Rate Limiting

The default rate limit for calls to the REST API varies depending on the authorization method being used and whether the method itself requires authentication.

• Unauthenticated calls are permitted 150 requests per hour. Unauthenticated calls are measured against the public facing IP of the server or device making the request.
• OAuth calls are permitted 350 requests per hour and are measured against the oauth_token used in the request.

Ensure you inspect the headers returned when requesting methods which do not require authentication. If the request you make includes invalid OAuth information the API will do one of two things:

• For methods which require authentication, the API will return an error response with more information about the error. For example an HTTP 401 error with the response body
  Could not authenticate with OAuth.
• For methods which can be requested unauthenticated, the API will process the request as if authentication had not been used. This means the request will count against the unauthenticated rate limit. If this has happened the API will include the following header in it's response:
  X-Warning: Invalid OAuth credentials detected.

Rate limits are applied to methods that request information with the HTTP GET command. Generally API methods that use HTTP POST to submit data to Twitter are not rate limited, however some methods are being rate limited now. Every method in the API documentation explains if it is rate limited or not.

Actions such as publishing status updates, sending direct messages, following and unfollowing are not directly rate limited by the API but are subject to fair use limits. These Twitter Limits are described on our help site.

Feature-based rate limiting

Some features, such as the GET search method, have additional feature rate limits which are applied in conjunction with the main REST API rate limit. Calls to users/search will count against both the feature and default request rate limit. If either limit is exhausted, the method will fail. You can monitor the status of the feature rate limit by inspecting the HTTP response headers that are returned.

In addition to the default rate limit headers you will also see:

• X-FeatureRateLimit-Limit
• X-FeatureRateLimit-Remaining
• X-FeatureRateLimit-Reset

The meaning of these headers correspond to the X-RateLimit headers provided by the main REST API limit.

If your application is being rate-limited by the REST API it will 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 which are explained in the Rate Limiting FAQ.

If you are rate limited on the Search or Streaming APIs an HTTP 420 response code will be returned.

REST & Search API Whitelisting is not provided. Resourceful use of more efficient REST API requests, authentication, and Streaming APIs will allow you to build your integration successfully without requiring whitelisting.

Requests to the Search API, hosted on search.twitter.com, do not count towards the REST API limit. However, all requests coming from an IP address are applied to a Search Rate Limit. The Search Rate Limit isn't made public to discourage unnecessary search usage and abuse, but it is higher than the REST Rate Limit. We feel the Search Rate Limit is both liberal and sufficient for most applications and know that many application vendors have found it suitable for their needs.

Requirements for the Search API

Search API usage requires that applications include a unique and identifying User Agent string. An HTTP Referrer is expected but is not required. Applications 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 an HTTP 420 response code. It is best practice to watch for this error condition and honor the Retry-After header which is returned. The Retry-After header's value is the number of seconds your application should wait before requesting date from the Search API again.

Use Streaming APIs Instead

The Search API is best suited for user-initiated ad-hoc queries. If your application requires repeated Search API polling, you might want to consider the Streaming API instead.

The tips below are there to help you code defensively and reduce the possibility of being rate limited.

Some application features that you may want to provide are simply impossible in light of rate limiting, especially around the freshness of results. If real-time information is an aim of your application, look into User Streams or Site Streams.

Caching

Store API responses in your application or on your site if you expect a lot of use. For example, don't try to call the Twitter API on every page load of your website landing page. Instead, call the API infrequently and load the response into a local cache. When users hit your website load the cached version of the results.

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.

Adapt to the search results

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 popular but not waste cycles requesting queries that very rarely change.

Alternatively, consider using the Streaming APIs and filter on your search terms.

We ask that you honor the rate limit. If you or your application abuses the rate limits we will blacklist it. If you are blacklisted you will be unable to get a response from the Twitter API.

If you or your application has been blacklisted and you think there has been an error you can contact the email address on the Support. So we can get you back online quickly please include the following information:

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

The Streaming API has rate limiting and access levels that are appropriate for long-lived connections. See the Streaming APIs for more details.

Leveraging the Streaming API is a great way to free-up your rate limits for more inventive uses of the Twitter API.

Rate Limiting information for the Streaming API is detailed on Connecting to a streaming endpoint.

We have a page of Rate Limiting FAQ which may help.