POST /2/lists

POST /2/lists

Enables the authenticated user to create a List.

Endpoint URL

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

Authentication and rate limits

Authentication methods
supported by this endpoint

OAuth 2.0 Authorization Code with PKCE

OAuth 1.0a is also available for this endpoint.

Rate limit

User rate limit (User context): 300 requests per 15-minute window per each authenticated user

OAuth 2.0 scopes required by this endpoint

tweet.read

users.read

list.read

list.write

Learn more about OAuth 2.0 Authorization Code with PKCE

JSON body parameters

NameTypeDescription
name
 Required 
stringThe name of the List you wish to create.
description
 Optional 
stringDescription of the List.
private
 Optional 
booleanDetermine whether the List should be private.


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);
  }
})();

    
      // Set the params values

ListCreateRequest listCreateRequest = new ListCreateRequest();
listCreateRequest.name("test v2 create list");
listCreateRequest.description("example create");
listCreateRequest._private(false);

try {
    ListCreateResponse result = apiInstance.lists().listIdCreate(listCreateRequest);
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ListsApi#listIdCreate");
    System.err.println("Status code: " + e.getCode());
    System.err.println("Reason: " + e.getResponseBody());
    System.err.println("Response headers: " + e.getResponseHeaders());
    e.printStackTrace();
}

    

Example responses

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

Response fields

NameTypeDescription
idnumberThe id of the newly created List.
namestringThe name of the newly created List.