Labs v2 Overview

Versioning contents

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.

Migrating from v1 to 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": "https://developer.twitter.com/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": "https://developer.twitter.com/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
}