Migration guide
Interested in exploring Labs?
The endpoints we release in Labs are previews of tools that may be released more broadly in the future, but will likely undergo changes before then. We encourage you to take that into consideration as you explore. Before getting started, please read more about Twitter Developer Labs.
Jump to on this page
If you are, instead, trying to migrate from Labs to the new Twitter API v2: Early Access endpoints, you can find a helpful comparison table that lists the Twitter API v1.1, Labs, and Twitter API v2: Early Access functionality side by side that describes what has changed between the three different endpoint versions.
You can find links to these tables at the following links:
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 | Metrics v1 | Tweets | 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 |
Migrating from Labs v1 to Labs v2
This guide is intended to help developers using the Twitter Developer Labs v1 endpoints to migrate to v2.
While the way requests are formed for fields in a Tweet object is changing across all endpoints, the core search, pagination and other functionality of Recent Search will stay the same. The new version of hide replies will not have any new functionality.
Labs v1 endpoints will be available for 90 days after the launch of their newer version. Tweet metrics, Filtered Stream, and Sampled Stream are still available in v1 and will be coming to v2 in the near future.
New path variable for single ID lookup in Tweets and Users
Tweets
v1: /labs/1/tweets?ids=1212092627178287104
v2: /labs/2/tweets/1212092627178287104
Note that the ids query parameter is still available in v2 to retrieve multiple Tweets.
For example: /labs/2/tweets?ids=1212092627178287104,20
Users (ID lookup)
v1: /labs/1/users?ids=2244994945
v2: /labs/2/users/2244994945
Note that the ids query parameter is still available in v2 to retrieve multiple users.
For example: /labs/2/users?ids=12,13
New path for username lookup in Users
Single username lookup
v1: /labs/1/users?usernames=TwitterDev
v2: /labs/2/users/by/username/TwitterDev
Multiple username lookup
v1: /labs/1/users?usernames=TwitterDev,jack
v2: /labs/2/users/by?usernames=TwitterDev,jack
Formats and fields
The difference between formats and fields
The Labs v2 endpoints will no longer include a formats query parameter. With formats, you were only able to select one of three different sets of fields to return in your payload (compact, default, and detailed). The new fields query parameter allows you to select each individual field that you would like returned in the your payload, and is only available with the v2 endpoints.
As seen below, the v2 default responses Tweets and Users are pared down. We have also included an example of which fields values you must pass in v2 to receive the same data that is available in the default format in v1.
Comparing v1 and v2 GET /tweets requests and responses
GET /tweets v1 using the default format and no expansions:
Request
GET /labs/1/tweets?ids=1212092627178287104&tweet.format=default
Response
{
"data": [
{
"author_id": "2244994945",
"created_at": "2019-12-31T19:26:16.000Z",
"entities": {
"urls": [
{
"start": 187,
"end": 210,
"url": "https://t.co/Vxp4UKnuJ9",
"expanded_url": "https://twitterdevfeedback.uservoice.com/forums/921790-twitter-developer-labs",
"display_url": "twitterdevfeedback.uservoice.com/forums/921790-…"
}
]
},
"id": "1212092627178287104",
"in_reply_to_user_id": "2244994945",
"referenced_tweets": [
{
"type": "replied_to",
"id": "1212092626247110657"
}
],
"text": "These launches would not be possible without the feedback you provided along the way, so THANK YOU to everyone who has contributed your time and ideas. Have more feedback? Let us know ⬇️ https://t.co/Vxp4UKnuJ9",
"format": "default"
}
]
}
GET /tweets v2 using the default format and no expansions:
Request
GET /labs/2/tweets/1212092627178287104
Response
{
"data": {
"id": "1212092627178287104",
"text": "These launches would not be possible without the feedback you provided along the way, so THANK YOU to everyone who has contributed your time and ideas. Have more feedback? Let us know ⬇️ https://t.co/Vxp4UKnuJ9"
}
}
GET /tweets v2 using the fields parameter to request the same fields as the default v1 payload:
Request
GET /labs/2/tweets/1212092627178287104&tweet.fields=author_id,created_at,entities,in_reply_to_user_id,referenced_tweets
Response
{
"data": {
"author_id": "2244994945",
"created_at": "2019-12-31T19:26:16.000Z",
"entities": {
"urls": [
{
"start": 187,
"end": 210,
"url": "https://t.co/Vxp4UKnuJ9",
"expanded_url": "https://twitterdevfeedback.uservoice.com/forums/921790-twitter-developer-labs",
"display_url": "twitterdevfeedback.uservoice.com/forums/921790-…"
}
]
},
"id": "1212092627178287104",
"in_reply_to_user_id": "2244994945",
"referenced_tweets": [
{
"type": "replied_to",
"id": "1212092626247110657"
}
],
"text": "These launches would not be possible without the feedback you provided along the way, so THANK YOU to everyone who has contributed your time and ideas. Have more feedback? Let us know ⬇️ https://t.co/Vxp4UKnuJ9"
}
}Comparing v1 and v2 GET /users requests and responses
GET /users v1 using the default format:
Request
GET /labs/1/users?ids=2244994945&format=default
Response
{
"data": [
{
"created_at": "2013-12-14T04:35:55.000Z",
"description": "The voice of Twitter's #DevRel team, and your official source for updates, news, & events about Twitter's API.\n\nNeed help? Visit https://t.co/DVDf7qKyS9",
"entities": {
"url": {
"urls": [
{
"start": 0,
"end": 23,
"url": "https://t.co/3ZX3TNiZCY",
"expanded_url": "/content/developer-twitter/en/community",
"display_url": "developer.twitter.com/en/community"
}
]
},
"description": {
"urls": [
{
"start": 129,
"end": 152,
"url": "https://t.co/DVDf7qKyS9",
"expanded_url": "http://twittercommunity.com",
"display_url": "twittercommunity.com"
}
],
"hashtags": [
{
"start": 23,
"end": 30,
"tag": "DevRel"
}
]
}
},
"id": "2244994945",
"location": "127.0.0.1",
"most_recent_tweet_id": "1222944210724233217",
"name": "Twitter Dev",
"pinned_tweet_id": "1214281000932593667",
"profile_image_url": "https://pbs.twimg.com/profile_images/880136122604507136/xHrnqf1T_normal.jpg",
"protected": false,
"url": "https://t.co/3ZX3TNiZCY",
"username": "TwitterDev",
"verified": true,
"format": "default"
}
]
}
GET /users v2 request using the default format
GET /labs/2/users/2244994945
Response
{
"data": {
"id": "2244994945",
"name": "Twitter Dev",
"username": "TwitterDev"
}
}
GET /users v2 using the fields parameter to request the same fields as the default v1 payload:
Request
GET /labs/2/users/2244994945?user.fields=created_at,description,entities,id,location,name,pinned_tweet_id,profile_image_url,protected,url,username,verified
Response
{
"data": {
"created_at": "2013-12-14T04:35:55.000Z",
"description": "The voice of Twitter's #DevRel team, and your official source for updates, news, & events about Twitter's API.\n\nNeed help? Visit https://t.co/DVDf7qKyS9",
"entities": {
"url": {
"urls": [
{
"start": 0,
"end": 23,
"url": "https://t.co/3ZX3TNiZCY",
"expanded_url": "/content/developer-twitter/en/community",
"display_url": "developer.twitter.com/en/community"
}
]
},
"description": {
"urls": [
{
"start": 129,
"end": 152,
"url": "https://t.co/DVDf7qKyS9",
"expanded_url": "http://twittercommunity.com",
"display_url": "twittercommunity.com"
}
],
"hashtags": [
{
"start": 23,
"end": 30,
"tag": "DevRel"
}
]
}
},
"id": "2244994945",
"location": "127.0.0.1",
"name": "Twitter Dev",
"pinned_tweet_id": "1214281000932593667",
"profile_image_url": "https://pbs.twimg.com/profile_images/880136122604507136/xHrnqf1T_normal.jpg",
"protected": false,
"url": "https://t.co/3ZX3TNiZCY",
"username": "TwitterDev",
"verified": true
}
}
Other changes
Removed most_recent_tweet_id field from the Users object
If you used this field to infer information about a user's set language, consider using the pinned_tweet_id expansion instead.
Cleaned up the source field in the Tweets object
v1: "source": "<a href=\"http://twitter.com\" rel=\"nofollow\">Twitter Web Client</a>"
v2: "source": "Twitter Web App"
Changed field name stats to public_metrics in both the Tweets and Users objects
Tweet object v1
"stats": {
"retweet_count": 49,
"reply_count": 23,
"like_count": 124,
"quote_count": 14
}Tweet object v2
"public_metrics": {
"retweet_count": 49,
"reply_count": 23,
"like_count": 123,
"quote_count": 14
}
User object v1
"stats": {
"followers_count": 593,
"following_count": 496,
"tweet_count": 1038,
"listed_count": 4
}User object v2
"public_metrics": {
"followers_count": 593,
"following_count": 496,
"tweet_count": 1038,
"listed_count": 4
}
