X API bookmarks: the two caps that are not in the docs

#Quick answer

The X API exposes five bookmarks endpoints, and two of them cannot give you a complete answer. The flat list, GET /2/users/:id/bookmarks, stops producing pagination tokens at around 199 Posts. The folder endpoint returns exactly 20 Post IDs no matter what max_results you send. X staff have acknowledged both, and the documented workaround for the first is the endpoint that has the second.

Last updated: November 2026

So if you are building a bookmark exporter, a read-it-later sync or a Grok-style digest, the interesting question is not how to call these endpoints. It is which subset of someone's bookmarks you are structurally able to see.

#Five endpoints, and what each one actually hands back

Bookmarks on X (formerly Twitter) are private, so every endpoint in this group is user-context only. The OpenAPI schemas accept an OAuth 2.0 user token or OAuth 1.0a, which both quickstarts omit in favour of PKCE only.

Read that third row again. The folder-contents endpoint returns an array of objects whose only required property is id. No text, no author, no created_at, and no tweet.fields or expansions parameters to ask for them. The flat list accepts six field parameters and returns an includes block; the folder endpoint accepts neither.

That asymmetry is the whole design, and it shows up in every section below.

#The 199-result window on the flat list

On 26 August 2026 a developer ran a controlled traversal of their own bookmarks and posted the numbers. Page one with max_results=100 returned 100 Posts and a meta.next_token. Page two, using that token, returned 99 Posts and no token. Total: 199. Repeating the traversal produced the same 100-then-99 termination, with no 429s and no error entries for deleted or protected Posts that could account for the missing 200th item.

The same developer then checked their folders and found 66 older bookmark IDs that the flat traversal never returned. The data is on X's side. The endpoint just stops describing it.

X staff replied the same day: the cutoff "is not how the docs describe bookmark lookup", they would check whether the top-level endpoint is windowed, and in the meantime "folder-scoped bookmark lookups are the workaround for older items." That is an honest answer and it is also the problem, because of what the next section does to that workaround.

Plan for it. If your product promises "export all your bookmarks", test against an account with more than 200 of them before you write that sentence on a pricing page.

#The hard 20 on folders

The folder endpoints advertise max_results between 1 and 100 and a pagination_token. Both are fiction.

The first report landed on 1 March 2026: an unparameterised call returns exactly 20 Posts and an empty meta object, and asking for more returns a 400 with the message The query parameter [max_results] is not one of [id,folder_id]. The same behaviour was reported again on 18 March for the folder list endpoint, again on 4 June for folder contents, and again on 14 October through Grok's connected X tools, where requests for 5, 20 and 40 all returned the same 20 Posts.

On that last thread X staff confirmed it directly. The folder endpoint "has historically returned a fixed page of about 20 Post IDs and does not honor max_results the way GET /2/users/:id/bookmarks does", folder responses "typically omit pagination metadata", and the gap would stay "on the API side of the backlog."

There is an independent reproduction in X's own tooling repo. Issue #98 on xdevplatform/xurl, opened 23 September 2026 against api-version 2.168, ran the folder endpoint at max_results of 1, 5 and 100 from both curl and Python and got the same 20 IDs in the same order every time, with data as the only top-level key. It is still open with no maintainer response.

Eight months, four forum threads, one issue on an official repo, and the schema at API version 2.174 still says 1 to 100.

#The two workarounds point at each other

Put the two caps side by side and the shape of the thing becomes clear.

• The flat list has expansions, real pagination and the cheap rate, and goes blind past roughly 199 Posts.
• The folder endpoint reaches older Posts, and hands back 20 bare IDs with no way to ask for the 21st.
• The flat list does not return folder membership, so you cannot reconstruct a folder from it even within the window.

That last point came from the developer who filed the June report, and it closes the loop: there is no combination of these five endpoints that reliably enumerates a large bookmark collection. You can get the recent 199 in full fidelity, or 20 IDs per folder, and nothing stitches the two together.

For a digest product this is survivable, because recent bookmarks are the ones people want summarised. For a migration or archive product it is a hard ceiling, and the honest move is to tell users to request their X archive instead of promising a complete API export.

#Folders cost five times what the flat list costs

The pricing page puts GET /2/users/{id}/bookmarks on the Owned Reads table at $0.001 per resource. Neither folder endpoint is on it.

The Owned Read rate also carries a condition that is easy to skim past: it applies when the {id} matches the authenticated user and that user owns the developer app. Bookmarks are private, so you are always reading as the owning user. But in a multi-user product your users do not own your app, so every bookmark you read for a customer bills at $0.005, not $0.001. The discount is for tools you build for yourself.

