Interpreting the metrics

Note: You may observe differences between reported data on some of the X 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 Posts 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 Post has been viewed on the X platform in an organic context. Impressions generated from Posts that are seen in a Promoted or Paid context are not included.

Engagements represent the number of times that a given Post was engaged upon by a viewer in both an organic and promoted 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. 

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 Post for the time period you are analyzing.

Impression and engagement data can only be retrieved for Posts from owned @handles, or @handles that have authorized your application to view details about their Posts.  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.  

Video metrics

There are a couple of different metrics that represent impressions of media within X. 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 Posts via the /28hour and /historical endpoints, as well as for all unowned Posts via the /totals endpoint. 

While the video views metric within the X user interface is using the same MRC standard, please 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 different Engagement API endpoints.

• The video views provided by the /totals endpoint and the X user interface will display the video view aggregated across all Posts in which the given video has been posted. That means that the metric delivered via /totals and displayed in the X 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 /28hour and /historical Engagement API endpoints will just include those views generated by the specific Post for which you are pulling metrics. 
   

Please note that we do not deliver video views for Posts that are older than 1800 days. Instead, we deliver an object that lists the Posts that are older than 1800 days. You will still receive all other metrics for your requested Posts in a separate object. Here is an example response:

The Media Views metric is only available for owned Posts with the /28hour and /historical endpoints.

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.
• 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 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.