A developer’s ‘getting started’ guide

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 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):

  • Array of Post IDs.
  • Array specifying the metric types of interest. Types include things such as ‘impressions’, ‘retweets’, ‘hashtag_clicks’, and ‘user_follows’.
  • Engagement groupings, which is a JSON structure indicating how you want the engagement data arranged in the API response.


In many situations, the Engagement Types and Groupings will remains relatively constant from request to request, with only the Post IDs being updated.

The Engagement API provides three endpoints:

  • Totals - Provides grand totals of engagements for Posts. Some metrics are available for all Posts, while others are only available for the past 90 days.
  • 28 hour - Provides time-series engagement metrics from the last 28 hours.
  • Historical - Provides time-series engagement metrics for up to four consecutive weeks for Posts posted since September 1, 2014.


The /totals endpoint supports requesting metrics for up to 250 Posts per request. The /28hour and /historical endpoints support 25 per request.

After discussing getting access to the Engagement API, we’ll walk through making an API request, provide an OAuth overview, and provide links to other technical resources.

Getting API access

If you are reading this document, you have most likely already obtained access to the Engagement API. If not, please reach out to your Enterprise account manager, or apply for Enterprise access here.

The first step is creating a X app using an approved developer account via the developer portal.  Your account manager will need the numeric App ID associated with this application to provide access. If you need to apply for a developer account, you can do so here.

Making a request

The good news is that making requests to the Engagement API is simple. For our request, we’ll ask it for total Retweets, Quote Tweets, Favorites, and replies, for the following two @XDevelopers Posts:

The first step is constructing the API request in JSON, consisting of these two Post IDs placed in an array, an array of engagement types of interest, and a custom-named “groupings” JSON object that indicates how we want the metrics arranged in the response. Here is what our request looks like:

      {
  "tweet_ids": [
    1260294888811347969, 850006245121695744
  ],
  "engagement_types": [
    "retweets", "quote_tweets", "favorites", "replies"
  ],
  "groupings": {
    "engagement-types-by-id": {
      "group_by": [
        "Tweet.id", "engagement.type"
      ]
    }
  }
}

To retrieve these total metrics, we POST this JSON request to the https://data-api.x.com/insights/engagement/totals endpoint.

We’ll include the following headers to indicate that our request is encoded in JSON, and that it is Gzipped (request bodies can get big):

  • Content-Type: application/json
  • Accept-Encoding: gzip
     

When making requests we authenticate using OAuth, which we’ll discuss more in the next section.

The API returns the following payload:

      {
  "grouping name": {
    "1260294888811347969": {
      "favorites": "17111",
      "quote_tweets": "3254",
      "replies": "1828",
      "retweets": "5218"
    },
    "850006245121695744": {
      "favorites": "492",
      "quote_tweets": "66",
      "replies": "42",
      "retweets": "324"
    }
  }
}


Note that the response has our requested metrics in the structure described by the “groupings” definitions, with metrics listed by Post ID first, then by engagement type on the next level.

That was pretty simple. If you are new to authenticating with OAuth, check out the next section.

Authenticating with OAuth

OAuth is an authentication standard that is very common in the technology industry.  If you are already using OAuth (perhaps with other X APIs) then you are likely using a language-specific OAuth package that abstracts away all the gnarly details. If you are new to OAuth, please visit our Oauth with the X API page or head directly to the https://oauth.net to learn more. Then we recommend that you find an OAuth package for your integration language of choice and start there. With these packages, the path to authenticating typically means configuring your keys and tokens, creating some sort of HTTP object, then making requests with that object.

For example, in the Ruby world, the following pseudo-code represents a recipe to build an OAuth-enabled app using the Ruby gem ‘oauth’ and making a POST request:  

      require 'oauth'

#Assemble JSON request (as above).
request = make_json_request() 

#Build an app consumer object with my app consumer key and secret.
consumer = OAuth::Consumer.new(keys['consumer_key'], keys['consumer_secret'], {:site => ‘https://data-api.x.com’})
#Build a user token with tokens provided by account providing permission. If making app-only #request (checking Tweets that do not require permission with /totals endpoint), this step can be #skipped. 
token = {:oauth_token => keys['access_token'], :oauth_token_secret => keys['access_token_secret']}

#Create oauth-enabled app object. 
app = OAuth::AccessToken.from_hash(consumer, token)
#Make POST request.
result = app.post(“/insights/engagement/totals", request, {"content-type" => "application/json", "Accept-Encoding" => "gzip"})

 

The Engagement API supports both application-only and user-context authentication. If you are collecting engagement metrics for unowned public Posts with the /totals endpoint then no user permission is required and you can use application-only authentication. In this case, you’ll use only your app key and secret to authenticate.

OAuth also allows an app to make an API request “on behalf of another user”, using tokens that relate to the user. If you are generating Engagement metrics for owned Posts, ie Posts that were published by a user whom you have user tokens for, you will be making requests with a user context, meaning authenticating with both your app keys and user-specific access tokens. These user access tokens are typically supplied with the 'Sign-in with X' process or acquired directly from the user (please note that you must use twurl if you acquire the tokens directly from the user). Once the user provides their tokens, they do not expire and can be used with the Engagement API to make requests on their behalf,  as long as the user doesn't reset their tokens or change their password, in which case they will have to provide you the new tokens.

You can review which metrics require which authentication via this table.
 

Next steps

  • Read through the Engagement API's Overview page for general information about the product.
  • 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. 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.