1

Today, we’re excited to launch two new endpoints, recent Tweet counts and full-archive Tweet counts, to the Twitter API v2. These endpoints are valuable for a number of reasons, but most commonly, to understand the size of the conversation, or the amount of data a query will return, prior to submitting a search request.

All developers with access to the Twitter API v2 can use the recent Tweet counts endpoints, and developers with access that includes full-archive search, can use the full-archive Tweet counts endpoint (currently, only available on the Academic Research product track).

The Twitter API v2 currently supports two search endpoints, recent search and full-archive search. These endpoints allow developers and researchers to get public Tweets that match their query. Sometimes, before using the recent search or full-archive search endpoints to get Tweets for a query, developers and researchers may first want to get a sense of how many Tweets their request will return. This can help you further refine your search queries to filter for the precise Tweets or conversation that you may be looking for.

The Tweet counts endpoints provide you with the Tweet volume that a search query will return. These endpoints can also be used to:

  • Understand how a topic has trended over time
  • Estimate how many Tweets your search query will return
  • Help you be more cognizant of the usage of your monthly Tweet cap

What’s launching today

We are launching two new endpoints:

Recent Tweet counts

This endpoint gives you the Tweet counts for a search query for Tweets from the last 7 days and is available to everyone that has access to the Twitter API v2.

Full-archive Tweet counts

This endpoint gives you the Tweet counts for a search query for Tweets from the entire archive of public Tweets. This endpoint is currently only available as part of the Academic Research product track.

Getting started

In order to get started with these endpoints, you need to make sure you have an approved Twitter developer account. Additionally, in order to use the full-archive Tweet counts endpoint, you need to be eligible and apply for the Academic Research product track.

Once you have access, you can use the quick start guides available for the recent Tweet counts and the full-archive Tweet counts to connect with these endpoints. We also have code samples available in Python, R, JavaScript etc. in our TwitterDev Github repository to help you get started quickly. Just add the appropriate bearer token from your app to the code samples in order to connect to these endpoints.

Support for these endpoints in libraries

Sample request and response

A sample request and response for the recent Tweet counts endpoint looks like:

Request (cURL)

curl --request GET 'https://api.twitter.com/2/tweets/counts/recent?query=lakers&granularity=day' --header 'Authorization: Bearer XXXXX'

Response

{
   "data": [
       {
           "end": "2021-05-26T00:00:00.000Z",
           "start": "2021-05-25T00:00:00.000Z",
           "tweet_count": 10352
       },
       {
           "end": "2021-05-27T00:00:00.000Z",
           "start": "2021-05-26T00:00:00.000Z",
           "tweet_count": 199865
       },
       {
           "end": "2021-05-28T00:00:00.000Z",
           "start": "2021-05-27T00:00:00.000Z",
           "tweet_count": 43186
       },
       {
           "end": "2021-05-29T00:00:00.000Z",
           "start": "2021-05-28T00:00:00.000Z",
           "tweet_count": 179222
       },
       {
           "end": "2021-05-30T00:00:00.000Z",
           "start": "2021-05-29T00:00:00.000Z",
           "tweet_count": 35808
       },
       {
           "end": "2021-05-31T00:00:00.000Z",
           "start": "2021-05-30T00:00:00.000Z",
           "tweet_count": 116632
       },
       {
           "end": "2021-06-01T00:00:00.000Z",
           "start": "2021-05-31T00:00:00.000Z",
           "tweet_count": 50931
       },
       {
           "end": "2021-06-02T00:00:00.000Z",
           "start": "2021-06-01T00:00:00.000Z",
           "tweet_count": 29037
       }
   ],
   "meta": {
       "total_tweet_count": 665033
   }
}

Note: The default granularity is hour i.e. if you do not specify the granularity parameter, the default aggregation of the Tweet counts returned from these endpoints will be hourly. If you want the Tweet volume to be aggregated by day, you will have to specify that using the granularity parameter, as shown in the example above.

Also, similar to the recent search and full-archive search endpoints, if you do not specify a start_time and end_time, the default time window will be the last 7 days (for recent Tweet counts) and 30 days (for full-archive Tweet counts).

We hope that developers and researchers will find value with these endpoints. If you have questions about this endpoint, feel free to ask in our Twitter community forums

9 Likes