Users lookup

​

Introduction

You can authenticate your request to all users lookup endpoints other than the authenticated user lookup with OAuth 1.0a User Context, App only, or OAuth 2.0 Authorization code with PKCE. However, if you would like to access private metrics or data from private users, you will need to utilize OAuth 1.0a User Context or OAuth 2.0 Authorization Code with PKCE, and pass the authenticated users’ Access Token with your request.    

This endpoint is commonly used to receive up-to-date details on a user, to verify that a user exists, or to update your stored details following a compliance event.

​

Authenticated user lookup

If authenticating on behalf of other users, it is critical to be able to see who you can make a request on behalf of.

This endpoint requires you to use OAuth 1.0a User Context or OAuth 2.0 Authorization Code with PKCE. It returns information about the authorized user, meaning the user that is associated with the user Access Tokens that you pass with the request.

You can access this endpoint via the GET method. There is a user rate limit of 75 requests per 15 minutes for this endpoint.

​

Getting started with the users lookup endpoints

This quick start guide will help you make your first request to the users lookup endpoints with a set of specified fields using Postman.

If you would like to see sample code in different languages, please visit our X API v2 sample code GitHub repository. 

​

Steps to build a users lookup request

​

Step one: Start with a tool or library

There are several different tools, code examples, and libraries that you can use to make a request to this endpoint, but we are going to use the Postman tool here to simplify the process.

To load the X API v2 Postman collection into your environment, please click on the following button:

Once you have the X API v2 collection loaded in Postman, navigate to the GET /users/by endpoint.  

​

Step two: Authenticate your request

To properly make a request to the X API, you need to verify that you have permission. To do so, this endpoint requires you to authenticate your request with either App only, OAuth 2.0 Authorization Code with PKCE, or OAuth 1.0a User Context authentication methods.

For simplicity’s sake, we will utilize App only with this request, but you will need to use one of the other authentication methods if you’d like to request private metrics or users. 

To utilize App only, you must add your keys and tokens, specifically theApp Access Token (also known as the App only Bearer Token) to Postman. You can do this by selecting the environment named “X API v2” in the top-right corner of Postman and adding your keys and tokens to the “initial value” and “current value” fields (by clicking the eye icon next to the environment dropdown).

These variables will automatically be pulled into the request’s authorization tab if you’ve done this correctly.  

​

Step three: Identify and specify which user(s) you would like to retrieve

You must specify a user or a set of users that you would like to receive within the request. Depending on which user endpoint you use, you can pass either a user ID or a username. In this situation, we are going to use the GET /users/by endpoint which allows you to pass multiple usernames in a single request (rather than the single-ID, multi-ID, and single-username endpoints) and pass a set of usernames using the usernames query parameter.

Usernames are simply the account handle that you can find within an account’s profile URL. For example, the following account’s username is XDevelopers.

https://twitter.com/XDevelopers

In Postman, navigate to the “Params” tab and enter this username, or a string of usernames separated by a comma, into the “Value” column of the username parameter, making sure to not include any spaces between usernames and commas. 

​

Step four: Identify and specify which fields you would like to retrieve

If you click the “Send” button after step three, you will receive the default user object fields in your response: id, name, and username.

If you would like to receive additional fields beyond id, name, and username, you will have to specify those fields in your request with the field and/or expansion parameters.

For this exercise, we will request a three additional sets of fields from different objects:

1. The additional user.created_at field in the primary user objects.
2. The associated pinned Posts’ object’s default fields for the returned users: id and text.
3. The additional  tweet.created_at field in the associated Post objects.  

In Postman, navigate to the “Params” tab and add the following key:value pair to the “Query Params” table:

You should now see the following URL next to the “Send” button:

https://api.x.com/2/users/by?usernames=twitterdev,twitterapi,adsapi&user.fields=created_at&expansions=pinned_tweet_id&tweet.fields=author_id,created_at

​

Step five: Make your request and review your response

Once you have everything set up, hit the “Send” button and you will receive the following response:

{
  "data": [
    {
      "created_at": "2013-12-14T04:35:55.000Z",
      "id": "2244994945",
      "name": "Twitter Dev",
      "pinned_tweet_id": "1255542774432063488",
      "username": "TwitterDev"
    },
    {
      "created_at": "2007-05-23T06:01:13.000Z",
      "id": "6253282",
      "name": "Twitter API",
      "username": "TwitterAPI"
    },
    {
      "created_at": "2013-02-27T20:01:12.000Z",
      "id": "1225933934",
      "name": "Twitter Ads API",
      "username": "AdsAPI"
    }
  ],
  "includes": {
    "tweets": [
      {
        "author_id": "2244994945",
        "created_at": "2020-04-29T17:01:38.000Z",
        "id": "1255542774432063488",
        "text": "During these unprecedented times, what’s happening on Twitter can help the world better understand & respond to the pandemic. \n\nWe're launching a free COVID-19 stream endpoint so qualified devs & researchers can study the public conversation in real-time. https://t.co/BPqMcQzhId"
      }
    ]
  }
}

