X API Lists: the add limit that is not in the docs

#Quick answer

The X API Lists group is 17 endpoints that let you build, read and curate Lists in code. The reads are cheap and generously rate limited. The writes are the problem: the published ceiling for adding a member is 300 requests per 15 minutes, but X staff have confirmed that a separate platform spam limit lands first, and the developer who asked about it was stopped near 100 adds a day.

Last updated: October 2026

That gap decides the architecture. A 5,000-member List is about four hours of work at the documented rate and closer to fifty days at the observed one.

#Seventeen endpoints, fifteen published limits

X groups the Lists endpoints into six sets. The rate-limit reference heads the block "Lists (14 endpoints)" and then prints 15 rows, which is a decent clue about how recently the page was audited.

Two documented endpoints are missing from that table entirely. GET /2/lists/:id/followers has a reference page and no rate limit. GET /2/users/:id/followed_lists has a reference page, a price in the Owned Reads table, and no rate limit. List follows also has no guide section at all, so the only way to learn the endpoint group exists is to read the index.

Assume an unpublished limit is low rather than absent, and read the x-rate-limit-limit header on your first call to find out what it actually is.

#The only read on the X API you can budget in advance

Here is the thing that makes Lists genuinely useful, and it has nothing to do with the endpoints themselves.

X deduplicates billable resources inside a 24-hour UTC window. Request the same Post twice in a day, pay once. Combine that with a List, whose membership is capped at 5,000 accounts that you chose, and your worst-case daily cost stops depending on how often you poll.

Work it through. A 100-account List whose members average 10 Posts a day produces about 1,000 unique Posts in a UTC day. At $0.005 that is $5, whether you poll the timeline once an hour or every two minutes, because the repeat reads are free inside the window. Scale the List to 500 accounts at the same posting rate and you are at $25 a day. The number moves with membership and their posting habits, both of which you can measure before you commit.

Now compare that to the alternative. On X API stream the bill is written by other people's posting rate against a keyword you cannot bound, with no page size to cap it. On X API search you control max_results but a broad query still returns whatever matched. A List is the only read surface where the author set is finite and yours.

Three practical notes on the timeline endpoint:

• max_results goes to 100, so one page of a List timeline is roughly $0.50 at the $0.005 rate. List: Read and Posts: Read are both $0.005, so the bucket argument does not change the arithmetic.
• 900 requests per 15 minutes is enormous headroom. If you are near it you are polling 100 Lists a minute, which is a different design problem.
• The reads land against the same 3 million Post read monthly cap as everything else on the account. At $0.005 that cap is $15,000, and a dozen busy Lists will not get near it.

Our X API pricing breakdown has the rest of the rate card, and X API rate limits covers how the per-app and per-user ceilings interact.

#Owning a List does not make it an Owned Read

X added Owned Reads to the rate card for exactly the use case Lists suit: an app reading its own owner's data at $0.001 per resource instead of $0.005 or $0.010. Four Lists endpoints qualify.

Notice the pattern. Every discounted endpoint is user-scoped: the Lists you own, follow, belong to or pinned. None of them returns the contents of a List.

GET /2/lists/:id/tweets, GET /2/lists/:id/members, GET /2/lists/:id/followers and GET /2/lists/:id are not in the Owned Reads table. Your own List, created by your own app, read with your own token, is full price. The discount covers finding your Lists, not reading them.

There is a second irony in the rate limits. The cheapest Lists call, owned_lists at $0.001, is tied with pinned_lists for the most throttled in the group at 15 requests per 15 minutes, or one a minute. The full-price timeline read gets 900. Pricing and throttling point in opposite directions, so cache your List inventory and spend your request budget on content.

#The write limit that is not in the docs

The Lists documentation says POST /2/lists/:id/members allows 300 requests per 15 minutes. Taken at face value, that is 1,200 adds an hour and a full 5,000-member List in about four hours and ten minutes.

