Tweet metrics v1

API Reference contents
  • GET /labs/1/tweets/metrics/private

    • GET /labs/1/tweets/metrics/private

    Returns Tweet engagement data for any owned/authorized Tweet or list of Tweets specified by the requested ID or list of IDs.

    Run in Postman ❯ 


    Endpoint URL

    https://api.twitter.com/labs/1/tweets/metrics/private

    Authentication and rate limits

    Authentication methods
    supported by this endpoint

    OAuth 1.0a User context

    Rate limit15 requests per 15-minute window

    Learn more about rate limits.



    Query parameters

    NameTypeDescription
    ids
     Required     		stringA comma separated list of Tweet IDs. Up to 50 are allowed in a single request. The Tweets you query must have been created in the last 30 days and cannot be Retweets.


    Examples

    • twurl
    twurl -X GET "/labs/1/tweets/metrics/private?ids=123456789,987654320000"

    Response

    • Default format
    {
  "data": [
    {
      "tweet_id": "123456789",
      "tweet": {
        "like_count": 1,
        "retweet_count": 2,
        "quote_count": 3,
        "reply_count": 4,
        "impression_count": 5
      },
      "video": {
        "media_key": "13_123456789",
        "view_count": 12345,
        "playback_0_count": 50,
        "playback_25_count": 40,
        "playback_50_count": 30,
        "playback_75_count": 20,
        "playback_100_count": 10
      }
    }
  ],
  "errors": [
    {
      "value": "987654320000",
      "detail": "Could not find tweet with ids: [987654320000].",
      "type": "https://api.twitter.com/labs/1/problems/resource-not-found",
      "title": "Not Found Error",
      "parameter": "ids",
      "resource_type": "tweet"
    }
  ]
}

    Response fields

    NameTypeDescription
    dataarrayList of requested Tweets and attached videos with associated engagement metrics.
    data.tweet_idstringUnique identifier of this Tweet. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers.
    data.tweetobjectContains detailed engagement metrics for this Tweet.
    data.tweet.like_countintegerThe count of how many times this Tweet has been liked. This is the total count of likes from both organic and paid contexts, in order to maintain consistency with the counts shown publicly on Twitter.
    data.tweet.retweet_countintegerThe count of how many times this Tweet has been Retweeted. This does not include Quote Tweets ("Retweets with comment"). This is the total count of Retweets from both organic and paid contexts, in order to maintain consistency with the counts shown publicly on Twitter.
    data.tweet.quote_countintegerThe count of how many times this Tweet has been Retweeted with a new comment (message). This does not include Retweets. This is the total count of Quote Tweets from both organic and paid contexts.
    data.tweet.reply_countintegerThe count of how many times this Tweet has been replied to. This returns the total count of replies from both organic and paid contexts, in order to maintain consistency with the counts shown publicly on Twitter.
    data.tweet.impression_countintegerThe count of how many times this Tweet has been viewed (not unique by user). This is the total count of impressions from both organic and paid contexts.
    data.videoobjectContains detailed engagement metrics for any video attached to this Tweet.
    data.video.media_keyintegerUnique identifier of the media attached to this Tweet.
    data.video.view_countintegerThe count of how many times the video attached to this Tweet has been viewed. This is the number of video views aggregated across all Tweets in which the given video has been posted. That means that the metric includes the combined views from any instance where the video has been Retweeted or reposted in separate Tweets. This returns the total count of video views from both organic and paid contexts, in order to maintain consistency with the counts shown publicly on Twitter.
    data.video.playback_0_countintegerThe number of users who made it to less than 25% of the video. This reflects the number of quartile views across all Tweets in which the given video has been posted. This is the total count of video view quartiles from both organic and paid contexts and is only returned when the requester is also the author of the media.
    data.video.playback_25_countintegerThe number of users who made it to 25% of the video. This reflects the number of quartile views across all Tweets in which the given video has been posted. This is the total count of video view quartiles from both organic and paid contexts and is only returned when the requester is also the author of the media.
    data.video.playback_50_countintegerThe number of users who made it to 50% of the video. This reflects the number of quartile views across all Tweets in which the given video has been posted. This is the total count of video view quartiles from both organic and paid contexts and is only returned when the requester is also the author of the media.
    data.video.playback_75_countintegerThe number of users who made it to 75% of the video. This reflects the number of quartile views across all Tweets in which the given video has been posted. This is the total count of video view quartiles from both organic and paid contexts and is only returned when the requester is also the author of the media.
    data.video.playback_100_countintegerThe number of users who made it to 100% of the video. This reflects the number of quartile views across all Tweets in which the given video has been posted. This is the total count of video view quartiles from both organic and paid contexts and is only returned when the requester is also the author of the media.
    errorsarrayList of errors that affected any of the requested Tweets. See Status codes and error messages for more details.