Follow, search, and get users

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 (default, see extended Tweet below)

$ curl --request GET 
  --url 'https://api.twitter.com/1.1/statuses/show.json?id=970742659059986432' 
  --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/statuses/show.json?id=970742659059986432

Example Response (default, see extended Tweet below)

{
"created_at": "Mon Mar 05 19:27:40 +0000 2018",
"id": 970742659059986432,
"id_str": "970742659059986432",
"text": "Last week, we saw a safe return for three crew from @Space_Station​, a new weather satellite launched into orbit, a… https://t.co/m3XyUdAaJk",
"truncated": true,
"entities": {
  "hashtags": [],
  "symbols": [],
  "user_mentions": [
    {
      "screen_name": "Space_Station",
      "name": "Intl. Space Station",
      "id": 1451773004,
      "id_str": "1451773004",
      "indices": [
        52,
        66
      ]
    }
  ],
  "urls": [
    {
      "url": "https://t.co/m3XyUdAaJk",
      "expanded_url": "https://twitter.com/i/web/status/970742659059986432",
      "display_url": "twitter.com/i/web/status/9…",
      "indices": [
        117,
        140
      ]
    }
  ]
},
"source": "<a href="https://www.sprinklr.com" rel="nofollow">Sprinklr</a>",
"in_reply_to_status_id": null,
"in_reply_to_status_id_str": null,
"in_reply_to_user_id": null,
"in_reply_to_user_id_str": null,
"in_reply_to_screen_name": null,
"user": {
  "id": 11348282,
  "id_str": "11348282",
  "name": "NASA",
  "screen_name": "NASA",
  "location": "",
  "description": "Explore the universe and discover our home planet with @NASA. We usually post in EST (UTC-5)",
  "url": "https://t.co/TcEE6NS8nD",
  "entities": {
    "url": {
      "urls": [
        {
          "url": "https://t.co/TcEE6NS8nD",
          "expanded_url": "http://www.nasa.gov",
          "display_url": "nasa.gov",
          "indices": [
            0,
            23
          ]
        }
      ]
    },
    "description": {
      "urls": []
    }
  },
  "protected": false,
  "followers_count": 28677827,
  "friends_count": 269,
  "listed_count": 90706,
  "created_at": "Wed Dec 19 20:20:32 +0000 2007",
  "favourites_count": 2958,
  "utc_offset": -18000,
  "time_zone": "Eastern Time (US & Canada)",
  "geo_enabled": false,
  "verified": true,
  "statuses_count": 50797,
  "lang": "en",
  "contributors_enabled": false,
  "is_translator": false,
  "is_translation_enabled": false,
  "profile_background_color": "000000",
  "profile_background_image_url": "http://pbs.twimg.com/profile_background_images/590922434682880000/3byPYvqe.jpg",
  "profile_background_image_url_https": "https://pbs.twimg.com/profile_background_images/590922434682880000/3byPYvqe.jpg",
  "profile_background_tile": false,
  "profile_image_url": "http://pbs.twimg.com/profile_images/188302352/nasalogo_twitter_normal.jpg",
  "profile_image_url_https": "https://pbs.twimg.com/profile_images/188302352/nasalogo_twitter_normal.jpg",
  "profile_banner_url": "https://pbs.twimg.com/profile_banners/11348282/1518798395",
  "profile_link_color": "205BA7",
  "profile_sidebar_border_color": "000000",
  "profile_sidebar_fill_color": "F3F2F2",
  "profile_text_color": "000000",
  "profile_use_background_image": true,
  "has_extended_profile": true,
  "default_profile": false,
  "default_profile_image": false,
  "following": null,
  "follow_request_sent": null,
  "notifications": null,
  "translator_type": "regular"
},
"geo": null,
"coordinates": null,
"place": null,
"contributors": null,
"is_quote_status": false,
"retweet_count": 318,
"favorite_count": 1391,
"favorited": false,
"retweeted": false,
"possibly_sensitive": false,
"possibly_sensitive_appealable": false,
"lang": "en"
}

Example Requests (extended Tweet)

$ curl --request GET 
  --url 'https://api.twitter.com/1.1/statuses/show.json?id=970742659059986432&tweet_mode=extended' 
  --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/statuses/show.json?id=970742659059986432&tweet_mode=extended

Example Response (extended Tweet)

