Please note:

We recently graduated recent search into Twitter API v2: Early Access and announced a 90-day deprecation window. We will retire this endpoint in mid-November 2020.

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

 

Frequently asked questions

The FAQ content is divided into two sections:

 

Product details

How does the Labs recent search endpoint compare to the standard, premium, and enterprise endpoints?

See our "compare endpoint" guides for comparisons of the following details:

  • Authentication
  • API request parameters
  • Query language
  • Tweets and Author JSON
  • Response pagination metadata
     

How far back in history does the Recent search endpoint provide Tweets?

The Labs recent search endpoint provides Tweets from the last seven days.
 

How many Tweets can I get from the Labs search endpoint?

You can consume up to 500,000 Tweets per month (months are calculated starting from the day you activate this preview).
 

How many rules/filters can I submit with each Search API request?

The Labs recent search endpoint operates with a single query at a time. The query can be up to 512 characters in length.
 

What is the delay/latency between when a Tweet is posted and it being available with the Recent search endpoint?

Tweets are available approximately 30 seconds after being posted. An error will be throw if you explicitly set the end_time request parameter to less than 30 seconds ago. If that parameter is not set, it defaults to 30 seconds before the time of the request.
 

How does the Recent search endpoint return the large volumes of data that are common with queries?

The Labs recent search endpoint implements a pagination mechanism to return potentially large volumes of data in easily consumable pieces.  Recent search request parameters include a max_results parameter that determines the maximum amount of Tweets to include in each response. The default for this parameter is 10, and has a supported range of 10-100. If the Recent search endpoint query has more than max_results to return, a next_token string is provided with each response's meta section until all the data is returned. This next_token token is added as a parameter to the subsequent call, along with your original query.

See the search pagination guide to learn more. 
 

In what order are the matching Tweets returned? 

Tweets are returned in reverse chronological order. Each response will contain an array of Tweets, starting with more recent Tweets first. Multiple pages are also delivered in reverse-chronological order:

  • The first Tweet in the first response will be the most recent one matching your query.
  • The last Tweet in the last response will be the oldest one matching your query.
     

Troubleshooting FAQ

If you are having a problem working with the Labs recent search endpoint, the purpose of this section is to help you understand and resolve the issue. 

All Labs endpoints share a common set of error responses. When errors are triggered, Labs endpoints return an HTTP error code, along with response JSON that describes the error.  See the Labs documentation on error codes for more information on error codes and general errors returned. 

After successfully authenticating, most search errors are of the "400 Bad Request" type. These errors mean that there was some issue with the set of parameters in the request. These could be triggered by a query with invalid syntax, invalid start and end times, and a host of other possibilities. 
 

I am having problems with "bad requests". How can I avoid these errors?

Labs error responses usually provide enough detail to quickly understand the underlying issue. For example, if start_time is set to a time more than seven days ago, the following type of troubleshooting information is returned:

  {
    "errors": [
        {
            "parameters": {
                "start_time": [
                    "2019-12-16T18:15Z"
                ]
            },
            "message": "Invalid 'start_time':'2019-12-16T18:15Z'. 'start_time' must be on or after 2019-12-24T03:48Z"
        }
    ],
    "type": "https://api.twitter.com/labs/1/problems/invalid-request",
    "title": "Invalid Request",
    "detail": "One or more parameters to your request was invalid."
}


This JSON identifies the request parameters that caused the error. Depending on what request parameter you are working with, here are some general guidelines to help with troubleshooting:

  • query: Indicates that there is a syntactic problem with your query. When queries are made, the Labs recent search endpoint provides validation of the query's format. Could be caused by many things including a misspelled or unsupported Operator, mismatched parentheses, or unescaped quotation marks. To learn more about writing queries, see the Building queries guide
  • start_time: Can not be earlier then 7 days before the time of the request. Defaults to 7 days before the request. All timestamps are in UTC. 
  • end_time: Can not be within 30 seconds of the time of the endpoint request. Defaults to 30 seconds before the time of the request. All timestamps are in UTC. 
  • since_id: Must be a valid Tweet ID from the previous 7 days. To learn more about pagination see the Labs search pagination guide.
  • Do not mix since_id with  start_time and end_time parameters. You can navigate the seven day public archive by either timestamps or Tweet IDs, but not both in the same request. Default mode is to work with time periods, where start_time defaults to seven days ago, and end_time defaults to 30 seconds before the request. since_id (and until_id) are provided for navigating by Tweet ID. 
  • max_results: Supports a range of 10 to 100. 

See the Recent search API Reference for more request parameter documentation. 

 

I am having problems authenticating. How can I avoid authorization errors?

The Labs recent search endpoint is authenticated using OAuth 2.0 Bearer token (also known as application-only authentication). Make sure your OAuth token is correct and valid, and is generated using the API Key and Secret tokens from the Twitter developer app with which you set up your Recent Search preview via the Labs dashboard

How can I check my usage and rate limits?

To check connection limits response will return three headers: x-rate-limit-limit, x-rate-limit-remaining and x-rate-limit-reset headers. This is useful to understand how many times you can use the rule endpoint, and how many reconnections attempts are allowed for the streaming endpoint.

  • x-rate-limit-limit indicates the number of allotted requests your client is allowed to make during the 15-minute window.
  • x-rate-limit-remaining indicates the number of requests made so far in the 15-minute window.
  • x-rate-limit-reset is a UNIX timestamp indicating when the 15-minute window will restart, resetting x-rate-limit-remaining to zero.
     

The recent search endpoint does not currently report usage data. To check how many Tweets have been delivered, your code can implement a metering logic, so that consumption can be measured and paused if needed.

 

What if some Tweets are missing? I was expecting them to be returned by my query, but they weren't.

Most of the time, missing Tweets indicate that your query is more restrictive than intended. If you don't see a Tweet in your response payload that you were expecting, we suggest you check the following:

  • Make sure you are using the correct operators, as some operators are more restrictive than others. For example, -has:media filters out all media; sometimes, an exact phrase match can filter out more Tweets than intended.
  • If you’re grouping operators, check that the grouping is logically correct, and that operators do not invalidate the entire rule. You can test this by breaking down those groups into separate rules, and check if a Tweet matches that subset.
  • The missing Tweet needs to originate from a public account. The recent search endpoint can only return Tweets from accounts that are public at the time of the publishing of the Tweet. You can check to see if a Tweet was published while a user was private by using Twitter's Advanced Search and entering a search query that should match that Tweet. If the Tweet doesn't show up in the results, you know that the Tweet was published while the user was private. 

 

Additional resources

Was this document helpful?

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.