Migrating to Twitter API v2
We have graduated several Labs endpoints into the new Twitter API v2: Early Access, meaning that their full functionality is available in a production-ready state.
If you plan to continue using this functionality, please migrate to the new version of these endpoints.
Requesting Tweet and media metrics in the Tweet object
This section of the migration guide is intended for consumers of the /tweets/metrics/private endpoint. The data from that endpoint is now available to request in the Tweet and media objects themselves, using the /tweets and /tweets/search (recent search) endpoints. While all the same metrics are available in these endpoints, there are some minor differences. You will need to specify the metrics fields you want in your request, and the response object model is slightly different. We’ve outlined these changes below.
Authentication
OAuth 1.0a User Context authentication is required for metrics that are non-public (unavailable to view on twitter.com), such as impressions or video quartile views. If requesting only public metrics for a Tweet or media object within the Tweet, use OAuth 2.0 Bearer Token authentication.
Query Parameters
To retrieve metrics on the Tweets and recent search endpoints, you will need to specify the fields (non_public_metrics or public_metrics) in the tweet and media fields query parameters.
Response Object Model
Tweet metrics are returned in the data.non_public_metrics and data.public_metrics objects. Media metrics are returned in the data.includes.media.public_metrics object.
| Description | Labs metrics v1 | Labs Tweet lookup | Labs recent search |
|---|---|---|---|
| Base URL | https://api.twitter.com | https://api.twitter.com | https://api.twitter.com |
| Endpoint path(s) | /labs/1/tweets/metrics/private | (i) /labs/2/tweets (ii) /labs/2/tweets/:id |
/labs/2/tweets/search |
| Required parameters | ids | (i) ids | query |
| Authentication | User Context | Bearer Token User Context |
Bearer Token |
| Query parameters required to retrieve metrics? | ✔ | ✔ | |
| Query parameters for Tweet metrics | N/A | tweet.fields=public_metrics,non_public_metrics | tweet.fields=public_metrics |
| Query parameters for media metrics | N/A | expansions=attachments.media_keys &media.fields=public_metrics,non_public_metrics |
expansions=attachments.media_keys &media.fields=public_metrics |
| Maximum number of tweets in a single request | 50 | (i) 100 (ii) 1 |
max_results: 100 |
| Metrics | Object/Field Mapping | ||
| Impressions | tweet.impression_count | non_public_metrics.impression_count | Non-public metrics not currently available |
| Retweets | tweet.retweet_count | public_metrics.retweet_count | public_metrics.retweet_count |
| Quote Tweets | tweet.quote_count | public_metrics.quote_count | public_metrics.quote_count |
| Likes | tweet.like_count |
public_metrics.like_count |
public_metrics.like_count |
| Replies | tweet.reply_count |
public_metrics.reply_count |
public_metrics.reply_count |
Video views |
view.view_count |
includes.media.public_metrics.view_count |
includes.media.public_metrics.view_count |
Video view quartiles |
view.playback_0_count view.playback_25_count view.playback_50_count view.playback_75_count view.playback_100_count |
includes.media.non_public_metrics.playback_0_count includes.media.non_public_metrics.playback_25_count includes.media.non_public_metrics.playback_50_count includes.media.non_public_metrics.playback_75_count includes.media.non_public_metrics.playback_100_count |
Non-public metrics not currently available |
