Skip to content

List Search

GET/tw-v2/list/search

1 API unit per call · How billing works

Description

Search X Lists by keyword. Returns a paginated set of Lists.

Usage notes

Pages hold about 20 Lists, sometimes fewer. A short page does not mean the end: keep passing nextCursor until it is null.

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

Query Parameters

ParameterDescription
querystringrequiredSearch keyword
cursorstringoptionalPagination cursor from the previous response's nextCursor. Omit for the first page.

Code Examples

const params = new URLSearchParams({
  query: 'open source intelligence'
});

const response = await fetch(`https://api.tweetapi.com/tw-v2/list/search?${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
  }
}

Each item is a List with its owner's profile.

A search without matches, or the last page, can be empty:

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

Errors

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

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

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