​

Getting started with the Authenticated User Lookup endpoint

This quick start guide will help you make your first request to the authenticated user lookup endpoint using Postman.

Please visit our X API v2 sample code GitHub repository if you want to see sample code in different languages.

​

Steps to build an authenticated user lookup request

​

Step one: Start with a tool or library

There are several different tools, code examples, and libraries that you can use to make a request to this endpoint, but we will use the Postman tool here to simplify the process.

To load the X API v2 Postman collection into your environment, please click on the following button:

Once you have the X API v2 collection loaded in Postman, navigate to the “Authenticated User Lookup” folder, and select “Lookup an Authenticated User”.

​

Step two: Authenticate your request

To properly make a request to the X API, you need to verify that you have permission. To do so with this endpoint, you must authenticate your request using either OAuth 1.0a User Context or OAuth 2.0 Authorization Code with PKCE.

In this example, we are going to use OAuth 1.0a User Context.

You must add your keys and tokens – specifically your API Key, API Secret Key, OAuth 1.0a user Access Token, and OAuth 1.0a user Access Token Secret – to Postman. You can do this by selecting the environment named “X API v2” in the top-right corner of Postman and adding your keys and tokens to the “initial value” and “current value” fields (by clicking the eye icon next to the environment dropdown).

These variables will automatically be pulled into the request’s authorization tab if you’ve done this correctly.  

Step three: Determine which user fields you want to retrieve

If you click the “Send” button after step three, you will receive the default user object fields in your response: id, name, and username.

If you would like to receive additional fields beyond id, name, and username, you will have to specify those fields in your request with the field and/or expansion parameters.

For this exercise, we will request three additional sets of fields from different objects:

1. The additional user.created_at field in the primary user objects.

2. The associated pinned Posts’ object’s default fields for the returned users: id and text.

3. The additional tweet.created_at field in the associated Post objects.

In Postman, navigate to the “Params” tab and add the following key:value pair to the “Query Params” table:

You should now see a similar URL next to the “Send” button:

https://api.x.com/2/users/me?user.fields=created_at&expansions=pinned_tweet_id&tweet.fields=author_id,created_at

​

Integration guide

This page contains information on several tools and key concepts that you should be aware of as you integrate the users lookup endpoints into your system. We’ve broken the page into a couple of different sections:

• Helpful tools
• Key Concepts
• Authentication
• Developer portal, Projects, and Apps
• Rate limits
• Fields and expansions
• Edge cases

​

Helpful tools

Before we dive into some key concepts that will help you integrate this endpoint, we recommend that you become familiar with:

​

Postman

Postman is a great tool that you can use to test out an endpoint. Each Postman request includes every path and body parameter to help you quickly understand what is available to you. To learn more about our Postman collections, please visit our “Using Postman” page. 

​

Code samples

Interested in getting set up with this endpoint with some code in your preferred coding language? We’ve got a handful of different code samples available that you can use as a starting point on our Github page.

​

Third-party libraries

Take advantage of one of our communities’ third-party libraries to help you get started. You can find a library that works with the v2 endpoints by looking for the proper version tag.

​

Key concepts

​

Authentication

All X API v2 endpoints require requests to be authenticated with a set of credentials, also known as keys and tokens. You can use either OAuth 1.0a User Context, App only, or OAuth 2.0 Authorization Code with PKCE to authenticate requests to these endpoints. 

OAuth 1.0a User Context requires you to utilize your API Keys, user Access Tokens, and a handful of other parameters to create an authorization header, which you will then pass with your request. The Access Tokens must be associated with the user that you are making the request on behalf of. If you would like to generate a set of Access Tokens for another user, they must authorize your App using the 3-legged OAuth flow. 

Please note that OAuth 1.0a can be difficult to use. If you are not familiar with this authentication method, we recommend that you use a library, use a tool like Postman, or use OAuth 2.0 to authenticate your requests. If you would like to request a Post or private metrics from these endpoints, you will need to use a either OAuth 1.0a User Context or OAuth 2.0 Authorization Code with PKCE, which will ensure that you have the proper permissions from the user that owns that content.  

