Search Tweets: recent search

This endpoint was recently graduated from Twitter Developer Labs, and is the replacement of the current Twitter seven-day search endpoints (v1.1 search/tweets and Labs recent search). If you are currently using either of these endpoints, you can use our migration materials to start working with this new endpoint.

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

Introduction

The Twitter API v2 recent search endpoint provides developers with API access to public Tweets posted over the last week. The endpoint, receiving a single search query and responding with matching Tweets. The recent search endpoint serves a wide variety of use cases; from providing fundamental research data, to near-real-time 'listening' applications, this endpoint can be used to collect Tweets related to topics of interest. 

This RESTful endpoint can deliver to 100 Tweets per request in reverse-chronological order, and pagination tokens are provided for paging through large sets of matching Tweets. 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 filter's matching behavior, which can add up to 512 characters long.

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.

Search Tweets supports navigating the Tweet archive 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. 
     

Twitter API v2 introduces several features: 

  • Tweet attributes will include Twitter Annotations about things and topics in Tweet messages. There are two new operators that enable you to match on entity and context annotations.  
  • More easily thread conversations with the conversation_id Tweet attribute. 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.
     

Soon, we plan to release a full-archive version which will make the entire archive of public Tweets available. The recent and full-archive search endpoints will share common design and features and are part of the Search Tweets group of endpoints.

To access this endpoint, you must have an approved developer account, and have activated the new developer portal. When authenticating, you must use keys and tokens from a developer App that is located within a Project. Learn more about getting access to the Twitter API v2 endpoints in our "Getting started" page.
 

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.