Get Tweet engagement

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 query-based access to organic impressions and engagement data for Tweets from authorized/owned accounts, as well as engagement metrics for Favorites, Retweets, and Replies for any public Tweet. Engagement API customers are required to authenticate using app-user OAuth 1.0 in order to retrieve information about Tweets specific to the authenticating account or can use app-only OAuth 1.0 (or a bearer token) in order to retrieve the available information about any Tweet.

The Engagement API supports three different request endpoints: 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, Hashtag Clicks, Mention 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.

For these three visible metrics: Favorites, Replies, and Retweets, the Engagement API will return the total count of activities the Tweets from either organic or paid context, 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.  Internally, the Engagement API will track the number of unique @handles that have been requested against the contracted @handle limit.  It's recommended to also track the @handle request usage on the client side throughout the month.  For more information on this process, please review the enterprise contract with your account manager or view our OAuth documentation.

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 Tweets
• Limited to five metrics: Impressions, Engagements, Favorites, Replies, Retweets
• 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
• Supports the ability to retrieve Impressions and Engagements metrics for Tweets created within the last 90 days.
• Supports the ability to retrieve Favorite, Retweet, and Reply metrics for any Tweet.

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 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  /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 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"
        }
      }
    }
  }
}

Next steps

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.