App only just requires that you pass an App only Access Token with your request. You can either generate an App only Access Token from directly within a developer App, or generate one using the POST oauth2/token endpoint.

OAuth 2.0 Authorization Code with PKCE allows for greater control over an application’s scope, and authorization flows across multiple devices. OAuth 2.0 allows you to pick specific fine-grained scopes which give you specific permissions on behalf of a user. 

To enable OAuth 2.0 in your App, you must enable it in your’s App’s authentication settings found in the App settings section of the developer portal.

Please note

If you are requesting the following fields, OAuth 1.0a User Context or OAuth 2.0 Authorization Code is required: 

• tweet.fields.non_public_metrics
• tweet.fields.promoted_metrics
• tweet.fields.organic_metrics

​

Developer portal, Projects, and developer Apps

To retrieve a set of authentication credentials that will work with the X API v2 endpoints, you must sign up for a developer account, set up a Project within that account, and created a developer App within that Project. You can then find your keys and tokens within your developer App.   

​

Rate limits

Every day, many thousands of developers make requests to the X API. To help manage the sheer volume of these requests, rate limits are placed on each endpoint that limits the number of requests that you can make on behalf of your app or on behalf of an authenticated user. 

The user lookup endpoints are rate limited at both the app-level and the user-level. However, the authenticated user lookup endpoint is rate limited at the user-level

