Tweet metrics v1

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.

Overview

The metrics endpoint preview allows developers to access engagement metrics for any Tweet or list of Tweets from owned/authorized accounts. By metrics, we mean the total count of impressions, Retweets, Quote Tweets, likes, replies, video views, and video view quartiles for each Tweet specified in the request.

Currently, both private and public metrics can be requested for owned/authorized Tweets only. Developers are required to authenticate using OAuth 1.0a user context authorization. If you need to generate an access token and secret for the Tweet owner, you can do so with the 3-legged OAuth process. Public metrics for unowned Tweets (such as Retweets, likes, and replies) can be accessed via GET /tweets.

As we gather feedback and iterate on this API, we expect future versions to include even more metrics on owned Tweets and media.
 

Useful jargon to understand

When working with the Labs metrics endpoint, understanding the following terminology to help you navigate the functionality more easily. 

  • An owned account is the Twitter account linked to your Twitter developer app. 
  • An authorized account is a Twitter account that has authorized your Twitter developer app by granting it access to that account (any app permission level will permit access to Tweet metrics). This can be achieved using the 3-legged OAuth process. 
  • Public metrics refers to metrics that are available for anyone to access on Twitter, such as number of likes and number of Retweets. 
  • Private metrics refers to metrics that are not available for anyone to access on Twitter, such as number of impressions and video view quartiles.

     

GET /tweets/metrics/private

GET /tweets/metrics/private supports the ability to retrieve Tweet engagement data and delivers the following metrics:

  • impressions 
  • Retweets 
  • Quote Tweets 
  • likes 
  • replies 
  • video views 
  • video view quartiles


These metrics are only available for owned/authorized Tweets that have been created within the past 30 days. GET /tweets/metrics/private does not support querying specific metrics and, instead, automatically returns all available metrics.

Impressions represent the number of times that a given Tweet has been viewed on the Twitter platform. This metric will return the total count of impressions from both organic and paid context.

Tweet metrics and media metrics are returned in different sections of the response payload. Video view quartiles are only made available when the requester is also the author of the media.


Available metrics

The table below describes the types of metrics that can be accessed through the metrics endpoint. The metrics returned are consistent with the counts shown publicly on Twitter.

Please note: All metrics require user-context authentication at this time.

 

Metric API Representation Description
Impressions data.tweet.impression_count

A count of how many times the Tweet has been viewed (not unique by user).

This will return the total count of impressions from both organic and paid contexts.

Known issue: for Tweets used in promoted campaigns, many will be missing impressions from those campaigns and only organic impressions will be counted. We expect to address this in an update soon.
Retweets data.tweet.retweet_count A count of how many times the Tweet has been Retweeted. Please note: This does not include Quote Tweets (“Retweets with comment”).

This will return the total count of Retweets from both organic and paid contexts, in order to maintain consistency with the counts shown publicly on Twitter.
Quote Tweets data.tweet.quote_count A count of how many times the Tweet has been Retweeted with a new comment (message). Please note: This does not include Retweets.

This will return the total count of Quote Tweets from both organic and paid contexts.
Likes data.tweet.like_count A count of how many times the Tweet has been liked.

This will return the total count of likes from both organic and paid contexts, in order to maintain consistency with the counts shown publicly on Twitter.
Replies data.tweet.reply_count A count of how many times the Tweet has been replied to.

This will return the total count of replies from both organic and paid contexts, in order to maintain consistency with the counts shown publicly on Twitter.
Video views data.video.view_count A count of how many times the video included in the Tweet has been viewed.

This is the number of video views aggregated across all Tweets in which the given video has been posted. That means that the metric includes the combined views from any instance where the video has been Retweeted or reposted in separate Tweets.

This will return the total count of video views from both organic and paid contexts, in order to maintain consistency with the counts shown publicly on Twitter.
Video view quartiles

data.video.playback_0_count

data.video.playback_25_count

data.video.playback_50_count

data.video.playback_75_count

data.video.playback_100_count

 The number of users who made it to each quartile in a video. This reflects the number of quartile views across all Tweets in which the given video has been posted.

Please note: Media quartile metrics will not be shown if the requester is not the author of the media.

This will return the total count of video view quartiles from both organic and paid contexts.

 

 

Additional resources