Recent search v2

Interested in exploring Labs?
The endpoints we release in Labs are previews of tools that may be released more broadly in the future, but will likely undergo changes before then. We encourage you to take that into consideration as you explore. Before getting started, please read more about Twitter Developer Labs.

Still using v1?
This page documents the current version of this endpoints, however you can still reference the previous version. You should also check out our version migration guide and review our changelog.

Overview

The Labs recent search endpoint represents the future implementation of Twitter search endpoints.  This Labs endpoint provides developers API access to public Tweets posted in the previous seven days. Labs recent search is a RESTful endpoint that receives a single search query and responds with matching Tweets. Tweets are delivered in reverse-chronological order, starting with the most recent Tweets. The endpoint uses OAuth 2.0 Bearer Token authentication. 

Up to 100 Tweets are returned per request, and pagination tokens are provided for paging through large sets of matching Tweets. Search queries can be created with over 15 "operators" that match on Tweet attributes, such as message keywords, hashtags, and URLs. Operators and rule clauses can be combined with boolean logic and parentheses to help refine the filter's matching behavior. Queries can be up to 512 characters long.

Labs recent search requests support the Labs fields and expansions parameters, and return the new Labs Tweet JSON design shared by the other Labs endpoints. 

Labs recent search supports navigating the Tweet archive by time ranges and Tweet ID ranges. Recent search is designed to support two common use patterns: 

  • "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 Labs recent search.
  • "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 focus on near real-time 'listening' for Tweets of interest. 

Learn more about these topics:

  • Building search queries - Labs recent search supports 15 operators that match on Tweet attributes. Queries can be short and simple or can be a complex set of filters with up to 512 characters. Building effective queries is an iterative process. 
  • Making search API requests -  Labs recent search requests are made using the HTTP GET method and "app-only" (Oauth 2.0) authentication. See the Labs recent search Quick Start guide for help with making your first request. To learn more about request parameters, see the API Reference for more details.
  • Pagination - Since most search queries will match more Tweets than can be returned in an API response, the Labs recent search endpoint will split the data payload into multiple 'pages.' The endpoint supports simple pagination methods to assemble Tweets collections.
  • Retrieving metrics -  Public Tweet and media metrics are available in the Tweets object. Public metrics refers to metrics that are available for anyone to access on the Twitter platform, such as number of likes and number of Retweets. To retrieve Tweet metrics, specify the public_metrics field in the request. To retrieve media metrics, specify the public_metrics field with the media expansion. 
     

If you are already familiar with the standard, premium, or enterprise search endpoints, be sure to check out the compare search endpoints guides.

 

 

Additional resources

  • Learn more about the new Developer Labs on the "About Labs" page
  • Learn more about What’s new.
  • Give feedback on Twitter Developer Labs.
  • Tell us about your experience using the Twitter Developer Labs endpoints by filling out this survey.