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
60 requests per 1 min with OAuth 2.0 Bearer Token

Sandbox premium
30 requests per 1 min with OAuth 2.0 Bearer Token

Both
10 requests per 1 sec with OAuth 2.0 Bearer Token

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    
Was this document helpful?
Thank you

Thank you for the feedback. We’re really glad we could help!

Thank you for the feedback. How could we improve this document?
Thank you for the feedback. Your comments will help us improve our documents in the future.