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
}

Was this document helpful?

Thank you for the feedback. We’re really glad we could help!

Thank you for the feedback. How could we improve this document?

Thank you for the feedback. Your comments will help us improve our documents in the future.