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

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

Run in Postman ❯

Endpoint URL

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

Authentication and rate limits

Authentication methods supported by this endpoint	OAuth 1.0a is also available for this endpoint. OAuth 2.0 App-only
Rate limit	App rate limit (Application-only): 900 requests per 15-minute window shared among all users of your app

Authentication methods
supported by this endpoint

OAuth 1.0a is also available for this endpoint.

OAuth 2.0 App-only

Rate limit

App rate limit (Application-only): 900 requests per 15-minute window shared among all users of your app

Query parameters

Name	Type	Description
`ids` Required	string	A comma separated list of user IDs. Up to 100 are allowed in a single request.
`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.
`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 code with offical SDKs

      curl -X GET -H "Authorization: Bearer $BEARER_TOKEN" "https://api.x.com/labs/2/users?ids=2244994945,783214"

      curl -X GET -H "Authorization: Bearer $BEARER_TOKEN" "https://api.x.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

      {
  "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? 🔎nnSearch 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

Name	Type	Description
`id`	string	Unique 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_at`	date (ISO 8601)	Creation time of this account. To return this field, add `user.fields=created_at` in the request's query parameter.
`name`	string	The friendly name of this user, as shown on their profile.
`username`	string	The Twitter handle (screen name) of this user.
`protected`	boolean	Indicates 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.
`withheld`	object	Contains withholding details for withheld content. To return this field, add `user.fields=withheld` in the request's query parameter.
`withheld.country_codes`	array	Provides 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.scope`	enum (`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.
`location`	string	The 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.
`url`	string	The URL specified in the user's profile, if present. To return this field, add `user.fields=url` in the request's query parameter.
`description`	string	The 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.
`verified`	boolean	Indicate if this user is a verified Twitter User. To return this field, add `user.fields=verified` in the request's query parameter.
`entities`	object	This 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.url`	array	Contains details about text recognized as a URL.
`entities.url.start`	integer	The start position (zero-based) of the recognized URL within the Tweet.
`entities.url.end`	integer	The end position (zero-based) of the recognized URL within the Tweet.
`entities.url.url`	string	The URL in the format tweeted by the user.
`entities.url.expanded_url`	string	The fully resolved URL.
`entities.url.display_url`	string	The URL as displayed in the Twitter client.
`entities.hashtags`	array	Contains details about text recognized as a Hashtag.
`entities.hashtags.start`	integer	The start position (zero-based) of the recognized Hashtag within the Tweet.
`entities.hashtags.end`	integer	The end position (zero-based) of the recognized Hashtag within the Tweet.
`entities.hashtags.hashtag`	string	The text of the Hashtag.
`entities.mentions`	array	Contains details about text recognized as a user mention.
`entities.mentions.start`	integer	The start position (zero-based) of the recognized user mention within the Tweet.
`entities.mentions.end`	integer	The end position (zero-based) of the recognized user mention within the Tweet.
`entities.mentions.username`	string	The part of text recognized as a user mention.
`entities.cashtags`	array	Contains details about text recognized as a Cashtag.
`entities.cashtags.start`	integer	The start position (zero-based) of the recognized Cashtag within the Tweet.
`entities.hashtags.end`	integer	The end position (zero-based) of the recognized Cashtag within the Tweet.
`entities.cashtags.cashtag`	string	The text of the Cashtag.
`profile_image_url`	string	The URL to the profile image for this user, as shown on the user's profile.
`public_metrics`	object	Contains details about activity for this user.
`public_metrics.followers_count`	integer	Number of users who follow this user.
`public_metrics.following_count`	integer	Number of users this user is following.
`public_metrics.tweet_count`	integer	Number of Tweets (including Retweets) posted by this user.
`public_metrics.listed_count`	integer	Number of lists that include this user.
`pinned_tweet_id`	string	Unique 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.tweets`	array	For referenced Tweets, this is a list of objects with the same structure as the one described by GET /tweets.
`errors`	object	Contains details about errors that affected any of the requested users. See Status codes and error messages for more details.