Overview
Comparing X API’s Search Posts endpoints
The v2 Search Tweets endpoint will eventually replace the standard v1.1 search/posts endpoint and enterprise Search API. If you have code, apps, or tools that use an older version of a X search endpoint and are considering migrating to the newer X 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 | X API v2 |
|---|---|---|
| Host domain | https://api.x.com | https://api.x.com |
| Endpoint path | /1.1/search/tweets.json | /2/tweets/search/recent |
| Authentication | OAuth 1.0a User Context OAuth 2.0 App-Only | OAuth 1.0a User Context OAuth 2.0 Authorization Code with PKCE OAuth 2.0 App-Only |
| Timestamp format | YYYYMMDD | YYYY-MM-DDTHH:mm:ssZ ISO 8601 / RFC 3339 |
| Returns Posts 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 App-Only | Basic: 60 requests per 15 min with OAuth 2.0 App-Only 60 requests per 15 min with OAuth 1.0a User Context 60 requests per 15 min with OAuth 2.0 Authorization Code with PKCE Pro: 450 requests per 15 min with OAuth 2.0 App-Only 180 requests per 15 min with OAuth 1.0a User Context 180 requests per 15 min with OAuth 2.0 Authorization Code with PKCE |
| Offers fully unwound URLs | ✔ | |
| Maximum Posts per response (default) | 100 (15) | 100 (10) |
| Post JSON format | Standard v1.1 format | X 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 X 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 Post object | ✔ | |
| Supports the conversation_id operator and field | ✔ | |
| Provides Post edit history | ✔ | ✔ |
| JSON key name for Post 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 Post 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 | Enterprise | X API v2 |
|---|---|---|
| Host domain | https://gnip-api.x.com | https://api.x.com |
| Endpoint path | /search/fullarchive/accounts/:account_name/:label | /2/tweets/search/all |
| Authentication | Basic auth | OAuth 2.0 App-Only |
| Timestamp format | YYYYMMDDHHMM | YYYY-MM-DDTHH:mm:ssZ ISO 8601 / RFC 3339 |
| Returns Posts that are no older than | The full archive since March 2006 | The full archive since March 2006 |
| HTTP methods supported | GET POST | GET |
| Default request rate limits | 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 App-Only 1 requests per 1 sec with OAuth 2.0 App-Only |
| Offers fully unwound URLs | ✔ | ✔ |
| Posts per response | Maximum: 500 Default: 100 | Maximum: 500 Default: 10 |
| Post JSON format | Native Enriched or Activity Streams format | X 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 Post object | ✔ | |
| Supports the conversation_id operator and field | ✔ | |
| Provides Post edit history | ✔ | ✔ |
| JSON key name for Post data array | results | data |
| JSON key name for pagination | next | meta.next_token |
| Time resolution of time-based requests | second | second |
| Timezone | UTC | UTC |
| Supports navigating archive by Post ID | ✔ | |
| Request parameters for navigation by time | fromDate toDate | start_time end_time |
| Request parameters for navigating by Post ID | since_id until_id | |
| Request parameter for pagination | 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, enterprise, and v2) of search Posts differ in which operators are available, and also have varying levels of operator availability within each version, which are explained below.
Enterprise
- There are no sub-tiers of enterprise operators
X API v2
- **Free: **Available when using any Project
- Basic: Available when using any Project
- Pro: Available when using a Project
- Enterprise: Available when using a Project
You can learn more about each of these sets of operators in their respective guides:
Now that we understand the different operator levels within X API v2, here is the table that maps out operator availability for search Posts (note that if the cell is left blank, the operator is not available):
| Search operator | Standard | Enterprise | v2 |
|---|---|---|---|
| keyword | Available q:keyword | Available | Basic & Pro |
| emoji | Available q:😄 | Available | Basic & Pro |
| “exact phrase” | Available | Available | Basic & Pro |
| # | Available | Available | Basic & Pro |
| $ | Available | Available | Pro |
| @ | Available | Available | Basic & Pro |
| from: | Available | Available | Basic & Pro |
| to: | Available | Available | Basic & Pro |
| url: | Available | Available | Basic & Pro |
| retweets_of: | Available | Basic & Pro | |
| context: | Basic & Pro | ||
| entity: | Basic & Pro - Only available with recent search | ||
| conversation_id: | Basic | ||
| place: | Available | Pro | |
| place_country: | Available | Pro | |
| point_radius: | geocode parameter | Available | Pro |
| bounding_box: | Available | Pro | |
| is:retweet | filter:retweets | Available | Basic & Pro |
| is:reply | Available | Basic & Pro | |
| is:quote | Available | Basic & Pro | |
| is:verified | Available | Basic & Pro | |
| -is:nullcast | Available | Pro | |
| has:hashtags | Available | Basic & Pro | |
| has:cashtags | Available | Pro | |
| has:links | filter:links | Available | Basic & Pro |
| has:mentions | Available | Basic & Pro | |
| has:media | filter:media | Available | Basic & Pro |
| has:images | filter:images, filter:twimg | Available | Basic & Pro |
| has:videos | filter:videos filter:native_video | Available | Basic & Pro |
| has:geo | Available | Pro | |
| lang: | lang - can be used as an operator or a parameter | Available | Basic & Pro |
| has:profile_geo | Available | ||
| profile_country | Available | ||
| profile_locality | Available | ||
| profile_region | Available | ||
| proximity | Available | ||
| :( | Available | ||
| :) | Available | ||
| ? | Available | ||
| filter:periscope | Available | ||
| list: | Available | Pro | |
| 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 |
Other migration resources
Check out some sample code for these endpoints