Get Tweet engagement

Engagement API

Enterprise

This is an enterprise API available within our managed access levels only. To use this API, you must first set up an account with our enterprise sales team. Learn more

The Engagement API provides query-based access to organic impressions and engagement data for Tweets from authorized/owned accounts, as well as engagement metrics for Favorites, Retweets, and Replies for any public Tweet. Engagement API customers are required to authenticate using app-user OAuth 1.0 in order to retrieve information about Tweets specific to the authenticating account or can use app-only OAuth 1.0 (or a bearer token) in order to retrieve the available information about any Tweet.

The Engagement API supports three different request endpoints: Totals, Last 28 Hours, and 4 Week Historical.

Request endpoints

The Engagement API has three endpoints:

Current Totals: /totals

  • Requests return a total metric for impressions and a total metric for engagements for the desired Tweets
  • Limited to six metrics: Impressions, Engagements, Favorites, Replies, Retweets, and Video Views
  • Supports the ability to retrieve Impressions and Engagements metrics for Tweets created within the last 90 days.
  • Supports the ability to retrieve Favorite, Retweet, Reply, and Video Views metrics for any Tweet.
  • The results are based on the current total of impressions and engagements at the time the request is made
  • Ideal for powering a dashboard report and for calculating engagement rates across a variety of owned @handles
  • Supports requesting metrics for up to 250 Tweets per request
     

Last 28 hours: /28hr

  • Requests can return a total metric for impressions, a total metric for engagements, and breakdown of individual engagement metrics that have occurred in the last 28 hours
  • Data can be grouped by Tweet ID, and in time-series in aggregate, by day, or by hour
  • Ideal for tracking the performance of recently created content
  • Supports all available metrics
  • Supports requesting metrics for up to 25 Tweets per request
     

Historical: /historical

  • Requests can return impressions, engagements, and a breakdown of individual engagement metrics for any time period after September 1, 2014, up to 4 weeks in duration
  • Requests support a start date and end date parameter, providing flexibility to narrow into a specific time frame up to 4 weeks in duration
  • Data can be grouped by Tweet ID, and in time-series in aggregate, by day, or by hour
  • Ideal for evaluating recent performance against a historical benchmark or developing a historical picture of an @handle’s performance
  • Supports all available metrics
  • Supports requesting metrics for up to 25 Tweets per request


Available metrics

The table below describes the types of metrics that can be accessed through the Engagement API. The Engagement API returns data that occurred within an organic context.

Please check out our Interpreting the metrics page to learn more about the below metrics.
 

Metric API Representation Endpoint Availability User Context Required Description
Impressions impressions All Yes A count of how many times the Tweet has been viewed. This metric is only available for Tweets that have been posted within the past 90 days.
Engagements engagements All Yes A count of the number of times a user has interacted with the Tweet. This metric is only available for Tweets that have been posted within the past 90 days.
Favorites favorites All

Yes - /28hrs & /Historical

No - /totals

 A count of how many times the Tweet has been favorited. 
Retweets retweets All

Yes - /28hrs & /Historical

No - /totals

 A count of how many times the Tweet has been Retweeted.
Replies replies All

Yes - /28hrs & /Historical

No - /totals

 A count of how many times the Tweet has been replied to.
Video Views
 video_views All

Yes - /28hrs & /Historical

No - /totals

A count of how many times a video in the given Tweet has been 50% visible for at least two seconds.

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 /28hr and /historical endpoints.

  • The video views displayed in the Twitter user interface and with the /totals endpoint 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 /28hr and /historical endpoints will just include those views generated by the specific Tweet for which you are pulling metrics.
Media Views media_views /28hr /historical

 Yes
 A count of all views (autoplay and click) of your media counted across videos, gifs, and images.
Media Engagements
(formerly Media Clicks)		 media_engagements /28hr /historical Yes
 A count of how many times media such as an image or video in the Tweet has been clicked.
URL Clicks url_clicks /28hr /historical Yes A count of how many times a URL in the Tweet has been clicked.
Hashtag Clicks hashtag_clicks /28hr /historical Yes
 A count of how many times a hashtag in the Tweet has been clicked.
Detail Click detail_expands /28hr /historical Yes
 A count of how many times the Tweet has been clicked to see more details.
Permalink Clicks permalink_clicks /28hr /historical Yes
 A count of how many times the permalink to the Tweet (the individual web page dedicated to this Tweet) has been clicked.
App Install Attempts app_install_attempts /28hr /historical Yes
 A count of how many times an App Install event has occurred from the Tweet
App Opens app_opens /28hr /historical Yes
 A count of how many times an App Open event has occurred from the Tweet.
Tweet Emails email_tweet /28hr /historical Yes
 A count of how many times the Tweet has been shared via email.
User Follows user_follows /28hr /historical Yes
 A count of how many times the User (Tweet author) has been followed from this Tweet.
User Profile Clicks user_profile_clicks /28hr /historical Yes
 A count of how many times the User (Tweet author) has had their profile clicked from this Tweet.

 

Engagement groupings

Groupings enable custom organization of the returned engagement metrics. You can include a maximum of 3 groupings per request. You can choose to group the metrics by one or more of the following values:

All three endpoints support:

  • tweet.id
  • engagement.type
     

The /28hr and /historical can provide time-series metrics, and thus support:

  • engagement.day
  • engagement.hour

To learn more about grouping, please visit the Engagement API Grouping page within the Guides section.

Next steps

  • Check out our 'Getting started' guide for the Engagement API.
  • Figure out which Engagement API endpoint is right for you.
  • 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. Project 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 illustrating 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.
       
  • Review the following case studies: