Recent search v2 (retired)

Please note:

We graduated the Labs version of recent search into Twitter API v2: Early Access and retired it in November 2020.

Learn more about the new recent search endpoint, and review our migration resources to update to The New Twitter API.



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. 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


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.
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.