Twitter List API: Fetch Any List Members at $0.04/1K

The whole List family, and what each endpoint returns

Member enumeration is the endpoint people arrive for, and it is one of seven. The others answer the questions that usually come next: what are these accounts posting, who else is watching this list, and can I build the list from my own pipeline instead of curating it by hand. All seven authenticate with the same Bearer key and page with the same cursor mechanic.

Only list/create sits above the standard rate, at $0.0016, and it is the one call in the family you make once rather than in a loop. Everything else, including adding and removing members, bills at the same $0.0008 as a read.

list/tweets against list/timeline: which one you want

Two endpoints read posts from a list and the names do not make the difference obvious, so it is worth stating plainly. Both take a list id, both page by cursor, and both bill $0.0008 a call.

list/timeline is the list as a reader sees it in the X client: the ranked, blended feed the platform composes from the members. Reach for it when you want the experience, for example mirroring a curated feed into a dashboard, because it reflects what a human following that list would actually encounter.

list/tweets is the posts from the list's members as a collection. Reach for it when you are building a dataset rather than a feed, because a ranked view is a poor foundation for counting: ranking is not stable between calls, so the same crawl run twice returns overlapping but different pages, and a job that treats it as a complete set will both miss posts and duplicate others.

The rule of thumb: if a person will read the output, take the timeline. If a query will aggregate the output, take the tweets. If you need genuine completeness for a specific account, enumerate the members and pull each member's own timeline, which is more calls and the only way to be sure nothing was ranked out.

Building and maintaining a list from your own pipeline

Reading somebody else's curation is half the value. The other half is treating a List as a queryable, machine-maintained object: build it from a search, keep it in step with your CRM, and let it act as a durable filter that both your pipeline and a human in the X client can read. Creating a list and changing its membership are write calls, so they need an authenticated X session rather than only an API key.

import requests

BASE = "https://api.twitterapis.com/twitter"
H = {"Authorization": "Bearer YOUR_API_KEY"}

# $0.0016. Done once, not in a loop.
new_list = requests.post(f"{BASE}/list/create", headers=H, json={
    "name": "Q3 prospects",
    "description": "Built from search, synced nightly",
    "private": True,
}).json()

list_id = new_list["list"]["id"]

# $0.0008 each. Membership changes bill at the read rate.
for user_id in shortlist_from_your_crm():
    requests.post(f"{BASE}/list/add_member", headers=H,
                  json={"list_id": list_id, "user_id": user_id})

Error responses, and which ones to retry

Errors arrive as a consistent envelope, a machine-readable error code beside a human message, so a client branches on the code and logs the message. In a paging loop the distinction that matters is which of these a retry can fix.

One list-specific detail worth building for: hold the cursor you were on when a job dies. Resuming from the last successful cursor turns a failed crawl of a 50,000-member list into a few extra calls rather than a restart, and cursors stay usable for the length of a normal job.

What list data cannot tell you

Lists are one of the more honest signals on X, because somebody chose to put an account on one. That makes it worth being precise about what the signal does not carry, before a dashboard implies more than the data supports.

• Private lists are private. A list marked private is readable only by its owner's authenticated session. No API returns another account's private list, and any vendor implying otherwise is describing something you should not buy.
• Membership carries no endorsement. People list competitors, sources they distrust and accounts they are monitoring. Inclusion means attention, not agreement, which matters most when the list is titled something flattering.
• There is no membership history. X exposes the current members, not when each was added or by whom. If you want to know that a competitor added six accounts last Tuesday, the only way is to have snapshotted the list before and after and diffed them yourself.
• A member who left X still needs handling. Suspended and deleted accounts can persist in a list's membership and come back flagged as unavailable. Store that state rather than dropping the row, or every run re-discovers the same ghost.
• Follower counts on the list page are a snapshot. Every count in a member profile is the value at fetch time. Store the fetch timestamp beside it, or a later comparison is measuring two different moments and calling the difference growth.

The third point is the one that turns a read endpoint into a monitoring product. Snapshot the membership on a schedule, diff consecutive runs, and the additions and removals are the story: who a newsroom started trusting, who a competitor started watching, which analyst quietly dropped off a top-voices list.

Lists against the other ways to define an audience

A list is one of four ways to answer the question of which accounts a job should watch, and it is worth knowing what the alternatives buy you before defaulting to it.

• A keyword search defines an audience by what people say. It is the widest net and the noisiest, it finds accounts nobody has curated, and it needs an engagement floor or a language filter to stay useful. Best when you do not yet know who matters.
• A follower graph defines an audience by who follows whom. It is exhaustive and expensive at scale, it captures genuine attention rather than a curator's judgement, and a single popular account's followers are mostly not practitioners. Best for reach analysis.
• A community defines an audience by declared membership in a topic space. Narrower and higher-signal than a follower graph, with its own endpoints on the same key, and bounded by whether a community exists for your subject at all.
• A list defines an audience by somebody's deliberate curation. It is the highest signal per row of the four, because a human made a judgement about every member, and the smallest and most easily stale, because that human may have stopped maintaining it two years ago.

