Comparing Twitter API’s Search Tweets endpoints
The v2 Search Tweets endpoint will eventually replace the standard v1.1 search/tweets endpoint, premium v1.1 Search API, and enterprise Search API. If you have code, apps, or tools that use an older version of a Twitter search endpoint and are considering migrating to the newer Twitter API v2 endpoints, then this guide is for you.
This page contains three comparison tables:
Recent search comparison
The following table compares the various types of recent search endpoints:
| Description | Standard v1.1 | Twitter API v2 |
| Host domain | https://api.twitter.com | https://api.twitter.com |
| Endpoint path | /1.1/search/tweets.json | /2/tweets/search/recent |
| Authentication | OAuth 1.0a User Context OAuth 2.0 Bearer Token |
OAuth 1.0a User Context OAuth 2.0 Bearer Token |
| Timestamp format | YYYYMMDD | YYYY-MM-DDTHH:mm:ssZ ISO 8601 / RFC 3339 |
| Returns Tweets that are no older than | 7 days | 7 days |
| HTTP methods supported | GET | GET |
| Default request rate limits | 180 requests per 15 min with OAuth 1.0a User Context 450 requests per 15 min with OAuth 2.0 Bearer Token |
180 requests per 15 min with OAuth 1.0a User Context 450 requests per 15 min with OAuth 2.0 Bearer Token |
| Offers fully unwound URLs | ✔ | |
| Maximum Tweets per response (default) | 100 (15) | 100 (10) |
| Tweet JSON format | Standard v1.1 format | Twitter API v2 format (determined by fields and expansions request parameters, not backward-compatible with v1.1 formats) To learn more about how to migrate from the Standard v1.1 format to the Twitter API v2 format, please visit our data formats migration guide. |
| Supports selecting which fields return in the payload | ✔ | |
| Supports requesting and receiving annotations | ✔ | |
| Supports requesting specific metrics within Tweet object | ✔ | |
| Supports the conversation_id operator and field | ✔ | |
| JSON key name for Tweet data array | statuses | data |
| JSON key name for pagination | search_metadata.next_results | meta.next_token |
| Supports navigating archive by time range | ✔ | ✔ |
| Time resolution of time-based requests | day | second |
| Timezone | UTC | UTC |
| Request parameters for navigating by time | until | start_time end_time |
| Request parameters for navigating by Tweet ID | since_id max_id |
since_id until_id |
| Request parameter for pagination | Provides URL-encoded query | next_token |
| Requires the use of credentials from a developer App associated with a Project | ✔ |
Full-archive search comparison
The following table compares the various types of full-archive search endpoints:
| Description | Premium v1.1 | Enterprise | Twitter API v2 |
| Host domain | https://api.twitter.com | https://gnip-api.twitter.com | https://api.twitter.com |
| Endpoint path | /1.1/tweets/search/fullarchive/:label.json | /search/fullarchive/accounts/:account_name/:label | /2/tweets/search/recent |
| Authentication | OAuth 2.0 Bearer Token | Basic auth | OAuth 2.0 Bearer Token |
| Timestamp format | YYYYMMDDHHMM | YYYYMMDDHHMM | YYYY-MM-DDTHH:mm:ssZ ISO 8601 / RFC 3339 |
| Returns Tweets that are no older than | The full archive since March 2006 | The full archive since March 2006 | The full archive since March 2006 |
| HTTP methods supported | GET POST |
GET POST |
GET |
| Default request rate limits | Paid premium Sandbox premium Both |
The per minute rate limit will vary by partner as specified in your contract. 20 requests per sec with Basic auth |
300 requests per 15 min with OAuth 2.0 Bearer Token 1 requests per 1 sec with OAuth 2.0 Bearer Token |
| Offers fully unwound URLs | ✔ | ✔ | ✔ |
| Tweets per response | Maximum: 500 Default: 100 |
Maximum: 500 Default: 100 |
Maximum: 500 Default: 10 |
| Tweet JSON format | Native Enriched format | Native Enriched or Activity Streams format |
Twitter API v2 format (determined by fields and expansions request parameters) |
| Supports selecting which fields return in the payload | ✔ | ||
| Supports requesting and receiving annotations | ✔ | ||
| Supports requesting specific metrics within Tweet object | ✔ | ||
| Supports the conversation_id operator and field | ✔ | ||
| JSON key name for Tweet data array | results | results | data |
| JSON key name for pagination | next | next | meta.next_token |
| Time resolution of time-based requests | second | second | second |
| Timezone | UTC | UTC | UTC |
| Supports navigating archive by Tweet ID | ✔ | ||
| Request parameters for navigation by time | fromDate toDate |
fromDate toDate |
start_time end_time |
| Request parameters for navigating by Tweet ID | since_id until_id |
||
| Request parameter for pagination | next_token | next_token | next_token |
| Requires the use of credentials from a developer App associated with a Project that has Academic Research access | ✔ |
Filtering operator comparison
The four different versions (standard, premium, enterprise, and v2) of search Tweets differ in which operators are available, and also have varying levels of operator availability within each version, which are explained below.
Standard
- Unlike the other tiers, standard’s filtering tools are passed as parameters rather than operators.
- There are no sub-tiers of standard parameters. All parameters are available to all developers.
Premium
- Sandbox and paid: The operator is available to all premium users
- Paid only: The operator is only available to those users that are using a paid tier of premium
Enterprise
- There are no sub-tiers of enterprise operators
Twitter API v2
- Core: Available when using any Project
- Advanced: Available when using a Project with Academic Research access
You can learn more about each of these sets of operators in their respective guides:
Now that we understand the different operator levels within premium and Twitter API v2, here is the table that maps out operator availability for search Tweets (note that if the cell is left blank, the operator is not available):
| Search operator | Standard | Premium | Enterprise | v2 |
|---|---|---|---|---|
| keyword | Available q:keyword |
Sandbox and paid |
Available | Core |
| emoji | Available q:😄 |
Sandbox and paid | Available | Core |
| “exact phrase” | Available | Sandbox and paid | Available | Core |
| # | Available | Sandbox and paid | Available | Core |
| $ | Available | Available | Advanced | |
| @ | Available | Sandbox and paid | Available | Core |
| from: | Available | Sandbox and paid | Available | Core |
| to: | Available | Sandbox and paid | Available | Core |
| url: | Available | Sandbox and paid | Available | Core |
| retweets_of: | Sandbox and paid | Available | Core | |
| context: | Core | |||
| entity: | Core - Only available with recent search | |||
| conversation_id: | Core | |||
| place: | Sandbox and paid | Available | Advanced | |
| place_country: | Sandbox and paid | Available | Advanced | |
| point_radius: | geocode parameter | Sandbox and paid | Available | Advanced |
| bounding_box: | Sandbox and paid | Available | Advanced | |
| is:retweet | filter:retweets | Paid only | Available | Core |
| is:reply | Paid only | Available | Core | |
| is:quote | Sandbox and paid | Available | Core | |
| is:verified | Paid only | Available | Core | |
| -is:nullcast | Available | Advanced | ||
| has:hashtags | Paid only | Available | Core | |
| has:cashtags | Available | Advanced | ||
| has:links | filter:links | Sandbox and paid | Available | Core |
| has:mentions | Sandbox and paid | Available | Core | |
| has:media | filter:media | Sandbox and paid | Available | Core |
| has:images | filter:images, filter:twimg | Sandbox and paid | Available | Core |
| has:videos | filter:videos filter:native_video |
Sandbox and paid | Available | Core |
| has:geo | Paid only | Available | Advanced | |
| lang: | lang - can be used as an operator or a parameter | Sandbox and paid | Available | Core |
| has:profile_geo | Paid only | Available | ||
| profile_country | Paid only | Available | ||
| profile_locality | Paid only | Available | ||
| profile_region | Paid only | Available | ||
| proximity | Available | |||
| :( | Available | |||
| :) | Available | |||
| ? | Available | |||
| filter:periscope | Available | |||
| filter:safe | Available | |||
| list: | Available | Advanced | ||
| filter:replies | Available | |||
| filter:pro_video | Available | |||
| filter:social | Available | |||
| filter:trusted | Available | |||
| filter:follows | Available | |||
| filter:has_engagement | Available | |||
| include:antisocial | Available | |||
| include:offensive_user | Available | |||
| include:antisocial_offensive_user | Available | |||
| include:sensitive_content | Available | |||
| source: | Available | |||
| min_replies: | Available | |||
| min_retweets: | Available | |||
| min_faves: | Available | |||
| card_name: | Available | |||
| card_domain: | Available |