GET /labs/1/users

Returns a variety of information about one or more Users specified by the requested IDs or usernames.



Authentication and rate limits

Authentication methods supported by this endpoint
OAuth 2.0 Bearer token
OAuth 1.0a User context

This endpoint is rate limited at 900 requests per 15-minute window.



Query parameters

NameTypeDescription
ids
 Optional 
stringRequired unless using usernames. A comma separated list of User IDs. Up to 100 are allowed in a single request.
usernames
 Optional 
stringRequired unless using ids. A comma separated list of Twitter usernames (handles). Up to 100 are allowed in a single request.
format
 Optional 
enum (compact, default, detailed)Format for all the objects returned as part of the response.
user.format
 Optional 
enum (compact, default, detailed)Format for all User objects returned in response. Can be used together with other format parameters to expand or reduce User objects only.
expansions
 Optional 
enum (most_recent_tweet_id, pinned_tweet_id)Comma-separated list of fields to expand. Expansions enable requests to expand an ID into a full object in the includes response object.


Examples

  • cURL
  • twurl
curl -X GET -H "Authorization: Bearer $BEARER_TOKEN" "https://api.twitter.com/labs/1/users?usernames=TwitterDev"
twurl -X GET "/labs/1/users?usernames=TwitterDev"

Response

  • Default format
  • Compact format
  • Detailed format
{
  "data": [
    {
      "id": "2244994945",
      "created_at": "2013-12-14T04:35:55.000Z",
      "name": "Twitter Dev",
      "username": "TwitterDev",
      "protected": false,
      "location": "Internet",
      "url": "https://t.co/FGl7VOULyL",
      "description": "Your official source for Twitter Platform news, updates & events. Need technical help? Visit https://t.co/mGHnxZU8c1 ⌨️ #TapIntoTwitter",
      "verified": true,
      "entities": {
        "url": {
          "urls": [
            {
              "start": 0,
              "end": 23,
              "url": "https://t.co/FGl7VOULyL",
              "expanded_url": "https://developer.twitter.com/",
              "display_url": "developer.twitter.com"
            }
          ]
        },
        "description": {
          "urls": [
            {
              "start": 93,
              "end": 116,
              "url": "https://t.co/mGHnxZU8c1",
              "expanded_url": "https://twittercommunity.com/",
              "display_url": "twittercommunity.com"
            }
          ],
          "hashtags": [
            {
              "start": 120,
              "end": 135,
              "tag": "TapIntoTwitter"
            }
          ]
        }
      },
      "profile_image_url": "https://pbs.twimg.com/profile_images/880136122604507136/xHrnqf1T_normal.jpg",
      "most_recent_tweet_id": "1158441822286303232",
      "pinned_tweet_id": "1138505981460193280",
      "format": "default"
    }
  ]
}
{
  "data": [
    {
      "id": "2244994945",
      "created_at": "2013-12-14T04:35:55.000Z",
      "name": "Twitter Dev",
      "username": "TwitterDev",
      "protected": false,
      "verified": true,
      "profile_image_url": "https://pbs.twimg.com/profile_images/880136122604507136/xHrnqf1T_normal.jpg",
      "format": "compact"
    }
  ]
}
{
  "data": [
    {
      "id": "2244994945",
      "created_at": "2013-12-14T04:35:55.000Z",
      "name": "Twitter Dev",
      "username": "TwitterDev",
      "protected": false,
      "location": "Internet",
      "url": "https://t.co/FGl7VOULyL",
      "description": "Your official source for Twitter Platform news, updates & events. Need technical help? Visit https://t.co/mGHnxZU8c1 ⌨️ #TapIntoTwitter",
      "verified": true,
      "entities": {
        "url": {
          "urls": [
            {
              "start": 0,
              "end": 23,
              "url": "https://t.co/FGl7VOULyL",
              "expanded_url": "https://developer.twitter.com/",
              "display_url": "developer.twitter.com"
            }
          ]
        },
        "description": {
          "urls": [
            {
              "start": 93,
              "end": 116,
              "url": "https://t.co/mGHnxZU8c1",
              "expanded_url": "https://twittercommunity.com/",
              "display_url": "twittercommunity.com"
            }
          ],
          "hashtags": [
            {
              "start": 120,
              "end": 135,
              "tag": "TapIntoTwitter"
            }
          ]
        }
      },
      "profile_image_url": "https://pbs.twimg.com/profile_images/880136122604507136/xHrnqf1T_normal.jpg",
      "stats": {
        "followers_count": 503251,
        "following_count": 1474,
        "tweet_count": 3419,
        "listed_count": 1526
      },
      "most_recent_tweet_id": "1158441822286303232",
      "pinned_tweet_id": "1138505981460193280",
      "format": "detailed"
    }
  ]
}

