Bookmarks API

GET user/bookmarks returns the bookmarked tweets saved by the account behind your registered twitterapis.com session, ordered newest first. Each result is a full tweet object including author details and engagement counts. The endpoint is cursor-paginated via the count and cursor parameters, requires an active registered session, and costs $0.0008 per call.

curl -X GET "https://example.com/user/bookmarks?count=20&fields=id%2Ctext%2Ccreated_at%2Cauthor.username&compact=1&paid_promotion=only"

{  "count": 1,  "next_cursor": "DAACCgAC...",  "tweets": [    {      "id": "1759123456789012345",      "text": "Bookmark this thread on cursor pagination.",      "created_at": "Tue Feb 20 14:02:11 +0000 2026",      "author": {        "id": "745273",        "username": "naval",        "name": "Naval"      },      "favorite_count": 4821,      "retweet_count": 612,      "view_count": 219340    }  ]}

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

When to use

Use this endpoint to retrieve the tweets the registered account has bookmarked, most recent first. Reach for it instead of user/likes or the home timeline when you specifically need the account's saved-for-later list rather than its public engagement history.

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.
• 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

• User Info by Username: Fetch a full profile by @handle.
• User Info by ID: Fetch a full profile by numeric user ID.

FAQ

Does this endpoint work with any Twitter/X account, or only the one I've registered a session for?

Only the registered account's own bookmarks. The description specifies it fetches bookmarks for the account behind your registered session, so you cannot pass a target username to read another account's bookmarks; a valid registered session is required for the call to succeed.

How do I page through a large bookmarks list?

Use the count and cursor parameters together. count sets items per page (default 20, capped at 100), and cursor takes the next_cursor value from the previous response. Keep paging while has_more is true in the response; once it's false, next_cursor has no further pages to return.