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.
Comparing Labs and premium search endpoints
If you have been working with the premium search endpoint, the goal of this guide is to help you understand the similarities and differences between the premium and Labs search endpoints. If you have premium-based code that you want to use with Labs, read on to see what that conversion will entail.
Here we are comparing these Twitter search endpoints:
- 30-day search: https://api.twitter.com/1.1/tweets/search/30day/:label.json
- Full-archive search: https://api.twitter.com/1.1/tweets/search/fullarchive/:label.json
- Labs recent search: https://api.twitter.com/labs/1/tweets/search
One fundamental difference between the two is that the Labs recent search endpoint does not include a counts endpoint.
See these sections to learn more about the similarities and differences between Labs and premium search endpoints.
If you have been working with the premium search APIs and making OAuth 2.0 Bearer Token requests, then your code is likely ready to authenticate with the Labs recent search endpoint. If you have have been making requests using a OAuth 1.0a, you will need to switch to OAuth 2.0 Bearer Token.
The boolean syntax (how rule clauses are OR'ed together, AND'ed together, and excluded/negated) is identical. The only difference is the set of operators supported by the search endpoint. See this table for more information on what operators are available for the Labs, premium, and enterprise tiers.
Premium search supports both GET and POST HTTP request methods. The Labs recent search search endpoint supports only GET requests.
The premium and Labs search endpoints have a similar set of request parameters, although Labs adds support for making requests based on Tweet IDs.
Twitter Developer Labs are introducing new JSON designs for the objects returned by the APIs, including Tweet and User objects. The Labs JSON formats represent the future JSON formats that Twitter APIs will return. We are taking this opportunity to update the JSON key names of common objects and their attributes. Here are some examples of these changes:
- At the JSON root/top-level, the premium search endpoint returns Tweet objects in a results array, while Labs search returns a data array.
- Instead of using the term statuses, the term tweet will be used.
- Many legacy and deprecated fields, such as contributors and user.translator_type are being removed.
- Instead of using both favorites (in Tweet object) and favourites (in User object), Labs uses the term like.
- Lab formats are adopting the convention that JSON values with no value (e.g., null) are not written to the payload. Tweet and User attributes are only included if they have a non-null value.
To see the new JSON field names, see the response section of the Labs recent search API Reference guide.
With premium (and enterprise) search, response payloads include a
next token for cases when more "pages" of data are available. These next tokens are included in requests for more data.
With Labs recent search, response payloads include a meta section with a
next_token when another page of data is available, and
oldest_id Tweet IDs to support polling use cases.
- Get started with the Labs recent search Quick Start guide.
- Review the Labs recent search API Reference.
- Review the available query operators available with Labs recent search.
- Have you worked with the standard or premium search endpoint? Then check out these guides comparing Labs search with the standard and premium versions.