Bookmark Folders API | List Your X Bookmark Collections

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.

curl -X GET "https://example.com/user/bookmark_folders"

{  "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": "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

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.