Selecting an Engagement API Endpoint

Selecting an Engagement API Endpoint

The Engagement API provides three distinct endpoints:

  • Totals - provides grand totals of select metrics from owned 'owned' or 'unowned' Posts. Some metrics are available for all Posts, while others are only available for Posts published in the last 90 days. Supports 250 Posts per request.
  • 28 hour - provides time-series Engagement metrics for ‘owned’ Posts from the last 28 hours. Supports 25 Posts per request.
  • Historical - provides time-series Engagement metrics for up to four consecutive weeks for ‘owned’ Posts posted since September 1, 2014. Supports 25 Posts per request.
     

Each endpoint has its own unique characteristics. Whether you are planning to use all three, or are trying to decide which one best matches your use case, it’s important to understand the differences between them.

Below we introduce some key concepts, further explore the three endpoints, and then present example use cases that map generally to a specific endpoint. Our hope is that this information will help you more efficiently integrate all three, or help you decide which single endpoint best fits your mission.
 

Key concepts

There are several key concepts that help illustrate the different features of, and data provided by, the three Engagement API endpoints.
 

Impressions and engagement metrics

Impressions represent the number of times that a given Post has been viewed on the X platform in an organic context. Impressions generated from Posts that are seen in a Promoted or Paid context are not included. Before the Engagement API, Post impressions represented only a measure of potential views. It was based on counting followers of the author’s account and those of any account Retweeting the content. It did not take into account the common situation when a given user does not actually see the Post.

The impression metrics generated by the Engagement API is an actual measure of the number of times a Post has been rendered for display. If a follower of your account misses your Post, it does not count as an impression.

The Engagement API provides metrics on 14 unique engagement metric types, each representing a distinct action a user can take when presented a Post. These include Retweeting, Liking, Replying, clicking on entities like #hashtags, links and media, following the author, and viewing the author’s profile. All of these individual actions are rolled up into a single Engagements metric.

Owned and unowned X content

The Engagement makes a clear distinction between owned and unowned Posts. Owned Posts are Posts that are posted from your account, or Posts that you have obtained permission to request Engagement data for. As with other X APIs, you obtain permission by having other X users/accounts share access tokens that enable you to make API requests on their behalf. A common way to obtain these tokens is with the ‘Sign in with X’ process.

The /totals endpoint provides engagement data for both owned and unowned Posts. For unowned Posts, you can request engagement metrics that are publicly available in a Post display: Favorite, Retweet, and Reply. For these metrics, what the Engagement API brings to the table is the ability to retrieve these metrics at scale in an automated way. For owned Posts, the /totals endpoint also provides Impression and (total) Engagement metrics.

The /28hr and /historical endpoints provide metrics for owned Posts only, meaning that you have to pass along user context when making the request to these endpoints.

Total and time-series engagement Data

The /totals endpoint provides, as its name implies, only grand totals for its engagement types. Its numbers represent the up-to-date totals since the Post was posted. If a Post was just posted and you repeatedly request its metrics, these totals will commonly change with each request.

The /28hr and /historical endpoints can provide both grand totals and time-series data. When requesting time-series data, the engagement metrics can be rolled up into daily or hourly data.   

See our documentation on engagement groupings for how to request time-series data with the /28hr and /historical endpoints.

Endpoints and example use cases

Given the characteristics and differences discussed above, each individual endpoint generally maps to different types of use cases. To help you decide which endpoint best serves your particular use case, below are some example user statements and the endpoint that best satisfies it.

/totals

  • I only need access to some metric types (Impressions, Engagements, Favorites, Retweets, Quote Tweets, Replies, and Video Views).
  • I need access to basic engagement data for any Post, not just owned Posts.
  • I want to compare performance against a competitor.
  • I want to track basic engagement stats for a hashtag or campaign that includes Posts that I don’t own.
  • I don’t need data broken out by day or hour, I just need the current total when I make a request.
  • I need a single metric to show in a report or dashboard and don’t want to store any data.
  • I want to show data at page load time, and just need to make a request and get a response.
  • I need access to get data for hundreds of thousands or millions of Posts per day.
     

/28hr

  • I need access to all 17 metric types.
  • I want to show data for very recent Posts posted in last 28 hours.
  • I have a job that runs once a day to get data that I care about and only need to get data for the last day.
  • I need to have metrics broken out by day or hour.
  • I want to show time-series breakouts of activity by hour in a dashboard.
  • I need high access for hundreds of thousands to Posts per day
  • I have storage capabilities and can refresh data once per day and keep a running tally.
     

/historical

  • I need access to all 17 metric types.
  • I need to get historical data for Posts created all the way back to September 2014.
  • I want to show detailed historical analysis that compares campaigns.
  • I need to have metrics broken out by day or hour.
  • I don’t need high access to the Engagement API and only need to get data for a few hundred or thousand Posts per day.

     

Next steps

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