Tweet metrics v1 (retired)
API Reference contents
Please note:
We graduated the Labs version of filtered stream into Twitter API v2: Early Access and retired it in October 2020.
Learn more about the new metrics functionality.
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.
Endpoint URL
https://api.twitter.com/labs/1/tweets/metrics/private
Authentication and rate limits
| Authentication methods supported by this endpoint |
|
|---|---|
| Rate limit | 15 requests per 15-minute window |
Learn more about rate limits.
Query parameters
| Name | Type | Description |
|---|---|---|
idsRequired |
string | A 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. |
Example requests
- twurl
twurl -X GET "/labs/1/tweets/metrics/private?ids=123456789,987654320000"Example responses
- 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
| Name | Type | Description |
|---|---|---|
data | array | List of requested Tweets and attached videos with associated engagement metrics. |
data.tweet_id | string | Unique 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.tweet | object | Contains detailed engagement metrics for this Tweet. |
data.tweet.like_count | integer | The 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_count | integer | The 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_count | integer | The 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_count | integer | The 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_count | integer | The 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.video | object | Contains detailed engagement metrics for any video attached to this Tweet. |
data.video.media_key | integer | Unique identifier of the media attached to this Tweet. |
data.video.view_count | integer | The 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_count | integer | The 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_count | integer | The 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_count | integer | The 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_count | integer | The 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_count | integer | The 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. |
errors | array | List of errors that affected any of the requested Tweets. See Status codes and error messages for more details. |