Response fields

NameTypeDescription
idstringUnique identifier of this user. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers.

 default   compact   detailed 
created_atdate (ISO 8601)Creation time of this account.

 default   compact   detailed 
namestringThe friendly name of this user, as shown on their profile.

 default   compact   detailed 
usernamestringThe Twitter handle (screen name) of this user.

 default   compact   detailed 
protectedbooleanIndicates if this user has chosen to protect their Tweets (in other words, if this user's Tweets are private).

 default   compact   detailed 
withheldobjectContains withholding details for withheld content.

 default   compact   detailed 
withheld.country_codesarrayProvides a list of countries where this user is not available.
withheld.scopeenum (tweet, user)Indicates whether the content being withheld is a Tweet or a user (this API will return user).
locationstringThe location specified in the user's profile, if the user provided one. As this is a freeform value, it may not indicate a valid location, but it may be fuzzily evaluated when performing searches with location queries.

 default   detailed 
urlstringThe URL specified in the user's profile, if present.

 default   detailed 
descriptionstringThe text of this user's profile description (also known as bio), if the user provided one.

 default   detailed 
verifiedbooleanIndicate if this user is a verified Twitter User.

 default   compact   detailed 
entitiesobjectContains details about text that has a special meaning in a Tweet.

 default   detailed 
entities.urlarrayContains details about text recognized as a URL.
entities.url.startintThe start position (zero-based) of the recognized URL within the Tweet.
entities.url.endintThe end position (zero-based) of the recognized URL within the Tweet.
entities.url.urlstringThe URL in the format tweeted by the user.
entities.url.expanded_urlstringThe fully resolved URL.
entities.url.display_urlstringThe URL as displayed in the Twitter client.
entities.hashtagsarrayContains details about text recognized as a Hashtag.
entities.hashtags.startintThe start position (zero-based) of the recognized Hashtag within the Tweet.
entities.hashtags.endintThe end position (zero-based) of the recognized Hashtag within the Tweet.
entities.hashtags.hashtagstringThe text of the Hashtag.
entities.mentionsarrayContains details about text recognized as a user mention.
entities.mentions.startintThe start position (zero-based) of the recognized user mention within the Tweet.
entities.mentions.endintThe end position (zero-based) of the recognized user mention within the Tweet.
entities.mentions.usernamestringThe part of text recognized as a user mention.
entities.cashtagsarrayContains details about text recognized as a Cashtag.
entities.cashtags.startintThe start position (zero-based) of the recognized Cashtag within the Tweet.
entities.hashtags.endintThe end position (zero-based) of the recognized Cashtag within the Tweet.
entities.cashtags.cashtagstringThe text of the Cashtag.
profile_image_urlstringThe URL to the profile image for this user, as shown on the user's profile.

 default   compact   detailed 
statsobjectContains details about activity for this user.

 detailed 
stats.followers_countintegerNumber of users who follow this user.
stats.following_countintegerNumber of users this user is following.
stats.tweet_countintegerNumber of Tweets (including Retweets) posted by this user.
stats.listed_countintegerNumber of lists that include this user.
most_recent_tweet_idstringUnique identifier of this user's most recent Tweet.

You can obtain the expanded object in includes.tweets by adding expansions=most_recent_tweet_id in the request's query parameter.

 default   detailed 
pinned_tweet_idstringUnique identifier of this user's pinned Tweet.

You can obtain the expanded object in includes.tweets by adding expansions=pinned_tweet_id in the request's query parameter.

 default   detailed 
formatenum (default, compact, detailed)Indicates the format returned for this object, as requested in the format or user.format query parameters.

 default   compact   detailed 
includes.tweetsarrayFor referenced Tweets, this is a list of objects with the same structure as the one described by GET /tweets.
errorsobjectContains details about errors that affected any of the requested users. See Status codes and error messages for more details.

 default   compact   detailed