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' Tweets. Some metrics are available for all Tweets, while others are only available for Tweets published in the last 90 days. Supports 250 Tweets per request.
  • 28 hour - provides time-series Engagement metrics for ‘owned’ Tweets from the last 28 hours. Supports 25 Tweets per request.
  • Historical - provides time-series Engagement metrics for up to four consecutive weeks for ‘owned’ Tweets posted since September 1, 2014. Supports 25 Tweets 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 Tweet has been viewed on the Twitter platform in an organic context. Impressions generated from Tweets that are seen in a Promoted or Paid context are not included. Before the Engagement API, Tweet 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 Tweet.

The impression metrics generated by the Engagement API is an actual measure of the number of times a Tweet has been rendered for display. If a follower of your account misses your Tweet, 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 Tweet. 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 Twitter content

The Engagement makes a clear distinction between owned and unowned Tweets. Owned Tweets are Tweets that are posted from your account, or Tweets that you have obtained permission to request Engagement data for. As with other Twitter APIs, you obtain permission by having other Twitter 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 Twitter’ process.

The /totals endpoint provides engagement data for both owned and unowned Tweets. For unowned Tweets, you can request engagement metrics that are publicly available in a Tweet 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 Tweets, the /totals endpoint also provides Impression and (total) Engagement metrics.

The /28hr and /historical endpoints provide metrics for owned Tweets 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 Tweet was posted. If a Tweet 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 Tweet, not just owned Tweets.
  • I want to compare performance against a competitor.
  • I want to track basic engagement stats for a hashtag or campaign that includes Tweets 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 Tweets per day.
     

/28hr

  • I need access to all 17 metric types.
  • I want to show data for very recent Tweets 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 Tweets 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 Tweets 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 Tweets 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 Tweet 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 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. 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.