User Lists

GET/tw-v2/user/lists

Description

Retrieve the Lists shown on a user's Lists tab, in the order X shows them. Returns a paginated list of Lists.

Usage notes

These are the Lists X shows on the profile's Lists tab. They are not only Lists the user created: X can include Lists owned by other accounts, so check owner on each List. Every List X returns is included, Private ones too, and mode says which. For the Lists other accounts added this user to, use /tw-v2/user/list-memberships; for the users in one List, use /tw-v2/list/members. A page can be short or even empty without being the last one: keep passing nextCursor until it is null. A user with no Lists returns an empty list.

A request costs one API unit. 400, 401, 403, 429 and 5xx errors are free; a 404 is billed.

Query Parameters

Parameter	Type	Required	Description
userIdstringrequired	string	required	Unique Twitter user ID (e.g., '10017528')
cursorstringoptional	string	optional	Pagination cursor from the previous response's nextCursor. Omit for the first page.

Code Examples

const params = new URLSearchParams({
  userId: '10017528'
});

const response = await fetch(`https://api.tweetapi.com/tw-v2/user/lists?${params}`, {
  method: 'GET',
  headers: {
    'X-API-Key': 'YOUR_API_KEY'
  }
});

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

Response

Success Response (200 OK)

Synthetic example:

200

{
  "data": [
    {
      "id": "3000000000000000003",
      "name": "Sample List",
      "description": "Sample description",
      "mode": "public",
      "memberCount": 19,
      "subscriberCount": 549,
      "createdAt": "2023-11-14T22:13:20.000Z",
      "owner": {
        "id": "1000000000000000901",
        "username": "sample_user_00001",
        "name": "Sample User",
        "bio": "Sample bio",
        "location": "Sample City",
        "website": null,
        "pinnedTweetIds": [],
        "avatar": "https://example.com/images/sample-avatar.jpg",
        "banner": "https://example.com/images/sample-banner.jpg",
        "profileImageShape": null,
        "verified": false,
        "isBlueVerified": false,
        "verifiedType": null,
        "verifiedSince": null,
        "isIdentityVerified": false,
        "isProtected": false,
        "possiblySensitive": false,
        "profileInterstitialType": null,
        "withheldInCountries": [],
        "professional": null,
        "businessAccount": null,
        "creatorSubscriptionsCount": 0,
        "hasHiddenSubscriptions": false,
        "highlightsInfo": null,
        "hasGraduatedAccess": false,
        "isProfileTranslatable": false,
        "hasCustomTimelines": false,
        "isTranslator": false,
        "affiliatesHighlightedLabel": null,
        "defaultProfile": false,
        "defaultProfileImage": false,
        "followerCount": 1200,
        "followingCount": 34,
        "tweetCount": 560,
        "listedCount": 0,
        "mediaCount": 78,
        "favoritesCount": 90,
        "createdAt": "2023-01-02T00:00:00.000Z"
      },
      "bannerUrl": null,
      "defaultBannerMedia": {
        "url": "https://example.com/images/sample-list-banner.jpg",
        "width": 1500,
        "height": 500,
        "salientRect": {
          "left": 0,
          "top": 0,
          "width": 1500,
          "height": 500
        }
      },
      "facepileUrls": [
        "https://example.com/images/sample-avatar.jpg"
      ],
      "slug": "",
      "uri": ""
    }
  ],
  "pagination": {
    "nextCursor": "NEXT_CURSOR",
    "prevCursor": null
  }
}

Pass pagination.nextCursor as cursor to get the next page. It is null on the last page. owner is the account that owns the List, which can differ from userId. A Private List has "mode": "private".

A user with no Lists returns an empty list:

200

{
  "data": [],
  "pagination": {
    "nextCursor": null,
    "prevCursor": null
  }
}

Errors

Errors return { statusCode, message } with a non-2xx HTTP status.

An unknown user returns 404 and a suspended user returns 403. If X sends a List without its required fields or with an unknown mode, the request returns 502 instead of a partial list. Only the known List banner error is ignored. Other X errors fail the request with the corresponding HTTP status, such as 400 for an invalid request or 429 for a rate limit.

400

{
  "statusCode": 400,
  "message": "Request validation failed"
}

TweetAPI is a third-party API and is not affiliated with X Corp.