The Engagement API provides query-based access to organic impressions and engagement data for your own Tweets, as well as public engagement metrics for Favorites, Retweets, and Replies for any Tweet. Engagement API customers are required to authenticate using OAuth 1.0 in order to retrieve information about Tweets specific to the authenticating account and OAuth 2.0 in order to retrieve the available information about any Tweet.

The Engagement API supports three types of requests: Totals, Last 28 Hours, and 4 Week Historical.

Impressions and Engagement Data 

The Engagement API delivers organic impressions and engagement data.

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.

Engagements represent the number of times that a given Tweet was engaged upon by a viewer in an organic context. Engagements include, but are not limited to, Retweets, Favorites, Replies, URL Clicks, and Media Views. For the full list of included engagement actions, please see the Engagement Data section. Engagements from Tweets that are seen in a Promoted or Paid context are not included.

The exception to this rule of organic context is for the three metrics - Favorites, Replies, and Retweets - for which we return the total number of activities the Tweets have returned in order to maintain consistency with the counts shown publicly on Twitter. Since the Engagements metric is comprised of several metrics including the three metrics listed above, it is a combination of organic and total values.

In order to calculate a baseline engagement rate, please use the total number of engagements divided by the total number of impressions for a given Tweet for the time period you are analyzing.

Impression and engagement data can only be retrieved for Tweets from owned @handles, or @handles that have authorized your application to view details about their Tweets. For more information on this process, please view our OAuth documentation.

Request Endpoints 

The Engagement API has three endpoints:

Current Totals
  • Requests return a total metric for impressions and a total metric for engagements for the desired Tweets
  • 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 owned @handles
  • Limited to five metrics: Impressions, Engagements, Favorites, Replies, Retweets
  • New! The /totals endpoint now supports the ability to retrieve Impressions and Engagements metrics for Tweets created within the last 90 days.
  • New! The /totals endpoint now supports the ability to retrieve Favorite, Retweet, and Reply metrics for any Tweet.
Last 28 Hours
  • 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 Tweet 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
Historical
  • Requests can return impressions, engagements, and a breakdown of individual engagement metrics for any time period after September 1, 2014, up to 4 weeks in duration
  • Requests support a start date and end date parameter, providing flexibility to narrow into a specific time frame up to 4 weeks in duration
  • Data can be grouped by Tweet 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

Engagement Types 

The table below describes the types of engagement metrics that can be accessed through the Engagement API. Please note that each endpoint may not support all engagement types. The Engagement API returns data that occurred within an organic context. Impression or engagement actions that took place in a promoted context are not included.


Engagement Name API Representation Description
Impressions impressions A count of how many times the Tweet has been viewed.
Engagements engagements A count of the number of times a user has interacted with the Tweet
Favorites favorites A count of how many times the Tweet has been favorited.
Replies replies A count of how many times the Tweet has been replied to.
Retweets retweets A count of how many times the Tweet has been Retweeted.
URL Clicks url_clicks A count of how many times a URL in the Tweet has been clicked.
Hashtag Clicks hashtag_clicks A count of how many times a hashtag in the Tweet has been clicked.
Detail Click detail_expands A count of how many times the Tweet has been clicked to see more details.
Permalink Clicks permalink_clicks A count of how many times the permalink to the Tweet (the individual web page dedicated to this Tweet) has been clicked.
Media Clicks media_clicks A count of how many times media such as an image or video in the Tweet has been clicked.
App Install Attempts app_install_attempts A count of how many times an App Install event has occurred from the Tweet
App Opens app_opens A count of how many times an App Open event has occurred from the Tweet.
Tweet Emails email_tweet A count of how many times the Tweet has been shared via email.
User Follows user_follows A count of how many times the User (Tweet author) has been followed from this Tweet.
User Profile Clicks user_profile_clicks A count of how many times the User (Tweet author) has had their profile clicked from this Tweet.
Video Views video_views A count of how many times a video in the Tweet has been viewed.

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

Groupings are honored serially, so that you can change the desired result format by changing the order of your group_by values. Groupings that contain four group_by values will only be supported in one of the follow two formats:

"group_by": [
    "tweet.id",
    "engagement.type",
    "engagement.day",
    "engagement.hour"
  ]

OR

"group_by": [
    "engagement.type",
    "tweet.id",
    "engagement.day",
    "engagement.hour"
]

For example, if you want to generate grand totals of metric types, include the following “groupings” specification as part of your request (and see the API Reference page for more information on assembling requests):

{
  "engagement_types": [
    "favorites",
    "replies",
    "retweets"
  ],
  "groupings": {
    "Grand Totals": {
      "group_by": [
        "engagement.type"
      ]
    }
  }
}

With this grouping, the Engagement API’s JSON response will include a root-level "Grand Totals" attribute which contains grand totals by metrics type:

{
  "Grand Totals": {
    "favorites": "12",
    "replies": "2",
    "retweets": "2"
  }
}

To generate a 4-hour time-series of metrics for a single Tweet grouped by Tweet IDs, the following Grouping specification would be part of the request:

{
  "start": "2016-02-10T17:00:00Z",
  "end": "2016-02-10T21:00:00Z",
  "tweet_ids": [
    "697506383516729344"
  ],
  "engagement_types": [
    "impressions",
    "engagements"
  ],
  "groupings": {
    "Tweets_MetricType_TimeSeries": {
      "group_by": [
        "tweet.id",
        "engagement.type",
        "engagement.hour"
      ]
    }
  }
}
        

With this grouping, the Engagement API’s JSON response will include a root-level "Tweets_MetricType_TimeSeries" attribute which contains the metrics broken down by Tweet ID, then metric type, and the corresponding hourly time-series:

{
  "Tweets_MetricType_TimeSeries": {
    "697506383516729344": {
      "impressions": {
        "2016-02-10": {
          "17": "551",
          "18": "412",
          "19": "371",
          "20": "280"
        }
      },
      "engagements": {
        "2016-02-10": {
          "17": "8",
          "18": "6",
          "19": "3",
          "20": "0"
        }
      }
    }
  }
}

Technical Details 

The Engagement API supports POST requests, with a post body that includes details around the Tweets you wish to evaluate, the metrics you’re interested in, and how you would like data grouped. For more information, please visit the API Reference page.