Every day many thousands of developers make requests to the X API. To help manage the sheer volume of these requests, limits are placed on the number of requests that can be made. These limits help us provide the reliable and scalable API that our developer community relies on. 

The maximum number of requests that are allowed is based on a time interval, some specified period or window of time. The most common request limit interval is fifteen minutes. If an endpoint has a rate limit of 900 requests/15-minutes, then up to 900 requests over any 15-minute interval is allowed. 

Rate limits are applied based on which authentication method you are using. For example, if you are using OAuth 1.0a User Context, you will have one limit per time period for each set of users’ Access Tokens, while if you are using OAuth 2.0 Bearer Token, you will have a separate limit per time period for requests made by your app. When these limits are exceeded, an error is returned. Keep reading to learn more about these details and tips on how to avoid being rate limited. 
 

Table of contents

• X API v2 Free rate limits  
• X API v2 Basic rate limits  
• X API v2 Pro rate limits  
• X API Enterprise rate limits  
• Rate limits and authentication method
• HTTP headers and response codes
• Recovering from rate limits
• Tips to avoid being rate limited

X API v2 rate limits - Free

The following table lists the rate limits for the X API v2 Free access. These rate limits are also documented on each endpoint's API Reference page and also displayed in the  developer portal's products section.

X API v2 rate limits - Basic

The following table lists the rate limits for the X API v2 Basic access. These rate limits are also documented on each endpoint's API Reference page and also displayed in the  developer portal's products section.

X API v2 rate limits - Pro

The following table lists the rate limits for the X API v2 Pro access. These rate limits are also documented on each endpoint's API Reference page and also displayed in the  developer portal's products section.

X API v2 rate limits - Enterprise

To learn more about enterprise access rate limits reach out to your account manager.

Rate limits and authentication method

Rate limits are set at both the developer App and the user access token levels:

• OAuth 2.0 Bearer Token: App rate limit
  This authentication method and rate limit allows you to make a certain number of requests to endpoints on behalf of your developer App. When using this authentication method, rate limits are determined by the number of requests you make using a Bearer Token.
  
  If an endpoint has an App rate limit of 450 requests per 15 minute interval, then you can make 450 requests per window on behalf of your App when you use your Bearer Token.
  
  This limit is considered completely separate from the user rate limit.
  
  
• OAuth 1.0a User Context: User rate limit
  This authentication method and rate limit allows for you to make a certain number of requests to endpoints on behalf of a X user, identified by the user Access Token used when authenticating the request. For example, if you would like to retrieve private metrics from Posts, you would need to authenticate with the user Access Tokens associated with that user, which can be generated by using the 3-legged OAuth flow. 
  
  If ten users have authorized your developer App, and the endpoint you are making a request to has a user rate limit of 900 requests per 15-minute interval, then you can make up to 900 requests per user in that 15 minute time period, for a total of 9000 requests.
  
  This limit is considered completely separate from App rate limit. 
   

HTTP headers and response codes

Use the HTTP headers in order to understand where the application is at for a given rate limit, on the method that was just utilized.

Note that the HTTP headers are contextual. When using application-only authentication, they indicate the rate limit for the application context. When using user-based authentication, they indicate the rate limit for that user context.

• x-rate-limit-limit: the rate limit ceiling for that given endpoint
• x-rate-limit-remaining: the number of requests left for the 15-minute window
• x-rate-limit-reset: the remaining window before the rate limit resets, in UTC epoch seconds
   

When an application exceeds the rate limit for a given X API endpoint, the API will return a HTTP 429 “Too Many Requests” response code, and the following error will be returned in the response body:

{ "errors": [ { "code": 88, "message": "Rate limit exceeded" } ] } 

Recovering from a rate limit

When these rate limits are exceeded, a 429 'Too many requests' error is returned from the endpoint.  As discussed below, when rate limit errors occur, a best practice is to examine HTTP headers that indicate when the limit resets and pause requests until then.  

When a "too many requests" or rate-limiting error occurs, the frequency of making requests needs to be slowed down. When a rate limit error is hit, the x-rate-limit-reset: HTTP header can be checked to learn when the rate-limiting will reset. 

Another common pattern is based on exponential backoff, where the time between requests starts off small (for example, a few seconds), then doubled before each retry. This is continued until a request is successful, or some reasonable maximum time between requests is reached (for example, a few minutes).  

Ideally, the client-side is self-aware of existing rate limits and can pause requests until the currently exceeded window expires. If you exceed a 15-minute limit, then waiting a minute or two before retrying makes sense.

Note that beyond these limits on the number of requests, the Standard Basic level of access provides up to 500,000 Posts per month from the recent search and filtered stream endpoints. If you have exceeded the monthly limit on the number of Posts, then it makes more sense for your app to raise a notification and know its enrollment day of the month and hold off requests until that day.  
 

Tips to avoid being rate limited

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 the filtered and sampled stream endpoints. 
 

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 X 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 X users (for example, fetching their current status or statistics about their X 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 filtered stream endpoint and filter with your search queries.
 

Denylist

If an application abuses the rate limits, it will be denied. Denied apps are unable to get a response from the X API. If you or your application has been denied and you think there has been a mistake, you can use our Platform Support forms to request assistance. Please include the following information:

1. Explain why you think your application was denied.
2. If you are no longer being rate limited, describe in detail how you fixed the problem.