Please note:

We recently graduated user lookup into Twitter API v2: Early Access.

Learn more about the new User lookup endpoints and migrate to the New Twitter API.

GET /labs/2/users (lookup by list of IDs)

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



Endpoint URL

https://api.twitter.com/labs/2/users

Authentication and rate limits

Authentication methods
supported by this endpoint

OAuth 2.0 Bearer token

OAuth 1.0a User context

Rate limit900 requests per 15-minute window

Learn more about rate limits.



Query parameters

NameTypeDescription
expansions
 Optional 
enum (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.
ids
 Required 
stringA comma separated list of user IDs. Up to 100 are allowed in a single request.
media.fields
 Optional 
enum (duration_ms, height, media_key, preview_image_url, type, url, width)Comma-separated list of fields to return in the Tweet media object. The response will contain the selected fields only if a Tweet contains media attachments.
place.fields
 Optional 
enum (contained_within, country, country_code, full_name, geo, id, name, place_type)Comma-separated list of location fields to return. The response will contain the selected fields only if location data is present in any of the response objects.
poll.fields
 Optional 
enum (duration_minutes, end_datetime, id, options, voting_status)Comma-separated list of fields to return in the Tweet poll object. The response will contain the selected fields only if a Tweet contains a poll.
tweet.fields
 Optional 
enum (attachments, author_id, created_at, entities, geo, id, in_reply_to_user_id, lang, possibly_sensitive, referenced_tweets, source, public_metrics, text, withheld)Comma-separated list of fields to return in the Tweet object. By default, the endpoint does not return any Tweet field.
user.fields
 Optional 
enum (created_at, description, entities, id, location, name, pinned_tweet_id, profile_image_url, protected, public_metrics, url, username, verified, withheld)Comma-separated list of additional fields to return in the user object. By default, the endpoint only returns id, name and username.


Example requests

  • cURL (default fields)
  • cURL (optional fields)
  • twurl (default fields)
  • twurl (optional fields)
curl -X GET -H "Authorization: Bearer $BEARER_TOKEN" "https://api.twitter.com/labs/2/users?ids=2244994945,783214"
curl -X GET -H "Authorization: Bearer $BEARER_TOKEN" "https://api.twitter.com/labs/2/users?ids=2244994945,783214&expansions=pinned_tweet_id&user.fields=pinned_tweet_id&tweet.fields=created_at,public_metrics"
twurl -X GET "/labs/2/users?ids=2244994945,783214"
twurl -X GET "/labs/2/users?ids=2244994945,783214&expansions=pinned_tweet_id&user.fields=pinned_tweet_id&tweet.fields=created_at,public_metrics"

Example responses

  • Default fields
  • Optional fields
{
  "data": [
    {
      "id": "2244994945",
      "name": "Twitter Dev",
      "username": "TwitterDev"
    },
    {
      "id": "783214",
      "name": "Twitter",
      "username": "Twitter"
    }
  ]
}
{
  "data": [
    {
      "id": "2244994945",
      "name": "Twitter Dev",
      "pinned_tweet_id": "1214281000932593667",
      "username": "TwitterDev"
    },
    {
      "id": "783214",
      "name": "Twitter",
      "username": "Twitter"
    }
  ],
  "includes": {
    "tweets": [
      {
        "created_at": "2020-01-06T20:22:05.000Z",
        "id": "1214281000932593667",
        "public_metrics": {
          "retweet_count": 60,
          "reply_count": 39,
          "like_count": 150,
          "quote_count": 13
        },
        "text": "Hello… is it me you’re searching for? 🔎\n\nSearch the conversation as it unfolds with this new addition to Labs. We're making it easier than ever to find the Tweets you care about. https://t.co/HmuuUC6PKZ https://t.co/QgEXeL9XzX"
      }
    ]
  }
}

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.
created_atdate (ISO 8601)Creation time of this account.

To return this field, add user.fields=created_at in the request's query parameter.
namestringThe friendly name of this user, as shown on their profile.
usernamestringThe Twitter handle (screen name) of this user.
protectedbooleanIndicates if this user has chosen to protect their Tweets (in other words, if this user's Tweets are private).

To return this field, add user.fields=protected in the request's query parameter.
withheldobjectContains withholding details for withheld content.

To return this field, add user.fields=withheld in the request's query parameter.
withheld.country_codesarrayProvides a list of countries where this user is not available.

To return this field, add user.fields=withheld.country_codes in the request's query parameter.
withheld.scopeenum (tweet, user)Indicates whether the content being withheld is a Tweet or a user (this API will return user).

To return this field, add user.fields=withheld.scope in the request's query parameter.
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.

To return this field, add user.fields=location in the request's query parameter.
urlstringThe URL specified in the user's profile, if present.

To return this field, add user.fields=url in the request's query parameter.
descriptionstringThe text of this user's profile description (also known as bio), if the user provided one.

To return this field, add user.fields=description in the request's query parameter.
verifiedbooleanIndicate if this user is a verified Twitter User.

To return this field, add user.fields=verified in the request's query parameter.
entitiesobjectThis object and its children fields contain details about text that has a special meaning in the user's description.

To return this field, add user.fields=entities in the request's query parameter.
entities.urlarrayContains details about text recognized as a URL.
entities.url.startintegerThe start position (zero-based) of the recognized URL within the Tweet.
entities.url.endintegerThe 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.startintegerThe start position (zero-based) of the recognized Hashtag within the Tweet.
entities.hashtags.endintegerThe 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.startintegerThe start position (zero-based) of the recognized user mention within the Tweet.
entities.mentions.endintegerThe 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.startintegerThe start position (zero-based) of the recognized Cashtag within the Tweet.
entities.hashtags.endintegerThe 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.
public_metricsobjectContains details about activity for this user.
public_metrics.followers_countintegerNumber of users who follow this user.
public_metrics.following_countintegerNumber of users this user is following.
public_metrics.tweet_countintegerNumber of Tweets (including Retweets) posted by this user.
public_metrics.listed_countintegerNumber of lists that include this user.
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.
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.

Was this document helpful?

Thank you

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.