Then stack the hydration pass. The folder endpoint gives you IDs, so displaying anything means a second call to GET /2/tweets, which is a lookup-by-ID and not an Owned Read. Work a folder of 20 Posts:

Same 20 Posts. Reading them through the folder costs what reading them for a stranger costs, and takes an extra round trip. The 24-hour UTC deduplication window softens repeat reads, so a Post you already paid for today is free on the second call, but the first pass is the first pass. Our X API pricing breakdown has the full rate card, and X API rate limits covers how the per-app and per-user ceilings interact.

One oddity worth noting for anyone reverse-engineering the auth model: the flat lookup has no per-app rate limit column at all, while both folder endpoints have one at 50 per 15 minutes. A per-app ceiling on a strictly user-private resource is a strange thing to publish, and it is the kind of detail that suggests the folder endpoints came from a different code path.

#The batch write nobody documents

Here is the one piece of good news, and you will not find it in either quickstart.

POST /2/users/:id/bookmarks accepts either tweet_id for a single Post or a tweet_ids array of at most 25, mutually exclusive, plus an optional folder_id that applies to every ID in the request. The OpenAPI description spells out the billing consequence: "Billing and rate limits still apply per HTTP request."

One request, 25 bookmarks, one $0.005 charge. That is $0.0002 per bookmark, and it consumes one of your 50 writes per 15 minutes instead of 25 of them. Partial failures come back in a per-ID errors array with the note that "remaining IDs are still bookmarked", so a bad ID in the batch does not cost you the rest.

Both the "Manage Bookmarks" quickstart and the endpoint example in the introduction show only the single tweet_id form. The batch form exists solely in the OpenAPI description.

DELETE got none of this. It takes one tweet_id in the path, has no batch form, and is also $0.005 per request. So the arithmetic runs in one direction only:

• Add 25 bookmarks: 1 request, $0.005.
• Remove 25 bookmarks: 25 requests, $0.125, and half your 15-minute write budget.

A sync tool that mirrors a folder in both directions will be bounded entirely by its deletes. Batch the adds, queue the removals, and do not let a user hit "clear all" synchronously.

#What you cannot do at all

Three capability gaps, each confirmed rather than inferred.

No folder writes. There is no create, rename or delete endpoint for a folder. A developer asked for exactly those three on 29 April 2026 and X staff answered "nothing to announce at the moment regarding new bookmark endpoints." The folder_id parameter on POST means the API can file a Post into a folder it has no way to create, which is a genuinely odd place to stop.

No time filtering. There is no start_time, end_time or since_id on the bookmarks lookup, and the only timestamp available is the Post's created_at, not the time the bookmark was added. A request to add these in March 2026 got a "we'll take this feedback internally." So "my bookmarks from the last week" means paginating everything and filtering client-side, which the 199 window makes impossible past the recent slice.

No webhook. The X Activity API bills events for Posts, follows, mutes, blocks, profile updates, DMs, chats, news and Spaces. There is no bookmark event on that table. Bookmarks are a polling surface, and the 24-hour deduplication window is what makes polling affordable rather than the request ceiling.

Worth knowing about the docs themselves: the bookmarks "Integration guide" is a copy of the blocks integration guide, with every in-page anchor pointing at x-api/users/blocks/integrate.md, and it ends mid-sentence. The /x-api/bookmarks/* reference paths 307-redirect to /x-api/users/*, and the delete endpoint's externalDocs link still points at the retired developer.twitter.com domain. Read the OpenAPI blocks rather than the prose when the two disagree, and when the OpenAPI disagrees with the forum, trust the forum.

#When the API is the wrong route for this

The bookmarks endpoints are a decent fit for one job: a personal tool, on your own app, reading your own recent bookmarks at $0.001 a Post with batch writes at a fifth of a cent. That is a genuinely cheap digest or triage build, and the Owned Read rate exists precisely for it.

They are a poor fit for a product sold to other people. Your customers do not own your app, so you pay 5x. Folders cap at 20. The flat list goes blind past 199. And none of it can create the folder structure your users already have in the app, which is the organising principle they will expect you to respect. Check how to bookmark a post on X for what the app can do that the API cannot, and X API OAuth for getting the bookmark.read and bookmark.write scopes onto a token in the first place.

If what you actually want is for bookmarks to drive activity rather than sit in an archive, note that reading them is the easy half. X-Autopilot drives your own browser on your own machine, so a saved Post is something you can act on the way a person does, without an API tier deciding what you are allowed to reply to. The trade-offs are different and we will state them plainly: 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.

And if you are deciding between bookmarks and a List as the primitive for "watch this set of things", X API Lists is the better-behaved endpoint group of the two. Its caps are undocumented as well, but at least its pagination works.