List lookup

​

Introduction

There is a rate limit of 75 requests per 15 minutes when looking up a specified List by ID and a limit of 15 requests per 15 minutes when looking up user-owned Lists.

You can use OAuth 1.0a User Context, [App only](https://developer.twitter.com(/resources/fundamentals/authentication#app-only-authentication-and-oauth-2-0-bearer-token), or OAuth 2.0 Authorization Code with PKCE to authenticate your requests to these endpoints. 

​

Getting started with the List lookup endpoint

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

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

**Note: **For this example, we will make a request to the _List lookup by ID _endpoint, but you can apply the learnings from this quick start to other lookup requests as well.

​

Steps to build a List 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 “List” folder, select another folder “List lookup”, and then choose “List by ID”.  

Step two: Authenticate your request

To properly make a request to the X API, you need to verify that you have permission. To do this with this endpoint, you must 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 are going to utilize App only with this request, but if you’d like to request private metrics or Lists, you will need to use one of the other authentication methods. 

To utilize App only, you must add your keys and tokens (specifically theApp only Access Token) to Postman 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).

If you’ve done this correctly, these variables will automatically be pulled into the request’s authorization tab.  

Step three: Identify and specify which List you would like to retrieve

You must specify a List that you would like to receive within the request. You can find the List ID by navigating to x.com and clicking on a List and then looking in the URL. For example, the following URL’s List ID is 84839422.

https://twitter.com/i/lists/84839422

The target ID can be any valid List ID. In Postman, navigate to the “Params” tab, and enter your ID into the “Value” column of the id path variable. Be sure not to include any spaces before or after any ID.

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 List object fields in your response: id, name.

If you would like to receive additional fields, you will have to specify those fields in your request with list.fields and/or expansion parameters.

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

• The additional created_at field in the primary Lists object.

• The full user object using the expansion parameter

• The additional user.created_at field in the associated user object.

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/lists/84839422?list.fields=owner_id&expansions=owner_id&user.fields=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 a similar response to the following example response:

{
  "data": {
    "id": "84839422",
    "name": "Official Twitter Accounts",
    "owner_id": "783214"
  },
  "includes": {
    "users": [
      {
        "name": "Twitter",
        "created_at": "2007-02-20T14:35:54.000Z",
        "username": "Twitter",
        "id": "783214"
      }
    ]
  }
}

​

Integration guide

This page contains information on several tools and critical concepts that you should know as you integrate the List 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
• Pagination

​

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

Are you 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 you to authenticate your requests 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 your requests to these endpoints. . 

OAuth 1.0a User Context, which means that you must use a set of API Keys and user Access Tokens to make a successful 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.

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.

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

​

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 you can make on behalf of your app or on behalf of an authenticated user. 

These endpoints are rate limited at both the App-level and the user-level. The app 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 using either the API Key and API Secret Key, or the App only Access Token). The user rate limit means that the authenticated user that you are making the request on behalf of can only perform a List lookup 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 GET endpoint allows users to select exactly which data they want to return from the API using a set of tools called fields and expansions. The expansions parameter allows you to expand objects referenced in the payload. For example, looking up a List by ID allows you to pull the following expansions:

• owner_id

The fields parameter allows you to select exactly which fields within the different data objects you would like to receive. These endpoints deliver List objects primarily. By default, the List object returns the id, and name fields. To receive additional fields such as list.created_at or list.follower_count, you will have to specifically request those using a list.fields parameter. 

We’ve added a guide on using fields and expansions together to our X API v2 data dictionary.

 The chart below shows the field and expansions available for this endpoint group:

​

Pagination

Looking up user owned Lists can return a lot of data. To ensure we are returning consistent, high-performing results at any given time, we use pagination. Pagination is a feature in X API v2 endpoints that return more results than can be returned in a single response. When that happens, the data is returned in a series of ‘pages’. Learn more about how to paginate through results.

​

Comparing X API’s List lookup endpoints

The v2 List lookup endpoint group will replace the standard v1.1 GET lists/show and  GET lists/ownership endpoints. If you have code, apps, or tools that use one of these versions of the List 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 standard v1.1 and X API v2 List endpoints:

List Lookup by ID

User owned List lookup

To access the X API v2 endpoints, you must sign up for a developer account. When authenticating, you must use keys and tokens from a developer App that is located within a Project. 

Learn more about getting access to the X API v2 endpoints in our getting started page.

​

List lookup: Standard v1.1 compared to X API v2

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

• Similarities
  • Authentication methods
  • Rate limits
• Differences
  • Endpoint URLs
  • App and Project requirements
  • Data objects per request limits
  • Response data formats
  • Request parameters

​

Similarities

Authentication

Both endpoint versions support both OAuth 1.0a User Context and App only. Therefore, if you were previously using one of the standard v1.1 List 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.

Rate limits

​

Differences

Endpoint URLs

• Standard v1.1 endpoints:
  • GET https://api.x.com/1.1/lists/show.json (Lookup a specified List)
  • GET https://api.x.com/1.1/lists/ownerships.json (Lookup specified user owned Lists)
• X API v2 endpoint:

  • GET https://api.x.com/2/lists/:id (Lookup a specified List)

  • GET https://api.x.com/2/users/:id/owned_lists (Lookup specified user owned Lists)

App and Project requirements

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

Data objects per request limits

The standard v1.1 /lists/ownerships endpoint allows you to return up to 1000 Lists per request. The new v2 endpoints allow you to return up to 100 Lists per request. By default, 100 user objects will be returned, to change the number of results you will need to pass a query parameter max_results= with a number between 1-100; you can then pass the next_token returned in the response payload to the pagination_token query parameter in your next request.

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 additional fields or sets of fields should return in the payload.

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

Here are examples of possible List fields and expansions:

• created_at

• follower_count

• member_count

• owner_id

• description

• private

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 that can help you map standard v1.1 fields to the newer v2 fields. This guide will also provide you with 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 non-null values.  

Request parameters

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

List lookup by ID

User owned List lookup

​

API reference index

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

​

GET /2/lists/:id

Returns the details of a specified List.

​

Endpoint URL

https://api.x.com/2/lists/: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 getListBtId = await twitterClient.lists.listIdGet(
      //The ID of the List to get
      84839422
    );
    console.dir(getListBtId, {
      depth: null,
    });
  } catch (error) {
    console.log(error);
  }
})();

​

Example responses

• Default fields
• Optional fields

{
  "data": {
    "id": "84839422",
    "name": "Official Twitter Accounts"
  }
}

​

Response fields

​

GET /2/users/:id/owned_lists

Returns all Lists owned by the specified user.

​

Endpoint URL

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

​

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 getListBtId = await twitterClient.lists.listUserOwnedLists(
      //The ID of the user for whom to return results
      2244994945
    );
    console.dir(getListBtId, {
      depth: null,
    });
  } catch (error) {
    console.log(error);
  }
})();

​

Example responses

• Default fields
• Optional fields

{
  "data": [
    {
      "id": "1451305624956858369",
      "name": "Test List"
    }
  ],
  "meta": {
    "result_count": 1
  }
}

​

Response fields