Bookmark Search API

GET user/bookmark_search performs a full-text keyword search across the bookmarks saved to the registered account's session. It returns matching tweets as full Tweet objects, paginated by cursor. Each page includes a count of items returned and a next_cursor plus has_more flag for retrieving additional results. Costs $0.0008 per call.

curl -X GET "https://example.com/user/bookmark_search?query=cursor+pagination&fields=id%2Ctext%2Ccreated_at%2Cauthor.username&compact=1&paid_promotion=only"

{  "count": 1,  "next_cursor": "DAACCgAC...",  "tweets": [    {      "id": "1759123456789012345",      "text": "The empty array is the universal stop signal for cursor pagination.",      "created_at": "Tue Feb 20 14:02:11 +0000 2026",      "author": {        "id": "745273",        "username": "naval",        "name": "Naval"      },      "favorite_count": 4821    }  ]}

{  "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 when a user needs to locate a specific bookmarked tweet by keyword instead of scrolling through the full bookmarks list. Reach for it over the plain bookmarks endpoint whenever the query is known and filtering by text match is the goal, rather than retrieving bookmarks in save order.

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.
• Searches only your own bookmarks, not the public tweet corpus.

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

How is this different from the plain bookmarks endpoint?

The plain bookmarks endpoint returns your saved tweets in list order with no filtering. This endpoint takes a required query parameter and matches it against the text of tweets you've bookmarked, so you get only bookmarks whose tweet text contains the keyword(s).

How do I page through results and how many can I get per request?

Pass the cursor value from a response's next_cursor field as the cursor parameter on your next request. count controls items per page, defaulting to 20 with a cap of 100. Check has_more to know whether another page exists before requesting it.