Skip to main content

​
Overview

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

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

​
Guides

​
Developer getting started guide

​
Introduction

The purpose of this documentation is to provide developers an introduction to integrating with the Engagement API. We’ll start off by discussing the ‘whys’ of integrating, then start digging into the technical ‘how’ details.
What does the Engagement API provide?
  • The Engagement API provides impression and engagement data for any X account’s owned Posts from the last 90 days, assuming that account has authorized your App to request metrics on their behalf using 3-legged OAuth. This powerful, yet easy-to-implement solution gives immediate access to impressions and deep engagements such as URL clicks, #hashtag clicks, and many more.
  • The Engagement API provides total aggregate metrics for favorites, Retweets, Quote Tweets, replies, and video views for any Post. This can be used as a powerful way to get basic engagement data about any Post or collection of Posts.
  • The Engagement API delivers new value to social listening, marketing, and publishing platforms by allowing customers to measure ROI on X by effectively measuring the performance of content using 15+ performance metrics.
  • The Engagement API is a request/response API that allows app developers to send requests with Post IDs, desired metrics, and a time frame, for which the API instantly returns data.  
Why integrate? Example use-cases
  • Understand the total reach of your content to see how many people view it. See how many people view videos, click on links, click on hashtags, or install my apps.
  • Generate both total and time-series engagement metrics.
  • Understand basic engagement metrics (favorites, Retweets, Quote Tweets, replies) about any public Post.
  • Use these metrics to determine what types of Posts work so I can post them more often and get more impressions and more engagements for my content.
  • Automate marketing behavior (such as Retweeting content from a different owned account) every time one of my Posts reaches 100 Likes, or another threshold.
  • Benchmark and compare my campaigns against each other as a tool for A/B testing.
  • Analyze what type of content resonates for my customer service department to determine how and when to respond.
  • Show analytics for content that is published from my platform.  
The Engagement API was launched in 2016 and was the first X API to provide these in-depth engagement metrics at scale. The Engagement API is easy to use and enables customers to automate the process. Here is a case study describing an example integration: Now that we’ve explored the ‘whys’ of the Engagement API, let’s start digging into the technical details.

​
Integrating the Engagement API

Introduction to API
The Engagement API is a simple RESTful API that receives requests encoded in JSON and responds with engagement metrics encoded in JSON. Requests consist three main parts (follow links for more documentation):