GET users/lookup

Please note

We recently released user lookup, a set of Twitter API v2 endpoints that have the same functionality as this one. The new version is currently in development and serves adequate access for the majority of developers on our platform. While elevated levels of access are coming soon, developers in need of higher levels of access should continue to use this endpoint along with the Twitter API v2 version.

GET users/lookup

Returns fully-hydrated user objects for up to 100 users per request, as specified by comma-separated values passed to the user_id and/or screen_name parameters.

This method is especially useful when used in conjunction with collections of user IDs returned from GET friends / ids and GET followers / ids.

GET users / show is used to retrieve a single user object.

There are a few things to note when using this method.

  • You must be following a protected user to be able to see their most recent status update. If you don't follow a protected user their status will be removed.
  • The order of user IDs or screen names may not match the order of users in the returned array.
  • If a requested user is unknown, suspended, or deleted, then that user will not be returned in the results list.
  • If none of your lookup criteria can be satisfied by returning a user object, a HTTP 404 will be thrown.
  • You are strongly encouraged to use a POST for larger requests.

Resource URL

https://api.twitter.com/1.1/users/lookup.json

Resource Information

Response formats JSON
Requires authentication? Yes
Rate limited? Yes
Requests / 15-min window (user auth) 900
Requests / 15-min window (app auth) 300

Parameters

Name Required Description Default Value Example
screen_name optional A comma separated list of screen names, up to 100 are allowed in a single request. You are strongly encouraged to use a POST for larger (up to 100 screen names) requests. twitterapi twitter
user_id optional A comma separated list of user IDs, up to 100 are allowed in a single request. You are strongly encouraged to use a POST for larger requests. 783214 6253282
include_entities optional The entities node that may appear within embedded statuses will not be included when set to false. false
tweet_mode optional Valid request values are compat and extended, which give compatibility mode and extended mode, respectively for Tweets that contain over 140 characters false

Example Requests

$ curl --request GET 
  --url 'https://api.twitter.com/1.1/users/lookup.json?user_id=783214,6253282' 
  --header 'authorization: OAuth oauth_consumer_key="consumer-key-for-app", 
  oauth_nonce="generated-nonce", oauth_signature="generated-signature", 
  oauth_signature_method="HMAC-SHA1", oauth_timestamp="generated-timestamp", 
  oauth_version="1.0"'

$ twurl /1.1/users/lookup.json?user_id=783214,6253282,2244994945

Example Response

[
  {
    {user-object},
    {user-object},
    {user-object}
  }
]

For more detail, see the user-object definition.