Twitter list search API: find X lists by keyword

{
  "lists": [],
  "has_next_page": false,
  "next_cursor": ""
}

{
  "error": "missing_query",
  "message": "Search query required. Use q."
}

{
  "error": "unauthenticated",
  "message": "Authentication required."
}

{
  "error": "insufficient_credits",
  "message": "Insufficient credits. Top up or subscribe to continue."
}

{
  "error": "x_api_unavailable",
  "message": "X data source temporarily unavailable. Try again later."
}

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Try again later.",
  "retryAfter": 60
}

{
  "error": "x_api_unavailable",
  "message": "X data source temporarily unavailable. Try again later."
}

{
  "error": "x_api_unavailable",
  "message": "Xquik is busy right now. Retry shortly."
}

GET

lists

Twitter list search API: find X lists by keyword

curl --request GET \
  --url https://xquik.com/api/v1/x/lists/search

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://xquik.com/api/v1/x/lists/search"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "lists": [
    {
      "id": "<string>",
      "name": "<string>",
      "description": "<string>",
      "memberCount": 123,
      "subscriberCount": 123,
      "owner": {},
      "url": "<string>",
      "createdAt": "<string>",
      "bannerUrl": "<string>",
      "customBanner": {},
      "defaultBanner": {},
      "facepileUrls": [
        "<string>"
      ],
      "membersContext": "<string>"
    }
  ],
  "has_next_page": true,
  "next_cursor": "<string>"
}

Requested result counts are upper bounds for paid authenticated calls. When remaining credits cannot cover the full page, Xquik returns fewer results. If zero paid results are affordable, it returns 402 insufficient_credits.

1 credit per List returned · All plans from $0.00012/credit

curl -G https://xquik.com/api/v1/x/lists/search \
  --data-urlencode "q=space news" \
  -H "x-api-key: xq_your_api_key_here" | jq

const query = "space news";
const params = new URLSearchParams({ q: query });
const response = await fetch(`https://xquik.com/api/v1/x/lists/search?${params}`, {
  headers: { "x-api-key": "xq_your_api_key_here" },
});
const data = await response.json();
const nextCursor = data.has_next_page ? data.next_cursor : null;
const listRows = data.lists.map((list, index) => ({
  search_query: query,
  result_rank: index + 1,
  list_id: list.id,
  list_name: list.name,
  member_count: list.memberCount ?? null,
  follower_count: list.subscriberCount ?? null,
  owner_username: list.owner?.username ?? null,
  list_url: list.url ?? null,
  next_cursor: nextCursor,
}));

import requests

query = "space news"
response = requests.get(
    "https://xquik.com/api/v1/x/lists/search",
    params={"q": query},
    headers={"x-api-key": "xq_your_api_key_here"},
)
data = response.json()
next_cursor = data["next_cursor"] if data["has_next_page"] else None
list_rows = [
    {
        "search_query": query,
        "result_rank": index + 1,
        "list_id": item["id"],
        "list_name": item["name"],
        "member_count": item.get("memberCount"),
        "follower_count": item.get("subscriberCount"),
        "owner_username": (item.get("owner") or {}).get("username"),
        "list_url": item.get("url"),
        "next_cursor": next_cursor,
    }
    for index, item in enumerate(data["lists"])
]

The Node.js and Python snippets build 1 row per List. Store listRows or list_rows with nextCursor or next_cursor before requesting the next page.

Find Lists before you read them

Use GET /x/lists/search when you know a topic but not a List ID. It returns the public Lists X finds for your keywords, in X’s order. X may rank the Lists differently per request. Each List carries the id that List members, List followers and List tweets take. Compare memberCount, subscriberCount and the owner profile to pick a List. A List with many followers is often a well-kept source. Store the List id, since a List name can change. An empty lists array with has_next_page: false means X has no more Lists for your keywords. It costs nothing.

Query parameters

string

required

Keywords to find Lists by, such as a topic or a List name. Alias: query.

string

Pagination cursor from a previous response. Omit for the first page.

integer

Lists per page. Range: 1-100. Defaults to 20. Aliases: limit, count, and max_results.

Headers

string

Full account key. Sessions and OAuth also work.

string

Bearer xq_your_guest_key_here for paid_reads.

Response

200 OK

object[]

Public Lists that match your keywords. List object fields.

string

Numeric List ID.

string

List name.

string

List description. Empty when the owner wrote none.

number

Accounts on the List.

number

Accounts that follow the List.

object

Public profile of the account that owns the List, with the fields of Get User.

string

List page on x.com.

string

When the owner made the List (ISO 8601).

string

URL of the banner the owner uploaded. Omitted when the owner uploaded none.

object

Banner the owner uploaded: url, width, height, salientRect, mediaId, mediaKey & dominant colors in palette. Omitted when there is none.

object

Banner X shows when the owner uploaded none: url, width, height & salientRect. X picks it per reading account, so 2 calls can return different ones.

string[]

Avatar URLs of a few List members, which X may pick per request.

string

Member count as X words it, such as 35 members.

boolean

Whether more results are available.

string

Cursor for the next page.

