Overview
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 access to Post impression and engagement metrics. While most metrics and endpoints require you to authenticate using OAuth 1.0a User Context, you can access public Favorite, Retweet, Reply, and Video Views metrics using OAuth 2.0 Bearer Token and the /totals endpoint.
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.
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 Posts
- Limited to the following metrics: Impressions, Engagements, Favorites, Replies, Retweets, Quote Tweets, and Video Views
- Supports the ability to retrieve Impressions and Engagements metrics for Posts created within the last 90 days using OAuth 1.0a User Context
- Supports the ability to retrieve Favorites, Retweets, Quote Tweets, Replies, and Video Views metrics for any Post using OAuth 2.0 Bearer token
- 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 @handles
- Supports requesting metrics for up to 250 Posts 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 Post 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 Posts per request
Historical: /historical
- Requests can return impressions, engagements, and a breakdown of individual engagement metrics for the most recent one year, based on the engagement time (not the Post creation time).
- Requests support a start date and end date parameter, providing flexibility to narrow into a specific time frame up to 4 weeks in duration.
- Post engagement data is limited to only 365 days in the past.
- Data can be grouped by Post 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 Posts per request.
Available metrics
The table below describes the types of metrics that can be accessed through the Engagement API.
Please check out our Interpreting the metrics page to learn more about the below metrics.
| Metric | Endpoint Availability | User Context Required | Description |
|---|---|---|---|
| impressions | All | Yes | A count of how many times the Post has been viewed. This metric is only available for Posts that have been posted within the past 90 days. |
| engagements | All | Yes | A count of the number of times a user has interacted with the Post. This metric is only available for Posts that have been posted within the past 90 days. |
| favorites | All | Yes - /28hrs & /Historical No - /totals |
A count of how many times the Post has been favorited. |
| retweets | All | Yes - /28hrs & /Historical No - /totals |
A count of how many times the Post has been Retweeted. |
| quote_tweets | /totals | No - /totals |
A count of times a Post has been Retweeted with a comment (also known as Quote). |
| replies | All | Yes - /28hrs & /Historical No - /totals |
A count of how many times the Post has been replied to. |
| video_views | All | Yes - /28hrs & /Historical No - /totals |
A count of how many times a video in the given Post has been 50% visible for at least two seconds. Video views are only available for Posts that are 1800 days old or less. If you try to request video views for any Posts older than 1800 days, you will receive the following object within your response, along with a separate object that contains any other metrics that you requested: "unsupported_for_video_views_tweet_ids": ["TWEET_ID"] Please note: 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.
|
| media_views | /28hr /historical |
Yes |
A count of all views (autoplay and click) of your media counted across videos, gifs, and images. |
media_engagements |
/28hr /historical | Yes |
A count of how many times media such as an image or video in the Post has been clicked. |
| url_clicks | /28hr /historical | Yes | A count of how many times a URL in the Post has been clicked. |
| hashtag_clicks | /28hr /historical | Yes |
A count of how many times a hashtag in the Post has been clicked. |
| detail_expands | /28hr /historical | Yes |
A count of how many times the Post has been clicked to see more details. |
| permalink_clicks | /28hr /historical | Yes |
A count of how many times the permalink to the Post (the individual web page dedicated to this Post) has been clicked. |
| app_install_attempts | /28hr /historical | Yes |
A count of how many times an App Install event has occurred from the Post |
| app_opens | /28hr /historical | Yes |
A count of how many times an App Open event has occurred from the Post. |
| email_tweet | /28hr /historical | Yes |
A count of how many times the Post has been shared via email. |
| user_follows | /28hr /historical | Yes |
A count of how many times the User (Post author) has been followed from this Post. |
| user_profile_clicks | /28hr /historical | Yes |
A count of how many times the User (Post author) has had their profile clicked from this Post. |
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 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.