Manage Lists

​

Introduction

X Lists allows users to customize, organize and prioritize the Posts they see in their timeline. With the Lists endpoints, you can build solutions that enable people to curate and organize Posts based on preferences, interests, groups, or topics.

Since you are making requests on behalf of a user with the manage List endpoints, you must authenticate these endpoints with either OAuth 1.0a User Context or OAuth 2.0 Authorization Code with PKCE, and use the user Access Tokens associated with a user that has authorized your App, which can be generated using the 3-legged OAuth flow (OAuth 1.0a) or the Authorization Code with PKCE grant flow) (OAuth 2.0).  

​

Manage Lists

The manage List endpoints allow you to create, delete, and update Lists on behalf of an authenticated user. For these endpoints, there are three methods available: POST, DELETE and PUT. The POST method allows you to create a List, the DELETE method allows you to delete a List, and the PUT method allows you to update the metadata of a List. There is a user rate limit of 300 requests per 15 minutes for all three endpoints.

Note that you can create up to 1000 Lists per account.

Account setup

To access these endpoints, you will need:

• An approved developer account.
• To authenticate using the 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 guide.

​

Getting started with the manage Lists endpoint group

This quick overview will help you make your first request to the manage List endpoints using Postman.

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

**Note: **For this example, we will make a request to the Create a List endpoint, but you can apply the learnings from this quick start to other manage requests as well.

​

Steps to build a manage List 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 “Manage List”, and then choose “Create a List”.

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. To do this with the manage Posts endpoints, 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 (and 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).

If you’ve done this correctly, these variables will automatically be pulled into the request’s authorization tab.   Step three: Specify the name for the new List

When creating a new List with this endpoint, a name for the List is a required body parameter. Optionally, you can provide a description and specify whether the List is private.

In Postman, navigate to the “Body” tab and enter the name of the List as the value for the name parameter. Additionally, if you wish to add a description for the List, simply add a new key labeled description in the same fashion as the name, followed by the description of the List as the value. Making a List private will follow the same pattern, but only true or false values are accepted for this parameter. 

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

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

Code copied to clipboard

Step four: 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": "1441162269824405510",
    "name": "New list created from Postman"
  }
}

If the returned response object contains an id and the name of your List, you have successfully created the List. 

To delete a List, select the “Delete a List” request also found in the “Lists” folder of the X API v2 collection loaded in Postman. This endpoint requires the ID of the List you wish to delete. In the “Params” tab, enter the ID of the List you wish to delete as the value for the id column. 

On successful delete request, you will receive a response similar to the following example: 

{
  "data": {
    "deleted": true
  }
}

​

Integration guide

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

​

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. 

These specific endpoints requires the use of 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 or authenticate your App using the 3-legged OAuth flow.

Please note that OAuth 1.0a can be tricky to use. If you are not familiar with this authentication method, we recommend that you use a library or a tool like Postman to properly authenticate your requests.  

​

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. 

These endpoints are rate limited at the user level, meaning that the authenticated user that you are making the request on behalf of can only call the endpoint a certain number of times across any developer App. 

The chart below shows the rate limits for each endpoint.

​

Comparing X API’s Lists endpoints

The v2 manage Lists endpoints will eventually replace POST lists/create, POST lists/destroy, and POST lists/update. If you have code, apps, or tools that use an older version of these endpoints and are considering migrating to the newer X API v2, then this guide is for you. 

The following tables compare the standard v1.1 and X API v2 List endpoints:

Create a List

Delete a List

Update a List

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.

​

Manage Lists: Standard v1.1 compared to X API v2

If you have been working with the standard v1.1 POST lists/create, POST lists/destroy, and POST lists/update endpoints, the goal of this guide is to help you understand the similarities and differences between the standard v1.1 and X API v2 manage List endpoints.

• Similarities
  • Authentication
• Differences
  • Endpoint URLs
  • App and Project requirements
  • HTTP methods
  • Rate limits
  • Request parameters

​

Similarities

Authentication

Both endpoint versions support OAuth 1.0a User Context. Therefore, if you were previously using one of the standard v1.1 manage Lists endpoints, you can continue using the same authentication method if you migrate to the X API v2 version.

​

Differences

Endpoint URLs

• Standard v1.1 endpoints:
  • POST https://api.x.com/1.1/lists/create.json (Creates a List)
  • POST https://api.x.com/1.1/lists/destroy.json (Deletes a List)
  • POST https://api.x.com/1.1/lists/update.json (Updates a List)
• X API v2 endpoint:

  • POST https://api.x.com/2/lists (Creates a List)

  • DELETE https://api.x.com/2/lists/:id (Deletes a List)

  • PUT https://api.x.com/2/lists/:id (Updates a List)

Rate limits

App and Project requirements

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

Request parameters

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

Create a List

Delete/Update a List

​

API reference index

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

​

Manage Lists

​

POST /2/lists

Enables the authenticated user to create a List.

​

Endpoint URL

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

​

Authentication and rate limits

​

OAuth 2.0 scopes required by this endpoint

​

JSON body parameters

​

Example code with offical SDKs

• TypeScript
• Java

(async () => {
  try {
    const createList = await twitterClient.lists.listIdCreate({
      name: "test v2 create list",
      description: "example create",
      private: false,
    });
    console.dir(createList, {
      depth: null,
    });
  } catch (error) {
    console.log(error);
  }
})();

​

Example responses

• Successful response

{
  "data": {
    "id": "1441162269824405510",
    "name": "test v2 create list"
  }
}

​

Response fields

​

PUT /2/lists/:id

Enables the authenticated user to update the meta data of a specified List that they own.

​

Endpoint URL

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

​

Authentication and rate limits

​

OAuth 2.0 scopes required by this endpoint

​

Path parameters

​

JSON body parameters

​

Example code with offical SDKs

• TypeScript
• Java

(async () => {
  try {
    const updateList = await twitterClient.lists.listIdUpdate(
      //The ID of the List to modify
      1441163524802158595,
      {
        name: "test v2 create list",
        description: "example code",
        private: false,
      }
    );
    console.dir(updateList, {
      depth: null,
    });
  } catch (error) {
    console.log(error);
  }
})();

​

Example responses

• Successful response

{
  "data": {
    "updated": true
  }
}

​

Response fields

​

PUT /2/lists/:id

Enables the authenticated user to update the meta data of a specified List that they own.

​

Endpoint URL

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

​

Authentication and rate limits

​

OAuth 2.0 scopes required by this endpoint

​

Path parameters

​

JSON body parameters

​

Example code with offical SDKs

• TypeScript
• Java

(async () => {
  try {
    const updateList = await twitterClient.lists.listIdUpdate(
      //The ID of the List to modify
      1441163524802158595,
      {
        name: "test v2 create list",
        description: "example code",
        private: false,
      }
    );
    console.dir(updateList, {
      depth: null,
    });
  } catch (error) {
    console.log(error);
  }
})();

​

Example responses

• Successful response

{
  "data": {
    "updated": true
  }
}

​

Response fields

​

DELETE /2/lists/:id

Enables the authenticated user to delete a List that they own.

​

Endpoint URL

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

​

Authentication and rate limits

​

OAuth 2.0 scopes required by this endpoint

​

Path parameters

​

Example code with offical SDKs

• TypeScript
• Java

(async () => {
  try {
    const deleteList = await twitterClient.lists.listIdDelete(
      //The ID of the List to delete
      1441162269824405510,
    );
    console.dir(deleteList, {
      depth: null,
    });
  } catch (error) {
    console.log(error);
  }
})();

​

Example responses

• Successful response

{
  "data": {
    "deleted": true
  }
}

​

Response fields