Premium search APIs
Welcome to Twitter's premium Tweet search API. There are two premium search products based on the API:
- Search Tweets: 30-day endpoint → provides Tweets from the previous 30 days.
- Search Tweets: Full-archive endpoint → provides complete and instant access to Tweets dating all the way back to the first Tweet in March 2006.
This RESTful API supports a single query of up to 1,024 characters per request. Queries are written with premium operators and filter syntax - see Rules and filtering for more details. Requests can specify any time period, to the granularity of a minute. Since search queries can match so many Tweets, matching data are returned one 'page' at a time. Requests include a maxResults parameter (which defaults to 100 and has a maximum of 500) that determine how many Tweets to return per page. Using a next token provided in responses, users can paginate through the data. Both premium search APIs provides a counts endpoint that enables users to request the data volume associated with their query.
The Search Tweets API kicks off the next era of innovation for Twitter developers. The premium 30-day and Full-archive endpoints provide low-latency, full-fidelity, query-based access to the Tweet archive with minute granularity. Tweet data are served in reverse chronological order, starting with the most recent Tweet that matches your query. Tweets are available from the search API approximately 30 seconds after being published.
Requests include a maxResults parameter that specifies the maximum number of Tweets to return per API response. If more Tweets are associated with the query than this maximum amount of results per response, a next token is included in the response. These next tokens are used in subsequent requests to page through the entire set of Tweets associated with the query.
The premium search APIs also provide a counts endpoint that enables users to request the Tweet volume associated with their query.
Like all Twitter APIs, there are initial steps to take to prepare for API integration. If you have not visited our new developer portal, please check that out first. There you will be walked through the steps of creating a Twitter app and setting up a development environment for the Search Tweets endpoints. The developer portal enables the deployment of independent environments (i.e. dev, staging, prod) with different rate limits, consumption, filter-sets, user permissions, etc.
When you are finished with those steps you should have a Twitter App Consumer Key and Token for authentication, along with a search endpoint looking something like:
If you are using the 30-day endpoint:
If you are using the full-archive endpoint:
Where my_env_name is the development environment name you select.
The premium search API supports two tiers of access:
- Free Sandbox access that enables initial testing and development.
- Note that this tier provides access to full-fidelity Tweet data, but has a lower set of limits and capabilities than Premium access.
- Paid Premium access that provides increased access.
Below is a table that summaries the differences in the Sandbox and Premium tiers. For more information, and to manage your subscription, see HERE.
Last 30 days or full-archive
Last 30 days or full-archive
Tweets per data request
Tweet Counts endpoint
30 RPM, 10 RPS
60 RPM, 10 RPS
Expanded URLs, Profile Geo, Polls
- Search Tweets API is an HTTP-based RESTful API that returns responses encoded in JSON.
- All requests require a query parameter that contains filtering syntax for matching Tweets of interest.
- Query syntax is made up of operators that match on various Tweet and user attributes such as keywords, hashtags, URLs.
- Queries can be up to 1,024 characters long (256 with Sandbox tier).
- Provides both data and counts endpoint:
- Data endpoint returns Tweet arrays.
- Counts endpoint returns time-series counts of those Tweets (at Premium tier).
- Provides data and counts from the previous 30 days or Tweets from as early as 2006.
- Returns up to 500 Tweets per response (100 with Sandbox tier), and supports Tweet data pagination by providing ‘next’ tokens.
- Supports both GET and POST requests formats:
- GET request parameters are URL encoded.
- POST request parameters are JSON encoded and sent as a data body.
Premium search API supports rules with up to 1,024 characters. The Search Tweets APIs support the premium operators listed below. See our Premium operators guide for more details.
Matching on Tweet contents:
- "quoted phrase"
Matching on accounts of interest:
* Can not be used in a standalone fashion, must be combined with additional filtering logic.
- bounding_box:[west_long south_lat east_long north_lat]
- point_radius:[lon lat radius]
Data availability / important date
When using the Full-archive endpoint, keep in mind that the Twitter platform has continued to evolve since 2006. As new features were added, the underlying JSON objects have had new metadata added to it. For that reason it is important to understand when Tweet attributes were added that search operators match on. Below are some of the more fundamental 'born on' dates of important groups of metadata. To learn more about when Tweet attributes were first introduced, see this guide.
- First Tweet: 3/21/2006
- First Native Retweets: 11/6/2009
- First Geo-tagged Tweets: 11/19/2009
- URLs first indexed for filtering: 8/27/2011
- Enhanced URL expansion metadata (website titles and descriptions): 12/1/2014
- Profile Geo enrichment metadata and filtering: 2/17/2015
With the premium search APIs, some of the data within a Tweet is mutable, i.e. can be updated or changed after initial archival to values current at the time of the request.
This mutable data falls into two categories:
- User object metadata:
- User’s @handle (numeric ID does not ever change)
- Bio description
- Counts: statuses, followers, friends, favorites, lists
- Profile location
- Other details such as time zone and language
- Tweet statistics - i.e. anything that can be changed on the platform by user actions (examples below):
- Favorites count
- Retweet count
In most of these cases, the search APIs will return data as it exists on the platform at query-time, rather than Tweet generation time. However, in the case of queries using select operators (e.g. from, to, @, is:verified), this may not be the case. Data is updated in our index on a regular basis, with an increased frequency for most recent timeframes. As a result, in some cases, the data returned may not exactly match the current data as displayed on Twitter.com, but matches data at the time it was last indexed.
Note, this issue of inconsistency only applies to queries where the operator applies to mutable data. One example is filtering for usernames, and the best workaround would be to use user numeric IDs rather than @handles for these queries.