The endpoints we release in Labs will be previews and are likely to change before they are released broadly, so we encourage you to take that into consideration as you build. Before getting started, we encourage you to read more about Twitter Developer Labs.

As we gather feedback and iterate on this API, we expect future versions to provide additional features. We would also appreciate feedback on new features introduced in Labs, such as the ability to specify the amount of Tweet attributes returned using the format request parameter. 
 

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 format 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. To learn more about building search queries, see the Buiding queries guide.
  • 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. To learn more, see this guide on Labs recent search pagination.
     

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.