These endpoints are the replacements of the standard v1.1 seven-day search endpoint and the premium and enterprise full-archive search products. You can see an overview of the Search Tweets offerings via our search overview. If you are currently using any of these, you can use our migration materials to start working with these new endpoint.

Learn more about the new Twitter API v2: Early Access.

Introduction

Searching for Tweets is an important feature used to surface Twitter conversations about a specific topic or event. While this functionality is present in Twitter, these endpoints provide greater flexibility and power when filtering for and ingesting Tweets so you can find relevant data for your research more easily; build out near-real-time ‘listening’ applications; or generally explore, analyze, and/or act upon Tweets related to a topic of interest. 

We offer two endpoints that allow you to search for Tweets: Recent search and full-archive search. Both of these REST endpoints share a common design and features, including their use of a single search query to filter for Tweets around a specific topic. These search queries are created with a set of operators that match on Tweet and user attributes, such as message keywords, hashtags, and URLs. Operators can be combined into queries with boolean logic and parentheses to help refine the queries matching behavior. 

Once you’ve set up your query and start receiving Tweets, these endpoints support navigating the results both by time and Tweet ID ranges. This is designed to support two common use cases: 

  • Get historical: Requests are for a period of interest, with no focus on the real-time nature of the data. A single request is made, and all matching data is delivered using pagination as needed. This is the default mode for Search Tweets.
  • Polling or listening: Requests are made in a "any new Tweets since my last request?" mode. Requests are made on a continual basis, and typically there is a use case focused on near real-time 'listening' for Tweets of interest.
     

To access these endpoints, you must have an approved developer account. When authenticating your request, you must use keys and tokens from a developer App that is located within a Project. Many operators and other functionality are exclusive to the Academic Research product track, meaning that you must use keys and tokens from an App within an Academic Research Project to utilize the additional functionality. You can learn more about this in the endpoint sections below.

Learn more about getting access to the Twitter API v2 endpoints in our getting started page.
 

Recent search

The recent search endpoint allows you to programmatically access filtered public Tweets posted over the last week, and is available via the Standard and Academic Research product tracks.

You can authenticate you requests with OAuth 2.0 Bearer Token, but if you would like to receive private metrics, or a breakdown of organic and promoted metrics within your Tweets, you will have to use OAuth 1.0a User Context and pass user Access Tokens that are associated with the user that posted the Tweet.

This endpoint can deliver up to 100 Tweets per request in reverse-chronological order, and pagination tokens are provided for paging through large sets of matching Tweets. 

When using the Standard product track, you can use the basic set of operators and can make queries up to 512 characters long. When using the Academic Research product track, you have access to additional operators and can make queries up to 1024 characters long. 
 

Full-archive search

Academic Research product track only

At this time, the v2 full-archive search endpoint is only available via the Academic Research product track. The endpoint allows you to programmatically access public Tweets from the complete archive dating back to the first Tweet in March 2006, based on your search query.

You can authenticate your requests to this endpoint using OAuth 2.0 Bearer Token, and the Bearer Token must come from an App that is within an Academic Research Project. Since you cannot make a request on behalf of other users (OAuth 1.0a User Context) with this endpoint, you will not be able to pull private metrics

This endpoint can deliver up to 500 Tweets per request in reverse-chronological order, and pagination tokens are provided for paging through large sets of matching Tweets. 

Since this endpoint is only available to the Academic Research product track, you have access to the full set of search operators and can make queries up to 1024 characters long.
 

Introduction

The recent and full-archive search REST endpoints are part of the Search Tweets group of endpoints, meaning they share a common design and features. These endpoints receive a single search query and respond with matching Tweets, meaning they serve a wide variety of use cases; from providing fundamental research data, to enabling the buildout of a near-real-time 'listening' application, to exploring Tweets related to topics of interest.

To learn more about the specific recent search and full-archive search endpoints, please review their respective sections below. 

Search queries are created with operators that match on Tweet and user attributes, such as message keywords, hashtags, and URLs. Operators and rule clauses can be combined into queries with boolean logic and parentheses to help refine the query's matching behavior.

Once you’ve set up your query and start receiving Tweets, these endpoints support navigating the results both by time and Tweet ID ranges. This is designed to support two common use cases: 

  • "Get historical": Requests are for a period of interest, with no focus on the real-time nature of the data. A single request is made, and all matching data is delivered using pagination as needed. This is the default mode for Search Tweets.
  • "Polling" or "listening": Requests are made in a "any new Tweets since my last request?" mode. Requests are made on a continual basis, and typically there is a use case focused on near real-time 'listening' for Tweets of interest.
     

The new Twitter API v2 version introduces several new features: 

  • Tweet objects contain Annotations that include information about the entities and topics in those Tweets’ messages. There are also two new operators that enable you to match on entity and context annotations.  
  • More easily thread conversations with the conversation_id field. A new conversation_id operator is also available to match on Tweets within a conversation on Twitter.
  • Select specific Tweet, user, media, poll, or geo object attributes of interest with the fields request parameter.
  • Include related objects with the expansions parameter. For example, Tweets can include the user's author_id if requested with the corresponding tweet.fields parameter. If you include the expansions=author_id parameter you can request additional user fields such as their bio description or pinned Tweet.
     

To access these endpoints, you must have an approved developer account, and have activated the new developer portal. When authenticating your request, you must use keys and tokens from a developer App that is located within a Project. The Advanced operators and other functionality are exclusive to the Academic Research product track, meaning that you must use keys and tokens from an App within an Academic Research Project to utilize the additional functionality. You can learn more about this in the endpoint sections below. 

Learn more about getting access to the Twitter API v2 endpoints in our "Getting started" page.
 

Recent search

The recent search endpoint allows you to programmatically access filtered public Tweets posted over the last week, and is available via the Standard and Academic Research product tracks.

You can authenticate you requests with OAuth 2.0 Bearer Token, but if you would like to receive private metrics, or a breakdown of organic and promoted metrics within your Tweets, you will have to use OAuth 1.0a User Context and pass user access tokens that are associated with the user that posted the Tweet.

This endpoint can deliver up to 100 Tweets per request in reverse-chronological order, and pagination tokens are provided for paging through large sets of matching Tweets. 

When using the Standard product track, you can use the Core operators and can make queries up to 512 characters long. When using the Academic Research product track, you have access to both the Core and Advanced operators and can make queries up to 1024 characters long. 
 

Full-archive search
 

Academic Research product track only

At this time, the v2 full-archive search endpoint is only available via the Academic Research product track. The endpoint allows you to programmatically access public Tweets from the complete archive dating back to the first Tweet in March 2006, based on your search query.

You can authenticate your requests to this endpoint using OAuth 2.0 Bearer Token, and the Bearer Token must come from an App that is within an Academic Research Project. Since you cannot make a request on behalf of other users (OAuth 1.0a User Context) with this endpoint, you will not be able to pull private metrics

This endpoint can deliver up to 500 Tweets per request in reverse-chronological order, and pagination tokens are provided for paging through large sets of matching Tweets. 

Since this endpoint is only available to the Academic Research product track, you have access to both the Core and Advanced operators, and can make queries up to 1024 characters long.
 

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.