Frequently asked questions

General Search Tweet API questions

The number of Tweets I receive with the data endpoint doesn't match the number of Tweets identified by the counts endpoint. Why is this the case?

There is a known difference between results provided by the counts endpoint and the data endpoint. You may see a discrepancy in your results because the counts endpoint is pre-compliance (meaning that it does not account for things like deleted Tweets, scrub geo, etc.) whereas the data endpoint is compliant at the time of delivery and accounts for all compliance events. For further reference, please go to this document on our support site.

I didn't receive a Tweet that should match my query. Why?

There are a few different reasons why this might have happened, including:

  1. the Tweet you expected to see is from a protected account.
  2. because the data endpoint accounts for all compliance events (meaning that deleted Tweets, scrubbed geos, etc. will not be included in the response).

My query matched a Tweet but includes a keyword that I negated. Why is this happening?

This is likely due to a wrong usage of our premium rules & filtering. Please review our documentation here and ensure you understand the restrictions around building rules.

Are there any libraries that I can use to get started using the Search Tweet APIs?

Yes, there are, including:

  • Tweepy - good for using the standard search/tweets product (Python)
  • Twitter API - good for using both the standard and premium Search Tweet APIs (Python)
  • Search Tweets Python and Search Tweets Ruby - two good tools that can be used for both premium and enterprise Search Tweet APIs

All of the libraries that we directly support can be found on our TwitterDev GitHub page:

There are other third-party libraries that may also be helpful; however, please note that some of these may not work with our premium and enterprise products. 

Will I ever receive less volume of Tweets than the value I set as the maxResults in my request to the data endpoint?

The only time that a page will include less than the number of Tweets specified by maxResults  will be the final page of results.

In what order are the matching Tweets returned?

Tweets are returned in reverse chronological order. For example, the first page of results will show the most recent Tweets that match the query, pagination will continue until the results posted dates get to the fromDate initially requested.



Can I use twurl to use the premium Search Tweet API via the command line?

Yes, twurl supports the application-only authentication type that the premium search product uses. Follow the step-by-step tutorial on Twurl to get started: $ twurl --help

Make sure to check out this video and the repository's GitHub page

What is the sandbox? Is this real data?

The “sandbox” is the free version of either the Search Tweets: 30-day or Full-Archive, the data returned are real Tweets that match the query for the related timeframe.

What happens when I upgrade from sandbox to premium?

When you upgrade to the next package level, additional requests, higher count pagination, as well as the enrichments and additional query operators become available immediately.

  • You can review additional query operators here
  • You can review additional enrichments available here

Which operators are available in the sandbox vs. paid search premium tiers?

Please refer to our documentation chart for which operators are available.

  • Free search sandbox tier: a limited set of operators
  • Paid search premium tiers: includes is:retweet, is:verified, has:hashtags, has:geo, has:profile_geo, profile_country, profile_locality, profile_region


How much does the premium Search Tweet API cost?

You can learn more about the different pricing and access levels on our premium Search Tweet API pricing page.

How can I check my usage?

API request usage (including pagination) is tracked on the developer dashboard.

There, you are able to access your request usage per current or previous (monthly) periods, as well as per 30 day period, 24 hours and 120 minutes. The projected requests look at previous usage patterns to determine the remaining requests needed in the current period.

What counts as a 'request' for the premium Search Tweets' endpoint?

Any request to the 30-day or Full-Archive endpoint, including each page in the pagination, as well as any /counts calls will be counted as a request.

One or several operators aren't working. Why is this the case?

Some of our operators (e.g. the $ operator) are only available with the enterprise version of the product. The sandbox tier also offers a limited amount of operators. Please review our documentation here for a full list of available operators per product.

How long will it take to have my Twitter developer account approved?

We continue to work through the applications as quickly as we can. Hang tight - we are just as excited to see what you are going build!

I have a question that hasn’t been answered in the documentation.

Please check our forums to see if your question was answered there. If you still can’t find your answer, please submit a post to the forum.


Error troubleshooting guide

Code 404 - Not Found

  1. Please ensure you are using the right parameters for each endpoint (e.g. the bucketsfield can only be used with the counts endpoint, not the data endpoint).
  2. Please double check the :product :account_name and :label fields are correct. You can find your :label field in the GNIP Console (enterprise customers only).