{
  "lists": [
    {
      "id": "1284239399492833280",
      "name": "#Mars2020 Science & Tech",
      "description": "Official accounts on the Perseverance Mars rover mission.",
      "memberCount": 35,
      "subscriberCount": 76,
      "owner": {
        "id": "1232783237623119872",
        "username": "NASAPersevere",
        "name": "NASA's Perseverance Mars Rover",
        "followers": 2887286,
        "verified": true
      },
      "url": "https://x.com/i/lists/1284239399492833280",
      "createdAt": "2020-07-17T21:31:47.000Z",
      "membersContext": "35 members"
    }
  ],
  "has_next_page": true,
  "next_cursor": "DAAHCgABHTwHK3H..."
}

400 Missing query

{ "error": "missing_query", "message": "Search query required. Use q." }

401 Unauthenticated

Anonymous requests get WWW-Authenticate: Bearer and a guest wallet checkout action. This is not a Payment challenge.

{ "error": "unauthenticated" }

402 Payment required

Account keys get account options. Guest keys get guest top-up only. No checkout starts automatically. Confirm any payment action.

502 X API unavailable

{ "error": "x_api_unavailable" }

The read service returned an error. Retry after a short delay.

503 Service busy

{ "error": "x_api_unavailable" }

Xquik is busy. Wait for Retry-After, then retry.

429 Rate limit exceeded

{ "error": "rate_limit_exceeded", "retryAfter": 60 }

The Xquik tier limit blocked the request. Use Retry-After when present. Otherwise, use the JSON retryAfter field.

424 Dependency failed

{ "error": "x_api_unavailable" }

The opt-in normalized contract returns 424 when the read service fails. Send xquik-api-contract: 2026-04-29 to opt in. Default v1 returns 502.

Twitter List search questions

How do I search Twitter Lists by keyword?

Call GET /x/lists/search with your keywords in q. Each result is a public List with its ID, counts and owner.

How much does a List search cost?

Each returned List costs 1 credit. An empty page costs nothing. Lower pageSize to return fewer Lists.

Does List search return private Lists?

No. It returns only public Lists. Private Lists stay out of every answer.

Why do 2 searches return Lists in another order?

X may rank the Lists differently per request. Store each List id and dedupe by it when you merge pages or runs.

How do I get the members of a List I found?

Pass the List id to List members. Use List tweets for its timeline.

Does this replace X’s official API?

No. This page documents Xquik, an independent third-party service. It does not document X’s official API.

Next steps. List members reads who is on a List, and List tweets reads its timeline.

{
  "lists": [],
  "has_next_page": false,
  "next_cursor": ""
}

{
  "error": "missing_query",
  "message": "Search query required. Use q."
}

{
  "error": "unauthenticated",
  "message": "Authentication required."
}

{
  "error": "insufficient_credits",
  "message": "Insufficient credits. Top up or subscribe to continue."
}

{
  "error": "x_api_unavailable",
  "message": "X data source temporarily unavailable. Try again later."
}

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Try again later.",
  "retryAfter": 60
}

{
  "error": "x_api_unavailable",
  "message": "X data source temporarily unavailable. Try again later."
}

{
  "error": "x_api_unavailable",
  "message": "Xquik is busy right now. Retry shortly."
}

Twitter list search API: find X lists by keyword

curl --request GET \
  --url https://xquik.com/api/v1/x/lists/search

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://xquik.com/api/v1/x/lists/search"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "lists": [
    {
      "id": "<string>",
      "name": "<string>",
      "description": "<string>",
      "memberCount": 123,
      "subscriberCount": 123,
      "owner": {},
      "url": "<string>",
      "createdAt": "<string>",
      "bannerUrl": "<string>",
      "customBanner": {},
      "defaultBanner": {},
      "facepileUrls": [
        "<string>"
      ],
      "membersContext": "<string>"
    }
  ],
  "has_next_page": true,
  "next_cursor": "<string>"
}

Overview

X API

X write

Trends

Radar

Account

API keys

Guest wallets

Credits

X accounts

Monitors

Events

Webhooks

Draws

Extractions

Compose

Drafts

Styles

Support

Twitter list search API: find X lists by keyword

Find Lists before you read them

Query parameters

Headers

Response

200 OK

400 Missing query

401 Unauthenticated

402 Payment required

502 X API unavailable

503 Service busy

429 Rate limit exceeded

424 Dependency failed

Twitter List search questions

How do I search Twitter Lists by keyword?

How much does a List search cost?

Does List search return private Lists?

Why do 2 searches return Lists in another order?

How do I get the members of a List I found?

Does this replace X’s official API?

​Find Lists before you read them

​Query parameters

​Headers

​Response

​200 OK

​400 Missing query

​401 Unauthenticated

​402 Payment required

​502 X API unavailable

​503 Service busy

​429 Rate limit exceeded

​424 Dependency failed

​Twitter List search questions

​How do I search Twitter Lists by keyword?

​How much does a List search cost?

​Does List search return private Lists?

​Why do 2 searches return Lists in another order?

​How do I get the members of a List I found?

​Does this replace X’s official API?

Find Lists before you read them

Query parameters

Headers

Response

200 OK

400 Missing query

401 Unauthenticated

402 Payment required

502 X API unavailable

503 Service busy

429 Rate limit exceeded

424 Dependency failed

Twitter List search questions

How do I search Twitter Lists by keyword?

How much does a List search cost?

Does List search return private Lists?

Why do 2 searches return Lists in another order?

How do I get the members of a List I found?

Does this replace X’s official API?