Engagement API

​

Overview

​

Request endpoints

​

Current Totals: [/totals]

• Requests return a total metric for impressions and a total metric for engagements for the desired Posts
• Limited to the following metrics: Impressions, Engagements, Favorites, Replies, Retweets, Quote Tweets, and Video Views
• Supports the ability to retrieve Impressions and Engagements metrics for Posts created within the last 90 days using OAuth 1.0a User Context
• Supports the ability to retrieve Favorites, Retweets, Quote Tweets, Replies, and Video Views metrics for any Post using OAuth 2.0 Bearer token
• 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 @handles
• Supports requesting metrics for up to 250 Posts per request  

​

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 Post 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
• Supports requesting metrics for up to 25 Posts per request  

​

Historical: [/historical]

• Requests can return impressions, engagements, and a breakdown of individual engagement metrics for the most recent one year, based on the engagement time (not the Post creation time).
• Requests support a start date and end date parameter, providing flexibility to narrow into a specific time frame up to 4 weeks in duration.
• Post engagement data is limited to only 365 days in the past.
• Data can be grouped by Post 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.
• Supports requesting metrics for up to 25 Posts per request.

​

Available metrics

​

Engagement groupings

• tweet.id
• engagement.type  

• engagement.day
• engagement.hour

​

Guides

​

Developer getting started guide

​

Introduction

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.  

• Measuring campaign success with the Red Cross

​

Integrating the Engagement API

Introduction to API

• 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.

• 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.

Getting API access

Making a request

1/ Today we’re sharing our vision for the future of the X API platform — Twitter Dev (@TwitterDev) April 6, 2017

Don’t miss the Posts about your Post. Now on iOS, you can see Retweets with comments all in one place. pic.x.com/oanjZfzC6y — X (@X) May 12, 2020

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

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

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

​

Authenticating with OAuth

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

​

Selecting an Engagement API Endpoint

• 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.  

​

Key concepts

Impressions and engagement metrics

Owned and unowned X content

Total and time-series engagement Data

​

Endpoints and example use cases

/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.

​

Engagement API key characteristics

• RESTful API serving JSON data, supporting POST requests with JSON data bodies.
• Types of Requests: Client apps may make the following types of requests:
  • Total engagements — HTTP POST request to /totals endpoint
  • Last 28-hour engagements — HTTP POST request to /28hr endpoint
  • Historical engagements — HTTP POST request to /historical endpoint
• OAuth authentication:
  • OAuth 1.0 User Context: All available metrics are available for Posts that are owned by a user that has authorized your App using 3-legged OAuth. You must use that user’s Access Tokens when making your request.
  • OAuth 2.0 Bearer Token: Select metrics (Retweets, Quote Tweets, Replies, Favorites, and Video Views) are available for any public Post. 
• Request metadata and structure: Request data is a JSON object consisting of a Post ID array, an array of engagement types, and an engagement grouping structure.
• Posts per request:
  • /totals endpoint: 250 Post IDs
  • /28hr endpoint: 25 Post IDs
  • /historical endpoint: 25 Post IDs
• Engagement metrics availability:
  • /totals — Metric totals since when Post was posted. Impressions and Engagements are available for Posts published in the last 90 days, while Retweets, Quote Tweets, Replies, Favorites, and Video Views are available for all Posts.
  • /28hr — Last 28 hours from time of request.
  • /historical — Any 28-day period starting September 1, 2014.
• Metric types: Each request includes an array of Metric Types. The availability of these depends on the endpoint and, if requesting from the /totals endpoint, on whether Posts are user-permissioned.
  • /totals endpoint:
    • All Posts: Favorites, Retweets, Quote Tweets, Replies, and Video Views
    • Requires OAuth 1.0a User Context: Impressions, Engagements, Favorites, Replies, and Retweets
  • /28hr and /historical endpoints (Requires OAuth 1.0a User Context with Post owner’s Access Token): Impressions, Engagements, Favorites, Replies, Retweets, URL Clicks, Hashtag Clicks, Detail Click, Permalink Clicks, Media Clicks, App Install Attempts, App Opens, Post Emails, Video Views, and Media Views
• Engagement groupings: Each request includes an array of Engagement Groupings. With these groupings you can customize how the returned metrics are organized. Up to three groupings can be included with each request. Metrics can be organized by the following values:
  • All endpoints: Post ID, Engagement Type
  • /28hr and /historical endpoints: These endpoints provide time-series if these additional groupings are specified: Engagement Day, Engagement Hour
• Integration Expectations: Your team will be responsible for the following.
  • Creating and maintaining a client app that can send HTTP requests to the Engagement API that returns engagement metrics for Post ID included in request.
• Limitations
• Video views are only available for Posts that are 1800 days old or less.

​

Authenticating with the Engagement API

Please note:  X needs to enable access to the Engagement API for your developer App before you can start using the API. To this end, make sure to share the App ID that you intend to use for authentication purposes with your account manager or technical support team.

• All requests sent to the /28hr endpoint and /historical endpoint
• Accessing any of the following private metrics: Impressions, Engagements, Media Views, Media Engagements, URL Clicks, Hashtag Clicks, Detail Expands, Permalink Clicks, App Install Attempts, App Opens, Email Post, User Follows, and User Profile Clicks

​

Recent changes to the Engagement API

​

Interpreting the metrics

​

Impressions and engagement data

​

Video metrics

• The video views provided by the /totals endpoint and the X user interface will display the video view aggregated across all Posts in which the given video has been posted. That means that the metric delivered via /totals and displayed in the X UI includes the combined views from any instance where the video has been Retweeted or reposted in separate Posts.
• The video views provided by the /28hour and /historical Engagement API endpoints will just include those views generated by the specific Post for which you are pulling metrics.   

{
  "unsupported_for_video_views_tweet_ids": [
    "479311209565413376",
    "477139122520219648"
  ],
  "grouping name": {
    "479311209565413376": {
      "favorites": "69",
      "impressions": "1692",
      "retweets": "142",
      "video_views": "0"
    },
    "477139122520219648": {
      "favorites": "10",
      "impressions": "1023",
      "retweets": "6",
      "video_views": "0"
    },
    "1397568983931392004": {
      "favorites": "268",
      "impressions": "26803",
      "retweets": "56",
      "video_views": "17902"
    }
  }
}

​

Engagement API groupings

• tweet.id
• engagement.type  

• engagement.day
• engagement.hour

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

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

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

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

{
  "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"
      ]
    }
  }
}

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

​

Frequently asked questions

​

Engagement API

​

Error troubleshooting guide

​

Still can’t find what you’re looking for?

​

API reference

​

POST insights/engagement

​

Methods

​

Authentication

• Any request to /totals to obtain Impressions and Engagements metric types, which are limited to owned Tweets
• Any request to /28hr
• Any request to /historical

• Any request to /totals to obtain Favorites, Replies, Retweets, or Video Views metric types, which can be retrieved for any Tweet

• OAuth Overview
• Using 3 Legged OAuth, also known as User Context
• Using Application-Only OAuth

​

POST /insights/engagement/totals

​

POST /insights/engagement/28hr

​

POST /insights/engagement/historical

​

Response codes

​

Error Messages