{
  "created_at": "Mon Mar 05 19:27:40 +0000 2018",
  "id": 970742659059986432,
  "id_str": "970742659059986432",
  "full_text": "Last week, we saw a safe return for three crew from @Space_Station​, a new weather satellite launched into orbit, and our next mission to Mars moves closer to launch. Check out what we were up to on the latest episode of This Week at NASA! Watch: https://t.co/DL5mArGP4Q",
  "truncated": false,
  "display_text_range": [
    0,
    246
  ],
  "entities": {
    "hashtags": [],
    "symbols": [],
    "user_mentions": [
      {
        "screen_name": "Space_Station",
        "name": "Intl. Space Station",
        "id": 1451773004,
        "id_str": "1451773004",
        "indices": [
          52,
          66
        ]
      }
    ],
    "urls": [],
    "media": [
      {
        "id": 970742144771256320,
        "id_str": "970742144771256320",
        "indices": [
          247,
          270
        ],
        "media_url": "http://pbs.twimg.com/amplify_video_thumb/970742144771256320/img/BL5wCswXelTd18iL.jpg",
        "media_url_https": "https://pbs.twimg.com/amplify_video_thumb/970742144771256320/img/BL5wCswXelTd18iL.jpg",
        "url": "https://t.co/DL5mArGP4Q",
        "display_url": "pic.twitter.com/DL5mArGP4Q",
        "expanded_url": "https://twitter.com/NASA/status/970742659059986432/video/1",
        "type": "photo",
        "sizes": {
          "thumb": {
            "w": 150,
            "h": 150,
            "resize": "crop"
          },
          "medium": {
            "w": 1200,
            "h": 675,
            "resize": "fit"
          },
          "small": {
            "w": 680,
            "h": 383,
            "resize": "fit"
          },
          "large": {
            "w": 1280,
            "h": 720,
            "resize": "fit"
          }
        }
      }
    ]
  },
  "extended_entities": {
    "media": [
      {
        "id": 970742144771256320,
        "id_str": "970742144771256320",
        "indices": [
          247,
          270
        ],
        "media_url": "http://pbs.twimg.com/amplify_video_thumb/970742144771256320/img/BL5wCswXelTd18iL.jpg",
        "media_url_https": "https://pbs.twimg.com/amplify_video_thumb/970742144771256320/img/BL5wCswXelTd18iL.jpg",
        "url": "https://t.co/DL5mArGP4Q",
        "display_url": "pic.twitter.com/DL5mArGP4Q",
        "expanded_url": "https://twitter.com/NASA/status/970742659059986432/video/1",
        "type": "video",
        "sizes": {
          "thumb": {
            "w": 150,
            "h": 150,
            "resize": "crop"
          },
          "medium": {
            "w": 1200,
            "h": 675,
            "resize": "fit"
          },
          "small": {
            "w": 680,
            "h": 383,
            "resize": "fit"
          },
          "large": {
            "w": 1280,
            "h": 720,
            "resize": "fit"
          }
        },
        "video_info": {
          "aspect_ratio": [
            16,
            9
          ],
          "duration_millis": 140273,
          "variants": [
            {
              "bitrate": 832000,
              "content_type": "video/mp4",
              "url": "https://video.twimg.com/amplify_video/970742144771256320/vid/640x360/UcQQGOCyVw-PpKot.mp4"
            },
            {
              "content_type": "application/x-mpegURL",
              "url": "https://video.twimg.com/amplify_video/970742144771256320/pl/3aiIGPrfVTgxrOW0.m3u8"
            },
            {
              "bitrate": 320000,
              "content_type": "video/mp4",
              "url": "https://video.twimg.com/amplify_video/970742144771256320/vid/320x180/WFlj0q9e0FW0BJhQ.mp4"
            },
            {
              "bitrate": 2176000,
              "content_type": "video/mp4",
              "url": "https://video.twimg.com/amplify_video/970742144771256320/vid/1280x720/82t2pIe6C_MJ-qJs.mp4"
            }
          ]
        },
        "additional_media_info": {
          "monetizable": false
        }
      }
    ]
  },
  "source": "<a href="https://www.sprinklr.com" rel="nofollow">Sprinklr</a>",
  "in_reply_to_status_id": null,
  "in_reply_to_status_id_str": null,
  "in_reply_to_user_id": null,
  "in_reply_to_user_id_str": null,
  "in_reply_to_screen_name": null,
  "user": {
    "id": 11348282,
    "id_str": "11348282",
    "name": "NASA",
    "screen_name": "NASA",
    "location": "",
    "description": "Explore the universe and discover our home planet with @NASA. We usually post in EST (UTC-5)",
    "url": "https://t.co/TcEE6NS8nD",
    "entities": {
      "url": {
        "urls": [
          {
            "url": "https://t.co/TcEE6NS8nD",
            "expanded_url": "http://www.nasa.gov",
            "display_url": "nasa.gov",
            "indices": [
              0,
              23
            ]
          }
        ]
      },
      "description": {
        "urls": []
      }
    },
    "protected": false,
    "followers_count": 28676133,
    "friends_count": 269,
    "listed_count": 90666,
    "created_at": "Wed Dec 19 20:20:32 +0000 2007",
    "favourites_count": 2958,
    "utc_offset": -18000,
    "time_zone": "Eastern Time (US & Canada)",
    "geo_enabled": false,
    "verified": true,
    "statuses_count": 50796,
    "lang": "en",
    "contributors_enabled": false,
    "is_translator": false,
    "is_translation_enabled": false,
    "profile_background_color": "000000",
    "profile_background_image_url": "http://pbs.twimg.com/profile_background_images/590922434682880000/3byPYvqe.jpg",
    "profile_background_image_url_https": "https://pbs.twimg.com/profile_background_images/590922434682880000/3byPYvqe.jpg",
    "profile_background_tile": false,
    "profile_image_url": "http://pbs.twimg.com/profile_images/188302352/nasalogo_twitter_normal.jpg",
    "profile_image_url_https": "https://pbs.twimg.com/profile_images/188302352/nasalogo_twitter_normal.jpg",
    "profile_banner_url": "https://pbs.twimg.com/profile_banners/11348282/1518798395",
    "profile_link_color": "205BA7",
    "profile_sidebar_border_color": "000000",
    "profile_sidebar_fill_color": "F3F2F2",
    "profile_text_color": "000000",
    "profile_use_background_image": true,
    "has_extended_profile": true,
    "default_profile": false,
    "default_profile_image": false,
    "following": null,
    "follow_request_sent": null,
    "notifications": null,
    "translator_type": "regular"
  },
  "geo": null,
  "coordinates": null,
  "place": null,
  "contributors": null,
  "is_quote_status": false,
  "retweet_count": 174,
  "favorite_count": 736,
  "favorited": false,
  "retweeted": false,
  "possibly_sensitive": false,
  "possibly_sensitive_appealable": false,
  "lang": "en"
}