The app-level rate limit means that you, the developer, can only make a certain number of requests to this endpoint over a given period of time from any given App (assumed by the keys and tokens that you are using. The user-level rate limit means that the authenticated user that you are making the request on behalf of can only perform a certain number of times across any developer App.

The chart below shows the rate limits for each endpoint.

​

Fields and expansions

The X API v2 allows users to select exactly which data they want to return from the API using a set of tools called fields and expansions. The expansion parameter allows you to expand objects referenced in the payload. For example, this endpoint allows you to use the pinned_tweet_id expansion.

The fields parameter allows you to select exactly which fields within the different data objects you would like to receive. These endpoints delivers user objects primarily. By default, the user object returns the id, name, and username fields. To receive additional fields such as user.created_at or user.location, you will have to specifically request those using a fields parameter. Some important fields that you may want to consider using in your integration are our Post poll data, metrics, annotations, and conversation ID fields.

We’ve added a guide on how to use fields and expansions in our X API v2 data dictionary.

​

Edge cases

• Post text is truncated for Retweets. The short term workaround is to expand the referenced Post and retrieve the full text from the expansion. This is a bug that we will fix in the future.

​

Comparing X API’s users lookup endpoints

The v2 user lookup endpoints will replace the standard v1.1 GET users/lookup and GET users/show endpoints. If you have code, apps, or tools that use one of these versions of the user lookup endpoints, and are considering migrating to the newer X API v2 endpoint, then this set of guides is for you.   

The following tables compare the various types of users lookup endpoints:  

Other migration resources

User lookup: Standard v1.1 to X API v2

X API migration hub

Check out some sample code for these endpoints

​

Standard v1.1 compared to X API v2

If you have been working with the standard v1.1 GET users/show and GET users/lookup, the goal of this guide is to help you understand the similarities and differences between the standard and X API v2 users lookup endpoints.

• Similarities
  • OAuth 1.0a User Context
  • Users per request limits
• Differences
  • Endpoint URLs
  • App and Project requirements
  • Response data format
  • Request parameters

​

Similarities

OAuth 1.0a User Context authentication method

The standard endpoint supports OAuth 1.0a User Context, while the new X API v2 users lookup endpoints supports both OAuth 1.0a User Context and App only. Therefore, if you were previously using one of the standard v1.1 users lookup endpoints, you can continue using the same authentication method if you migrate to the X API v2 version. 

Depending on your authentication library/package of choice, App only authentication is probably the easiest way to get started and can be set with a simple request header. To learn how to generate an App only Access Token, see this App only guide. 

Users per request limits

The standard v1.1 GET users/lookup endpoint allows you to specify 100 users per request. This also goes for the GET /users and GET /users/by endpoints. To specify a full 100 users, you will need to pass the ids (GET /users) parameter or the username (GET /users/by) parameter as a query parameter, and include the list of user IDs/usernames in a comma-separated list.   

​

Differences

Endpoint URLs

• Standard v1.1 endpoints:
  • https://api.x.com/1.1/users/show (single-ID or username lookup)
  • https://api.x.com/1.1/users/lookup (multi-ID or username lookup)
• X API v2 endpoint:
  • https://api.x.com/2/users (multi-ID lookup)
  • https://api.x.com/2/users/:id (single-ID lookup)
  • https://api.x.com/2/users/by (multi-username lookup)
  • https://api.x.com/2/users/by/username/:username (single-username lookup)

App and Project requirements

The X API v2 endpoints require that you use credentials from a developer App that is associated to a Project when authenticating your requests. All X API v1.1 endpoints can use credentials from standalone Apps or Apps associated with a project. 

Response data format

One of the biggest differences between standard v1.1 and X API v2 endpoint versions is how you select which fields return in your payload.

For the standard endpoints, you receive many of the response fields by default, and then have the option to use parameters to identify which fields or sets of fields should return in the payload.

The X API v2 version only delivers the user id , name, and username fields by default. To request any additional fields or objects, you wil need to use the fields and expansions parameters. Any user fields that you request from this endpoint will return in the primary user object. Any expanded Post object and fields will return in an includes object within your response. You can then match any expanded objects back to the user object by matching the IDs located in both the user and the expanded Post object. 

We encourage you to read more about these new parameters in their respective guides, or by reading our guide on how to use fields and expansions. 

We have also put together a data format migration guide which can help you map standard v1.1 fields to the newer v2 fields. This guide will also provide you the specific expansion and field parameter that you will need to pass with your v2 request to return specific fields.   

In addition to the changes in how you request certain fields, X API v2 is also introducing new JSON designs for the objects returned by the APIs, including Post and user objects.

• At the JSON root level, the standard endpoints return Post objects in a statuses array, while X API v2 returns a data array. 
• Instead of referring to Retweeted and Quoted “statuses”, X API v2 JSON refers to Retweeted and Quoted Tweets. Many legacy and deprecated fields, such as contributors and user.translator_type are being removed. 
• Instead of using both favorites (in Post object) and favourites (in user object), X API v2 uses the term like. 
• X is adopting the convention that JSON values with no value (for example, null) are not written to the payload. Post and user attributes are only included if they have a non-null values.   

We also introduced a new set of fields to the Post object including the following:

• A conversation_id field
• Two new annotations fields, including context and entities
• Several new metrics fields 
• A new reply_setting field, which shows you who can reply to a given Post

Request parameters

The following standard v1.1 request parameters have equivalents in X API v2:

There are also a set of standard users lookup request parameters not supported in X API v2:

​

API reference index

For the complete API reference, select an endpoint from the list:

​

GET /2/users/:id

Returns a variety of information about a single user specified by the requested ID.

​

Endpoint URL

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

​

Authentication and rate limits

​

OAuth 2.0 scopes required by this endpoint

Path parameters

​

Query parameters

​

Example code with offical SDKs

• TypeScript (Default fields)
• TypeScript (Optional fields)
• Java (Default fields)
• Java (Optional fields)

(async () => {
  try {
    const getUserById = await twitterClient.users.findUserById(
      //The User ID
      2244994945
    );
    console.dir(getUserById, {
      depth: null,
    });
  } catch (error) {
    console.log(error);
  }
})();

​

Example responses

• Default fields
• Optional fields

{
  "data": {
    "id": "2244994945",
    "name": "Twitter Dev",
    "username": "TwitterDev"
  }
}

​

Response fields

​

GET /2/users

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

​

Endpoint URL

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

​

Authentication and rate limits

​

OAuth 2.0 scopes required by this endpoint

​

Query parameters

​

Example code with offical SDKs

• TypeScript (Default fields)
• TypeScript (Optional fields)
• Java (Default fields)
• Java (Optional fields)

(async () => {
  try {
    const userIdsLookup = await twitterClient.users.findUsersById({
      //A list of User IDs, comma-separated. You can specify up to 100 IDs.
      ids: ["2244994945", "6253282"]
    });
    console.dir(userIdsLookup, {
      depth: null,
    });
  } catch (error) {
    console.log(error);
  }
})();

​

Example responses

• Default fields
• Optional fields

{
  "data": [
    {
      "id": "2244994945",
      "username": "TwitterDev",
      "name": "Twitter Dev"
    },
    {
      "id": "783214",
      "username": "Twitter",
      "name": "Twitter"
    }
  ]
}

​

Response fields

​

GET /2/users/by/username/:username

Returns a variety of information about one or more users specified by their usernames.

​

Endpoint URL

https://api.x.com/2/users/by/username/:username

​

Authentication and rate limits

​

OAuth 2.0 scopes required by this endpoint

​

Path parameters

​

Query parameters

​

Example code with offical SDKs

• TypeScript (Default fields)
• TypeScript (Optional fields)
• Java (Default fields)
• Java (Optional fields)

(async () => {
  try {
    const usernameLookup = await twitterClient.users.findUserByUsername(
      //The Twitter username (handle) of the user.
      "TwitterDev"
    );
    console.dir(usernameLookup, {
      depth: null,
    });
  } catch (error) {
    console.log(error);
  }
})();

​

Example responses

• Default fields
• Optional fields

{
  "data": {
    "id": "2244994945",
    "name": "Twitter Dev",
    "username": "TwitterDev"
  }
}

​

Response fields

​

GET /2/users/by

Returns a variety of information about one or more users specified by their usernames.

​

Endpoint URL

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

​

Authentication and rate limits

​

OAuth 2.0 scopes required by this endpoint

​

Query parameters

​

Example code with offical SDKs

• TypeScript (Default fields)
• TypeScript (Optional fields)
• Java (Default fields)
• Java (Optional fields)

(async () => {
  try {
    const usernamesLookup = await twitterClient.users.findUsersByUsername({
      //A list of usernames, comma-separated. You can specify up to 100 usernames.
      usernames: ["TwitterDev", "Twitter"]
    });
    console.dir(usernamesLookup, {
      depth: null,
    });
  } catch (error) {
    console.log(error);
  }
})();

​

Example responses

• Default fields
• Optional fields

{
  "data": [
    {
      "id": "2244994945",
      "username": "TwitterDev",
      "name": "Twitter Dev"
    },
    {
      "id": "783214",
      "username": "Twitter",
      "name": "Twitter"
    }
  ]
}

​

Response fields

​

GET /2/users/me

Returns information about an authorized user.

​

Endpoint URL

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

​

Authentication and rate limits

​

OAuth 2.0 scopes required by this endpoint

​

Query parameters

​

Example code with offical SDKs

• TypeScript (Default fields)
• TypeScript (Optional fields)
• Java (Default fields)
• Java (Optional fields)

(async () => {
  try {
    const getCurrentUser = await twitterClient.users.findMyUser();
    console.dir(getCurrentUser, {
      depth: null,
    });
  } catch (error) {
    console.log(error);
  }
})();

​

Example responses

• Default fields
• Optional fields

{
  "data": {
    "id": "2244994945",
    "name": "TwitterDev",
    "username": "Twitter Dev"
  }
}

​

Response fields

​

GET /2/users/:id/following

Returns a list of users the specified user ID is following.

​

Endpoint URL

https://api.x.com/2/users/:id/following

​

Authentication and rate limits

​

OAuth 2.0 scopes required by this endpoint

​

Path parameters

​

Query parameters

​

Example code with offical SDKs

• TypeScript (Default fields)
• TypeScript (Optional fields)
• Java (Default fields)
• Java (Optional fields)

(async () => {
  try {
    const getUsersFollowing = await twitterClient.users.usersIdFollowing(
      //The ID of the user for whom to return results
      "2244994945"
    );
    console.dir(getUsersFollowing, {
      depth: null,
    });
  } catch (error) {
    console.log(error);
  }
})();

​

Example responses

• Default fields
• Optional fields

{
  "data": [
    {
      "id": "6253282",
      "name": "Twitter API",
      "username": "TwitterAPI"
    },
    {
      "id": "2244994945",
      "name": "Twitter Dev",
      "username": "TwitterDev"
    },
    {
      "id": "783214",
      "name": "Twitter",
      "username": "Twitter"
    },
    {
      "id": "95731075",
      "name": "Twitter Safety",
      "username": "TwitterSafety"
    },
    {
      "id": "3260518932",
      "name": "Twitter Moments",
      "username": "TwitterMoments"
    },
    {
      "id": "373471064",
      "name": "Twitter Music",
      "username": "TwitterMusic"
    },
    {
      "id": "791978718",
      "name": "Twitter Official Partner",
      "username": "OfficialPartner"
    },
    {
      "id": "17874544",
      "name": "Twitter Support",
      "username": "TwitterSupport"
    },
    {
      "id": "234489024",
      "name": "Twitter Comms",
      "username": "TwitterComms"
    },
    {
      "id": "1526228120",
      "name": "Twitter Data",
      "username": "TwitterData"
    }
  ],
  "meta": {
    "result_count": 10,
    "next_token": "DFEDBNRFT3MHCZZZ"
  }
}

​

Response fields