Get Tweet engagement

Engagement API

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.

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. This metric does not include video views on gifs.

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. This metric does not include video views on gifs.

Media Views

media_views

/28hr /historical

Yes

A count of all views (autoplay and click) of your media counted across videos, gifs, and images.

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:

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.

By using Twitter’s services you agree to our Cookies Use. We use cookies for purposes including analytics, personalisation, and ads.

This page and certain other Twitter sites place and read third party cookies on your browser that are used for non-essential purposes including targeting of ads. Through these cookies, Google and Demandbase collect personal data about you for their own purposes. Learn more.