Skip to content

Create List

POST/tw-v2/list/create

1 API unit per call · How billing works

Description

Create a list for the authenticated Twitter/X account.

Request Body

ParameterDescription
authTokenstringrequiredAccount authentication token (auth_token cookie value)
namestringrequiredList name, up to 25 characters
descriptionstringoptionalOptional list description, up to 100 characters. Defaults to an empty string.
isPrivatebooleanoptionalWhether the list should be private. Defaults to true.
proxystringoptionalOptional proxy in format 'host:port@user:pass'

Code Examples

const body = {
  authToken: 'YOUR_AUTH_TOKEN',
  name: 'Market Watch',
  description: 'Accounts to monitor for market updates',
  isPrivate: true
};

const response = await fetch('https://api.tweetapi.com/tw-v2/list/create', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(body)
});

const data = await response.json();
console.log(data);

Response

Success Response (200 OK)

200
{
  "data": {
    "id": "9004718786321977501",
    "name": "Market Watch",
    "description": "Accounts to monitor for market updates",
    "mode": "private",
    "memberCount": 0,
    "subscriberCount": 0,
    "createdAt": "2026-06-22T10:12:00.000Z",
    "owner": {
      "id": "10017528",
      "username": "sample_user_96991",
      "name": "Sample User 96991",
      "avatar": "https://example.com/images/sample-avatar-96991.jpg",
      "verified": false,
      "isBlueVerified": true,
      "isProtected": false
    },
    "bannerUrl": null,
    "defaultBannerMedia": null,
    "facepileUrls": [],
    "slug": "",
    "uri": ""
  }
}