In practice the strongest pipelines use two together rather than picking one. A list supplies the seed set, and a search or follower crawl expands outward from it, scoring candidates by how many of the seed accounts already interact with them. That gets you both the precision of curation and the coverage of a wide net, and every endpoint involved sits behind the same key at the same flat rate.

The staleness question is the one to answer first, because it is cheap. Enumerate the list once, pull each member's most recent post, and count how many have posted in the last month. A list where a third of the membership is dormant is a historical artefact rather than a live audience, and it is far better to learn that for a few cents than to build a monitor on top of it.

Five things that go wrong with list ids

Almost every 400 and 404 on this endpoint traces back to the identifier rather than the request. These are the five we see, in roughly the order they cost people time.

• Passing the URL instead of the id. The parameter wants the bare numeric string, not x.com/i/lists/1234567890 and not a fragment of it. This is the most common 400 by a wide margin, and it usually arrives from a spreadsheet column somebody pasted links into.
• Using the list name as if it were an identifier. A list has a display name and it is neither unique nor stable. Two people can own lists called the same thing, and an owner can rename one at any moment. The numeric id is the only durable handle.
• Parsing the id as a number. List ids, like every other X identifier, exceed the safe integer range in JavaScript, so Number(id) silently rounds and two different lists can collide on one key. Keep it as a string end to end, and use text or bigint in the database rather than a float column.
• Assuming an id from last year still resolves. Lists get deleted and made private. A 404 on an id that worked before is usually exactly that, not a bug in your client, so record the outcome against the id rather than retrying it nightly forever.
• Reusing a cursor across a different list. A cursor is scoped to the enumeration it came from. Feeding one list's cursor into another list's request produces either an error or a confusing empty page, which is a fiddly bug to find because nothing about it looks wrong at the call site.

The general defence is one line of validation at the edge: strip everything but digits from whatever a human handed you, reject an empty result loudly, and keep the value a string from that point on. It removes four of the five.

Finding lists worth crawling in the first place

A list id is easy to read out of a URL. The harder question, and the one that decides whether any of this is useful, is which lists exist that are worth reading at all. There is no global list search on X, so this is a discovery problem rather than a lookup, and the routes that work are indirect.

• Start from an account you already trust. Every profile has a Lists tab showing the public lists that account owns and subscribes to. An analyst or journalist covering your space has usually already done the curation you were about to pay someone for.
• Use listed_count as a shortlist signal. Every profile object carries the number of public lists that account appears on. An account with a high listed count relative to its follower count is one other people consider a reference in a niche, and its own lists are usually worth opening.
• Search for the lists people announce. Curators post about their lists. A search for url:x.com/i/lists alongside a topic term surfaces posts that link directly to a list, which is the closest thing to a list search that exists.
• Read the followers of a list, not just its members. The subscribers to a niche list are a self-selected audience for that niche, and that is frequently the more valuable half. It is the same cursor loop against a different endpoint.
• Walk outward from communities. Community members and moderators are a parallel curation layer with its own endpoints on the same key, and the overlap between an active community and a well-kept list is usually where the real practitioners sit.

The quality test once you have a candidate is quick and worth doing before you build anything on it: how many members, when did the owner last post, and how many of the members have posted this month. A hand-curated list of 40 active accounts beats an abandoned list of 900, and the first crawl tells you which one you have for less than a cent.

What list work costs at real sizes

A flat per-call rate makes this arithmetic rather than a quote. The numbers below are a full membership enumeration at $0.04 per 1,000 members, then the same list re-read daily for a month, then what it costs to also pull each member's recent posts.

The last column is where list projects actually spend, and it is the one to design around. Enumerating membership is close to free at any realistic list size; fanning out to a timeline call per member every day is 30 calls per member per month and dominates everything else. Two changes cut it hard: re-enumerate membership weekly rather than daily, because curated lists move slowly, and poll member timelines on a cadence that matches how often those accounts actually post rather than a uniform daily sweep across every member.

Turning a list into a working monitor

Most of the value in list data is not the one-off export. It is that a list is a stable, human-curated set of accounts you can watch over time, which makes it a far better filter than a keyword for anything where who said it matters as much as what was said.

The pattern is three jobs on different cadences. A weekly membership crawl that stores the full member set and diffs it against the previous run, so additions and removals are recorded as events rather than inferred later. A polling job over the members that matter, either their timelines directly or a list/tweets read when you want the whole set in one call. And a delivery step that only fires on something new, because a monitor that re-reports what it said yesterday gets muted within a week.

Two design notes that matter more than they look. Deduplicate on tweet id and not on text, because reposts and near-identical announcements will otherwise fill the feed, and hold a watermark of the newest id you have already delivered per member so a restart does not replay the backlog. And keep the membership diff separate from the content feed: the fact that a competitor added six accounts to a watchlist on Tuesday is often the more interesting signal, and it is invisible if you only ever look at posts.

If the consumer is a model rather than a person, the same endpoints are exposed as MCP tools on the same key and the same per-call rate, so an agent can enumerate a list, read what its members posted and decide what is worth surfacing without anyone writing tool definitions first.

Twitter List API FAQ