Understanding recent changes to Engagement API metrics

Recent changes to the Engagement API

The Engagement API delivers invaluable impression and engagement metrics that enable you to monitor the performance of your activity on X. In our continual effort to enable marketing decisions based on our data, we are excited to share recent changes to the Engagement API that provide greater consistency with metrics across all of X.  

We recently deployed changes to modernize the Engagement API to use the same metrics aggregation methodology in use by the X analytics dashboard (analytics.x.com). We took a thoughtful approach to try and minimize breaking API changes when rolling out these new metrics and deployed the first set of changes on October 9, 2017. These changes improve consistency from all of the places you or your customers might monitor your performance on X. Please see the detailed outline of the changes below:

Metric

Change

engagements

We’ve updated the metrics that roll into overall engagements to match consistency with the Post analytics dashboard. Engagements measures “times people interacted with this Post”.

For Posts that include media like a video or a GIF, the engagements metric will no longer include media views. Media views can now be accessed in a new metric, media_views.

media_clicks*

This metric has been replaced by a new metric called “media_engagements”.

video_views

As of July 6th, 2018, this metric is now available for 'unowned' Posts via the /totals endpoint. This means that you can access the video views for all Posts by using app-only authentication. 

You can only request video views that are younger than 1800 days old. If you try to request video views for a Post older than 1800 days, you will receive the following:

"unsupported_for_video_views_tweet_ids": ["TWEET_ID"]

Please note that it will differ from media_views in that video_views relies on the MRC standard of 50% of the video in view for at least two seconds.

Also, note that you may see a discrepancy between the video views metric displayed in the X owned and operated platforms (mobile app and website) and the number that you receive via the /28hr and /historical endpoints.

  • The video views displayed in the X user interface and that delivers using the /totals endpoint will display the video view aggregated across all Posts 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 Posts.
  • The video views provided by the /28hr and /historical endpoints will just include those views generated by the specific Post for which you are pulling metrics.

media_views

This includes all views (autoplay and click) of your media counted across videos, vines, gifs, and images.

Please note that Posts with images do not show a media_views metric in the analytics dashboard but will be returned in the Engagement API.

media_engagements* 

This includes the number of clicks on your media across videos, vines, gifs, and images. This metric is replacing media_clicks.

quote_tweets

As of July 7th, 2020, this metric is now available for 'unowned' Posts via the /totals endpoint. This means that you can access the Quote Post count for all Posts by using app-only authentication. 

 

Next steps

  • Read through the Engagement API's Overview page for general information about the product.
  • Check out our 'Getting started' guide for the Engagement API.
  • Check out our API references to learn more about how to programmatically access Post 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 Post collections. The client has a helper feature that can surface 'Top Posts.' As engagement metrics are retrieved, on a Post-by-Post basis, this client maintains a list of 'Top Posts' with the highest levels of engagement. For example, if you are processing 100,000 Posts, 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.