Comparing Twitter API’s Search Tweets endpoints
The v2 Search Tweets endpoint will eventually replace the standard v1.1 search/tweets endpoint, Labs recent search, 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.
These guides will focus on the following areas:
- API request parameters - The Twitter API v2 endpoint introduces a new set of request parameters. While some parameters will be familiar, especially for those integrating with Labs, there are many important differences such as the introduction of the fields and expansions parameters.
- New JSON format - Twitter API v2 introduces a completely new JSON format. Any code that parses v1.1 standard, premium, and enterprise JSON payloads will need to be updated to work with the new formats.
- Search query syntax - Twitter API v2 Search Tweets endpoints use a search query syntax similar to the Labs, premium, and enterprise Search Tweets offerings. However, there are important differences between the standard v1.1 search/tweets endpoint and v2 endpoints.
- App and Project requirements - To access the Twitter API v2, you will need to use credentials from a developer App that is associated with a Project.
This page contains two comparison tables:
Recent search comparison
The following table compares the various types of recent search endpoints:
| Description | Standard v1.1 | Labs v2 | Twitter API v2 |
| Host domain | https://api.twitter.com | https://api.twitter.com | https://api.twitter.com |
| Endpoint path | /1.1/search/tweets.json | /labs/2/tweets/search | /2/tweets/search/recent |
| Authentication | OAuth 1.0a User Context OAuth 2.0 Bearer Token |
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 | 7 days |
| HTTP methods supported | GET | 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 |
225 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) | 100 (10) |
| Tweet JSON format | Native (soon to be referred to as 'legacy') | Labs v2 (determined by fields and expansions request parameters, not backward-compatible with v1.1 formats) | Twitter API v2 (determined by fields and expansions request parameters, not backward-compatible with v1.1 formats) |
| 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 | data |
| JSON key name for pagination | search_metadata.next_results | meta.next_token | meta.next_token |
| Supports navigating archive by time range | ✔ | ✔ | ✔ |
| Time resolution of time-based requests | day | second | second |
| Timezone | UTC | UTC | UTC |
| Supports navigating archive by Tweet ID | ✔ | ✔ | ✔ |
| Request parameters for navigating by Tweet ID | since_id (polling) max_id |
since_id (polling) until_id |
since_id (polling) until_id |
| Request parameter for pagination | Provides URL-encoded query | next_token | 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://api.twitter.com | https://gnip-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 | Maxiumum: 500 Default: 100 |
Maxiumum: 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 |
| Supports navigating archive by time range | ✔ | ✔ | ✔ |
| Time resolution of time-based requests | second | second | second |
| Timezone | UTC | UTC | UTC |
| Supports navigating archive by Tweet ID | ✔ | ||
| Request parameters for navigating by Tweet ID | since_id (polling) 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 | ✔ |