In July 2026 a developer posted that the API cut them off around 100 adds a day with a 429, against that documented 300 per 15 minutes. X staff answered the same day, and the answer is the important part: the limit for adding members is indeed 300 requests per 15 minutes on self-serve pay-per-use, "however you may hit downstream platform spam limits before exceeding your API limit." The advice was to throttle off the endpoint on 429 and avoid spammy behaviour.

So there are two ceilings. One is published and belongs to the API. The other is anti-abuse, applies to the account rather than the app, and is not written down anywhere, which is normal for anti-abuse systems and still inconvenient when you are sizing a job.

An earlier thread shows the shape of the failure. In June 2026 a developer reported five consecutive days of bare 429s on the same endpoint, every single add attempt, with no documented window and no reset in sight. Nothing in the response body distinguishes the API limit from the platform limit. Both are a 429; only one clears on a schedule.

What to do with that:

1. Treat 100 adds a day as your design number, not 1,200 an hour. A 5,000-member List becomes a 50-day backfill, so build it as a queue with durable state rather than a script you babysit.
2. Back off hard on the first 429, with a long cooldown rather than a retry. A tight retry loop against an anti-abuse limit is the behaviour the limit exists to stop.
3. Spread adds across the day instead of bursting. The burst is what looks like bulk action, and bulk aggressive actions are called out in X's automation rules.
4. Budget the writes at $0.005 each. List: Manage is a flat per-request charge, so filling 5,000 seats costs about $25 in credits regardless of how long it takes.

The honest version: adding thousands of accounts to a List quickly is not something the platform wants to let you do, and that is a deliberate product decision rather than a bug in your client.

#You can search a List. You cannot stream one.

The list: operator exists, it is standalone, and it matches Posts from members of a specific List. list:123 on recent search gives you the same corpus as the List timeline with query syntax layered on top, which is the move when you want "Posts from my List that also mention our product."

It is not in the Filtered Stream operator set. The stream has listed_count:, which matches Posts from users who appear in a given number of Lists, and that is a different thing entirely. There is no way to open a streaming connection scoped to a List.

That is fine. It just means the design is a poller, and the dedup maths above is why polling a List is not the expensive choice it sounds like.

#Shape limits worth knowing before you design

Per X's own Lists help page, an account can hold 1,000 Lists and each List can hold 5,000 accounts. That ceiling multiplies out to five million memberships, which no self-serve rate limit will ever let you reach.

The API adds its own constraints, visible only in the request schema: a List name is 1 to 25 characters, a description caps at 100, and the name cannot start with a number. Twenty-five characters is tighter than most people expect and it is a 400, not a truncation.

Every write in the group is user-context. POST /2/lists, the PUT, the DELETE, the member writes, the follow and pin writes all show a per-user rate limit and no per-app column, and creating a List needs an OAuth 2.0 user token with users.read, tweet.read, list.read and list.write. Reads can run on an app-only Bearer token, with the obvious exception that private Lists need the owner's token.

#When a List is the wrong tool

Lists are a monitoring and curation primitive. They are excellent at "watch these 200 accounts" and bad at everything adjacent to growth.

If the aim is to find accounts worth replying to, a List is the index and not the work. Building the List is the slow part, as the add limits above make clear, and the reading is only useful if something acts on it. If the aim is audience signal, note that GET /2/lists/:id/followers returns user objects in the $0.010 Following/Followers bucket, which makes "who follows my List" the single most expensive question you can ask about a List you own.

And if the aim is consistent posting and replying from your own account, the API route adds a constraint that has nothing to do with Lists: since February 2026 self-serve tiers can only publish a reply when the original author mentioned or quoted you, which X API reply covers in full. A curated List of accounts you cannot reply to programmatically is an expensive reading list.

X-Autopilot takes the other route, driving your own browser on your own machine, so a curated feed is just a List you read the way a person does and replies are not gated by API tier. The trade-offs are different and we are direct about them: browser automation sits in a grey area under X's automation rules, while the API route is the sanctioned one. Neither removes risk from your account.

For the hand-driven version of all of this, our guide to using Lists on X covers building, sorting and pinning them in the app, which is still the fastest way to get the first version of a List right before you spend credits automating it.