30-day 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 30-day Search API provides low-latency, full-fidelity, query-based access to 30 days of historical data with minute granularity. Data is available within 30 seconds of generation on the Twitter platform.

It's a 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.. 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 the 30-day Search API supports the PowerTrack filtering syntax, please note that not all PowerTrack Operators are currently supported (see Available Operators).

Request types

The 30-day Search API supports two types of requests:

Search requests (data)

Search requests to the 30-day 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.

Filtering syntax

The 30-day 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.

Available operators

The 30-day Search API currently supports the following operators:

  • keyword
  • “quoted phrase”
  • “keyword1 keyword2”~N
  • from:
  • to:
  • retweets_of:
  • lang:
  • #
  • @
  • $
  • url:
  • bounding_box:[west_long south_lat east_long north_lat]
  • point_radius:[lon lat radius]
  • is:verified
  • is:retweet
  • has:geo
  • place:
  • place_country:
  • has:profile_geo
  • profile_country:
  • profile_region:
  • profile_locality:
  • has:mentions
  • has:hashtags
  • has:media
  • has:videos
  • has:images
  • has:links
  • has:symbols

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.


Next steps

Continue to the 30-day Search API reference

See code examples: