Bookmark Folders API | List Your X Bookmark Collections
Fetch the caller's own bookmark folders. Each item carries the folder's id, name, and a cover image X auto-picks from its contents. Requires a registered session. Billed at $0.0008 per call. Cost: $0.0008 per call.
Bookmark Folders returns the caller's own bookmark folders (X's internal name: collections), the named groups a user can organize saved tweets into, separate from the flat All Bookmarks list. Each folder has an id, a name, and a cover image. Requires a registered session.
Authorization
bearerAuth Pass your API key as a bearer token on every request: Authorization: Bearer <API_KEY>.
In: header
Query Parameters
Comma-separated list of dotted field paths to keep in the response (one parameter, never repeated), applied to every object in the returned lists and to nested objects (for example fields=id,text,author.username; the list's own name may prefix a path, fields=tweets.id). A path prefix that lands on an array applies to each element (media.media_url_https). Pagination and envelope keys (next_cursor, cursor, has_more, count, partial, error, message, reason) are always kept. Unknown paths are ignored; up to 50 paths of up to 6 segments. Projection never changes status codes or billing, and applies to data reads only: account, feedback, session status, monitor (other than deliveries), webhook and stream-compat reads return their bodies unchanged.
Set to 1 (or true) to apply the built-in compact preset: ids, url, text, created_at, lang, the engagement counts, the is_retweet/is_reply/is_quote flags, conversation ids, the author's id/username/name/followers_count/verification, and the quoted or retweeted tweet's id/url/author username. The preset trims what it recognises and leaves alone what it would empty, so it never turns a body into {}. Combine with fields to add paths on top of the preset. Typically cuts a tweet page by 70 to 90 percent for LLM tool callers.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/user/bookmark_folders?fields=id%2Ctext%2Ccreated_at%2Cauthor.username&compact=1"{ "count": 1, "folders": [ { "id": "2073826456430592429", "name": "Parasite SEO", "cover_media_url": "https://pbs.twimg.com/media/Ex_fuubVEAA9gcg.png" } ]}{ "error": "bad_request", "message": "Missing or malformed parameter. Fix the request before retrying."}{ "error": "unauthorized", "message": "The API key is missing, malformed, or revoked. Check the Authorization header."}{ "error": "insufficient_credits", "message": "Your balance is exhausted. Top up your credits to continue."}{ "error": "forbidden", "message": "X refused this resource for the acting account: on a read, the account is not a participant in the DM thread, the target is protected or has blocked it, or the session was attestation-blocked for calling from a datacenter or rotating IP; on a write, the account is not authorized for the action or has no logged-in session. The credentials are still valid, so do not re-register."}{ "error": "not_found", "message": "The resource does not exist, for example a deleted tweet or a private account."}{ "error": "rate_limited", "message": "Too many requests. Back off and retry with exponential backoff."}{ "error": "server_error", "message": "Something failed on our side. Retry with backoff; if it persists, contact support."}Pricing
| Unit | Price |
|---|---|
| Per call | $0.0008 |
| Per 1,000 calls | $0.80 |
When to use
Use it to enumerate your own folders and find a folder_id to pass to Bookmark Folder Timeline. To read the flat, unorganized bookmarks list instead, use Bookmarks or Bookmark Search.
Notes
- Needs a session for the account you are reading: either register one once (POST /customer/session), or pass per-call inline credentials as x-auth-token and x-ct0 request headers, which let a single API key act as many accounts. Returns 409 session_required if neither is supplied, 401 session_dead when the session has expired.
- Takes no request parameters; your folders resolve from your session alone.
- cover_media_url is a cover image X auto-picks from the folder's contents. It is null for an empty folder.
Related endpoints
- Bookmark Folder Timeline: Read the tweets inside one of your bookmark folders.
- Bookmarks: List your registered account's bookmarked tweets, most recent first.
- Bookmark Search: Full-text search within your registered account's bookmarks.
FAQ
Do I need a registered session?
Yes. Bookmark folders are the caller's own private data, same auth model as Bookmarks and Bookmark Search: a registered session (POST /customer/session) or per-call auth_token/ct0.
How do I read the tweets inside a folder?
Take a folder's id from this response and pass it as folder_id to Bookmark Folder Timeline.
What if a folder has no cover image?
cover_media_url is null. This is expected for an empty or very new folder; it does not mean the request failed.
Muted Accounts GET
Return the accounts muted by the account behind your registered session, as full user objects, cursor-paginated. Muting hides someone's posts from your timeline without blocking them, so this list is distinct from GET /user/blocking. This reads your OWN mute list; X exposes no way to read another account's, so there is no user_id parameter. Requires a registered session or per-call inline credentials. Cost: $0.0008 per call.
Bookmark Folder Timeline GET
Fetch the tweets inside one of the caller's own bookmark folders, identified by folder_id (from Bookmark Folders). Cursor-paginated. Requires a registered session. Billed at $0.0008 per call. Cost: $0.0008 per call.