Bookmark Folder Timeline API | Read Tweets in an X Bookmark Folder

Bookmark Folder Timeline returns the tweets saved inside one specific bookmark folder (X's internal name: collection) belonging to the caller's own account, cursor-paginated, newest first. Requires a registered session and the folder's id from Bookmark Folders.

curl -X GET "https://example.com/user/bookmark_folder_timeline?folder_id=2073826456430592429"

{  "folder_id": "2073826456430592429",  "count": 1,  "next_cursor": "-1783273732069",  "tweets": [    {      "id": "2073438646657564825",      "text": "https://t.co/dYukCmrM45",      "created_at": "Sat Jul 04 16:07:50 +0000 2026",      "author": {        "id": "1451118635108478976",        "username": "natiakourdadze",        "name": "Natia Kurdadze"      },      "favorite_count": 41,      "retweet_count": 5,      "view_count": 6332    }  ]}

{  "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 once you already have a folder_id from Bookmark Folders and want the tweets organized inside that one folder. To read your entire flat bookmarks list instead, use Bookmarks.

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.
• No count parameter exists for this op; only cursor pagination.
• Stop paginating when the tweets array comes back empty.

Pagination

This endpoint is cursor-paginated and returns roughly 20 records per call. Pass the next_cursor from each response back as the cursor parameter to read the next page. Stop when the records array comes back empty: follower-graph endpoints return a non-null cursor even on the final page, so the empty array is the only reliable stop signal. See Pagination for the full loop.

Related endpoints

• Bookmark Folders: List your registered account's 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

Where do I get a folder_id?

From user/bookmark_folders, which lists your own folders.

Can I read someone else's folder?

No. This only reaches folders belonging to the account behind your registered session.

Does this take a count parameter like Bookmarks does?

No. This endpoint is cursor-paginated only; there is no page-size parameter to set.