These endpoints are the replacements of the premium and enterprise Search API - Counts endpoints. We have not announced any deprecations or retirements yet, so no need to worry about migrating. If you do currently use one of these legacy endpoints, do consider exploring the new v2 Tweet counts functionality to see what's changing.

Learn more about the new Twitter API v2: Early Access.

Introduction

The v2 Tweet counts endpoints allow developers to understand and retrieve the volume of data for a given query.  This can be beneficial for a number of reasons, including:

  • Understand the Tweet volume for a keyword to build visualizations, such as trendlines.
  • Understanding the time period in which an event or conversation occurred, to ensure your query captures the relevant data
  • Understanding how many Tweets a search query will return, in order to refine your query, before using the recent search or full-archive search endpoints.
    Please note: The counts will not always match the result that will be returned from search endpoints because the search endpoints go through additional compliance that the counts endpoints do not go through
  • Understanding the size of the conversation around a topic, without actually having to pull the raw data, and put Tweets against your monthly Tweet cap. 

 

Recent Tweet counts

The recent Tweet counts endpoint allows you to programmatically retrieve the numerical count of Tweets for a query, over the last seven days. This endpoint is available via the standard and academic research product tracks and uses the OAuth 2.0 Bearer Token for authentication.

You can specify a query of up to 512 characters (using the core operators available in the standard product track) and specify the granularity (which can be day, hour or minute) as well as the time period for which you need the Tweet counts (using the start_time and end_time parameters). For example, you could use the recent Tweet counts endpoint to understand the number of Tweets per day, over the last 7 days, that contained the word ‘Twitter’.

The default time granularity that this endpoint uses is hour, which means if you do not specify the granularity parameter, the endpoint will give you the Tweet counts per hour, for the last 7 days.
 

Full-archive Tweet counts

Academic Research product track only

The full-archive Tweet counts endpoint allows you to programmatically retrieve the numerical count of Tweets for a query, from the entire archive of public Tweets. Currently, this endpoint is only available in the Academic Research product track and uses the OAuth 2.0 Bearer Token for authentication.

You can specify a query of up to 1024 characters, using both the core and advanced sets of operators (because this endpoint is available in the Academic Research product track) and specify the granularity and time period for which you need the Tweet counts, as noted above in section on recent Tweet counts. For example, you could use the full-archive Tweet counts endpoint to see the number of Tweets for the hashtag #SOSHurricaneHarvey per day between August and September 2017.

Please note: The counts endpoint paginates at 31 days per response. For example, setting a day granularity, will return the count of results per day for 31 days per page.  Setting an hour granularity, will return the count of results per hour for 744 (31 days x 24 hours) hours per page.  If you do not specify the granularity and time period, this endpoint will give you Tweet counts for a query per hour, for the last 30 days.

 

Learn more about getting access to the Twitter API v2 endpoints in our getting started page.

 

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.