Search Tweets: recent search
Comparing Twitter API’s recent search endpoints
The v2 recent search endpoint will eventually replace the v1.1 search/tweets and Labs recent search endpoints. 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 endpoint, 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.
- Tweets and user data objects - The Twitter API v2 introduces a completely new design for encoding Tweet and user objects in JSON. Any code that parses v1.1 standard JSON payloads will need to be updated to work with the new formats.
Search query syntax - Twitter API v2 recent search endpoints use a search query syntax common to Labs, premium, and enterprise tiers of search. While there are some similarities, there are important differences between the standard search v1.1 and v2.
The following tables compare the various types of user lookup 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 |
Other migration resources
