Bookmarks

GET/tw-v2/interaction/bookmarks

Description

Retrieve the posts bookmarked by the X account behind authToken. Returns a paginated timeline of posts.

Usage notes

Returns bookmarks of the authToken account only; there is no way to read another user's bookmarks. Bookmarked posts that X no longer returns are left out, so a page can hold fewer than 20 posts. Keep passing nextCursor until it is null. Bookmark folders and bookmark search are not supported.

A request costs one API unit. 400, 401, 403, 429 and 5xx errors are free; a 404 is billed.

Query Parameters

Parameter	Type	Required	Description
authTokenstringrequired	string	required	Authentication token (auth_token cookie value) of the X account whose data you read. Only that account's data is returned.
cursorstringoptional	string	optional	Pagination cursor from the previous response's nextCursor. Omit for the first page.
proxystringoptional	string	optional	Optional proxy in format 'host:port@user:pass'

Code Examples

const params = new URLSearchParams({
  authToken: 'YOUR_AUTH_TOKEN'
});

const response = await fetch(`https://api.tweetapi.com/tw-v2/interaction/bookmarks?${params}`, {
  method: 'GET',
  headers: {
    'X-API-Key': 'YOUR_API_KEY'
  }
});

const data = await response.json();
console.log(data);

Response

Success Response (200 OK)

Synthetic example:

200

{
  "data": [
    {
      "id": "2000000000000000001",
      "conversationId": "2000000000000000001",
      "text": "Sample post 2000000000000000001",
      "displayTextRange": [
        0,
        20
      ],
      "author": {
        "id": "1000000000000000902",
        "username": "sample_user_00002",
        "name": "Sample User",
        "bio": "Sample bio",
        "location": "Sample City",
        "website": null,
        "pinnedTweetIds": [],
        "avatar": "https://example.com/images/sample-avatar.jpg",
        "banner": "https://example.com/images/sample-banner.jpg",
        "profileImageShape": null,
        "verified": false,
        "isBlueVerified": false,
        "verifiedType": null,
        "verifiedSince": null,
        "isIdentityVerified": false,
        "isProtected": false,
        "possiblySensitive": false,
        "profileInterstitialType": null,
        "withheldInCountries": [],
        "professional": null,
        "businessAccount": null,
        "creatorSubscriptionsCount": 0,
        "hasHiddenSubscriptions": false,
        "highlightsInfo": null,
        "hasGraduatedAccess": false,
        "isProfileTranslatable": false,
        "hasCustomTimelines": false,
        "isTranslator": false,
        "affiliatesHighlightedLabel": null,
        "defaultProfile": false,
        "defaultProfileImage": false,
        "followerCount": 1200,
        "followingCount": 34,
        "tweetCount": 560,
        "listedCount": 0,
        "mediaCount": 78,
        "favoritesCount": 90,
        "createdAt": "2023-01-02T00:00:00.000Z"
      },
      "source": null,
      "type": "tweet",
      "replyTo": null,
      "quotedTweet": null,
      "reactionContext": null,
      "retweetedTweet": null,
      "likeCount": 1,
      "retweetCount": 0,
      "replyCount": 0,
      "quoteCount": 0,
      "bookmarkCount": 0,
      "viewCount": 0,
      "media": [],
      "poll": null,
      "card": null,
      "article": null,
      "hashtags": [],
      "mentions": [],
      "urls": [],
      "symbols": [],
      "possiblySensitive": false,
      "limitedActions": null,
      "hasAIGeneratedMedia": false,
      "isPaidPromotion": false,
      "isEdited": false,
      "editControl": null,
      "isTranslatable": false,
      "lang": "en",
      "translatedText": null,
      "hasBirdwatchNotes": false,
      "birdwatchPivot": null,
      "conversationControl": null,
      "isPromoted": false,
      "promotedMetadata": null,
      "createdAt": "2026-10-27T12:00:00.000Z",
      "place": null,
      "communityId": null,
      "communityResults": null
    }
  ],
  "pagination": {
    "nextCursor": "NEXT_CURSOR",
    "prevCursor": "PREVIOUS_CURSOR"
  }
}

An empty page is also successful:

200

{
  "data": [],
  "pagination": {
    "nextCursor": null,
    "prevCursor": null
  }
}

Errors

Errors return { statusCode, message } with a non-2xx HTTP status.

A missing authToken or a userId parameter returns 400. An auth token X rejects returns 401.

400

{
  "statusCode": 400,
  "message": "Request validation failed"
}

TweetAPI is a third-party API and is not affiliated with X Corp.