Interpreting the metrics
Note: You may observe differences between reported data on some of the Twitter web dashboards, and the data reported in the Engagement API. These differences occur because the web dashboards typically only show engagements and/or impressions that occurred within the selected time range. For example, a web dashboard may show engagement on Tweets within the span of a calendar month, while the Engagement API may show engagements that fall beyond the span of that month, but within the time range requested. The Engagement API should be seen as the valid source, in these cases.
Impressions and engagement data
The Engagement API delivers organic impressions and engagement data.
Impressions represent the number of times that a given Tweet has been viewed on the Twitter platform in an organic context. Impressions generated from Tweets that are seen in a Promoted or Paid context are not included.
Engagements represent the number of times that a given Tweet was engaged upon by a viewer in an organic context. Engagements include, but are not limited to, Retweets, Favorites, Replies, URL Clicks, Hashtag Clicks, Mention Clicks, and Media Views. For the full list of included engagement actions, please see the Engagement Data section. Engagements from Tweets that are seen in a Promoted or Paid context are not included.
For these four visible metrics: Favorites, Replies, Retweets, and Video Views, the Engagement API will return the total count of activities the Tweets from either organic or paid context, in order to maintain consistency with the counts shown publicly on Twitter. Since the Engagements metric is comprised of several metrics including the three metrics listed above, it is a combination of organic and paid values.
In order to calculate a baseline engagement rate, please use the total number of engagements divided by the total number of impressions for a given Tweet for the time period you are analyzing.
Impression and engagement data can only be retrieved for Tweets from owned @handles, or @handles that have authorized your application to view details about their Tweets. Internally, the Engagement API will track the number of unique @handles that have been requested against the contracted @handle limit. It's recommended to also track the @handle request usage on the client side throughout the month.
There are a couple of different metrics that represent impressions of media within Twitter. The first of which is our Video Views metric, which relies on the MRC standard of 50% of the video in view for at least two seconds. The second is Media Views, that includes all views (autoplay and click) of your media counted across videos, vines, gifs, and images.
The Video Views metric is available for owned Tweets via the /28hour and /historical endpoints, as well as for all unowned Tweets via the /totals endpoint. While the Video Views metric within the Twitter user interface is using the same MRC standard, please note that you may see a discrepancy between the video views metric displayed in the Twitter owned and operated platforms (mobile app and website) and the number that you receive via the Engagement API.
- The video views displayed in the Twitter user interface will display the video view aggregated across all Tweets in which the given video has been posted. That means that the metric displayed in the UI includes the combined views from any instance where the video has been Retweeted or reposted in separate Tweets.
- The video views provided by the Engagement API will just include those views generated by the specific Tweet for which you are pulling metrics.
The Media Views metric is only available for owned Tweets with the /28hour and /historical endpoints.
- Read through the Engagement API's Overview page for general information about the product.
- Check out our 'Getting started' guide for the Engagement API.
- Learn more about some of the recent changes to the Engagement API here.
- Check out our API references to learn more about how to programmatically access Tweet engagement metrics.
- Key Characteristics - serves as a one-page developer’s checklist of API features and details.
- Explore our sample code:
- Example Ruby client. This example Engagement API Client helps manage the process of generating engagement metadata for large Tweet collections. The client has a helper feature that can surface 'Top Tweets.' As engagement metrics are retrieved, on a Tweet-by-Tweet basis, this client maintains a list of 'Top Tweets' with the highest levels of engagement. For example, if you are processing 100,000 Tweets, it can compile the top 10 for Retweets or any other available metric. The repository includes an extensive README, which serves as an additional source of ‘getting started’ material and orientation for how the API works.
- Example Python client. This example illustrates using OAuth with the Requests package. The client also has an aggregating function for the /historical endpoint that combines API results over an arbitrary time period longer than 28 days.