Full-Archive Search API
This is an enterprise API available within our managed access levels only. To use this API, you must first set up an account with our enterprise sales team. Learn more
The Full-Archive Search API provides complete and instant access to the full corpus of Twitter data dating all the way back to the first Tweet in March 2006.
It's RESTful API that supports a single query of up to 2,048 characters per request. Queries are written with the PowerTrack rule syntax - see Rules and filtering for more details. Users can specify any time period, to the granularity of a minute, going back to March 2006. However, responses will be limited to the lesser of your specified maxResults OR 31 days and include a ‘next’ token to paginate for the next set of results. If time parameters are not specified, the API will return matching data from the 30 most recent days.
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.
Much like the 30-day Search API product, users can also request counts (data volume) for the time period they are interested in. While Full-Archive Search API supports the PowerTrack filtering syntax, please note that not all PowerTrack Operators are currently supported (see Available Operators).
The Full-Archive Search API supports two types of requests:
Search requests (data)
Search requests to the Full-Archive Search API allow you to retrieve up to 500 results per response for a given timeframe, with the ability to paginate for additional data. Using the maxResults parameter, you can specify smaller page sizes for display use cases (allowing your user to request more results as needed) or larger page sizes (up to 500) for larger data pulls. The data is delivered in reverse chronological order and compliant at the time of delivery.
Counts requests (Tweet count)
Counts Requests provide the ability to retrieve historical activity counts, which reflect the number of activities that occurred which match a given query during the requested timeframe. The response will essentially provide you with a histogram of counts, bucketed by day, hour, or minute (the default bucket is hour). It's important to note that counts results do not always reflect compliance events (e.g., Tweets deletes) that happen well after (7+ days) a Tweet is published; therefore, it is expected that the counts metric may not always match that of a data request for the same query.
Billing note: each request - including pagination requests - made against the data and counts endpoints are counted as a billed request. Therefore, if there are multiple pages of results for a single query, paging through the X pages of results would equate to X requests for billing.
Data availability / important dates
- 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
To learn more about when when Tweet attributes were first introduced, see this guide.
Full-Archive Search API supports rules with up to 2,048 characters with no limits on the number of positive and negative clauses. However, only a subset of PowerTrack Operators are initially supported.
The Full-Archive Search API currently supports the following operators:
- “quoted phrase”
- “keyword1 keyword2”~N
- bounding_box:[west_long south_lat east_long north_lat]
- point_radius:[lon lat radius]
Note: The ‘lang:’ operator and all ‘is:’ and ‘has:’ operators cannot be used as standalone operators and must be combined with another clause (e.g. @twitterdev has:links)
For more details, please see the Getting started with premium operators guide.
See code examples:
- See simple scripts in several languages to help get started
- See an example Python client library
- See an example Ruby client library