Get X/Twitter Notifications API (mentions)

Read an X/Twitter account's own notifications timeline - replies, mentions, likes, retweets, follows - via API. $0.002 per call. GetXAPI notifications endpoint.

POST/twitter/notifications

This endpoint costs $0.002 per API call.

Returns the auth_token account's own notifications timeline across the All, Mentions, and Verified tabs. Notifications are private to the account, so this runs entirely as that account. Page through next_cursor to retrieve older notifications.

Request Body

Field	Type	Required	Description
`auth_token`	string	Yes	The account's auth token cookie
`ct0`	string	No	Optional CSRF token cookie. When provided with `twid`, skips server-side credential resolution
`twid`	string	No	Optional user ID cookie, for example `u=1234567890`. Must be provided with `ct0`
`tab`	string	No	Which tab to read: `all` (default), `mentions`, `verified`
`cursor`	string	No	Pagination cursor (`next_cursor`) from a previous response
`count`	number	No	Page size, 1-40 (default 20)
`proxy`	string	No	Proxy URL (`http://`, `https://`, `socks5://`, or `socks4://`)

Notes

If you already have current ct0 and twid, send both to skip the extra server-side credential bootstrap from auth_token. If either is omitted, the server resolves them from auth_token.
Keep calling with next_cursor until has_more is false to walk the full timeline.
Each item has a type (reply, mention, quote, like, retweet, follow, or X's raw event name for anything else), the from_users who triggered it, and the target_tweet involved (the reply/mention itself, or the tweet that was liked/retweeted). target_tweet is null for tweetless notifications such as follows.
from_users and target_tweet use the same user and tweet shapes as the rest of the API, so no extra lookup is needed for profile pictures or tweet text.

Response (200)

{
  "status": "success",
  "msg": "success",
  "data": {
    "notifications": [
      {
        "id": "HA4f2tBaMAAAAAABSQ3bERhMX3OVru__O_I",
        "type": "reply",
        "text": "@you That's really cool.",
        "timestamp": "2026-08-07T10:07:00.000Z",
        "from_users": [
          {
            "type": "user",
            "userName": "someuser",
            "name": "Some User",
            "id": "195999802",
            "isBlueVerified": false,
            "profilePicture": "https://pbs.twimg.com/profile_images/.../normal.jpg"
          }
        ],
        "target_tweet": {
          "type": "tweet",
          "id": "2085669028551651826",
          "url": "https://x.com/someuser/status/2085669028551651826",
          "text": "@you That's really cool.",
          "createdAt": "Fri Aug 07 10:07:00 +0000 2026",
          "author": { "userName": "someuser", "name": "Some User" }
        }
      }
    ],
    "next_cursor": null,
    "has_more": false
  }
}

Response Fields

Field	Type	Description
`notifications`	array	The notifications in this page, newest first
`notifications[].id`	string	Notification ID
`notifications[].type`	string	`reply`, `mention`, `quote`, `like`, `retweet`, `follow`, or X's raw event name
`notifications[].text`	string \| null	The notification text (the reply/mention text, or the aggregated message)
`notifications[].timestamp`	string \| null	ISO 8601 timestamp
`notifications[].from_users`	array	The user(s) who triggered the notification
`notifications[].target_tweet`	object \| null	The tweet involved, or `null` for tweetless notifications (e.g. follows)
`next_cursor`	string \| null	Cursor for the next page, or `null` when there are no more
`has_more`	boolean	Whether another page is available

Error Responses

400 - Invalid tab

{
  "error": "Invalid tab \"foo\". Allowed: all, mentions, verified."
}

400 - Missing auth_token

{
  "error": "Missing required field: auth_token"
}

Examples

# All notifications
curl -X POST "https://api.getxapi.com/twitter/notifications" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "auth_token": "your_auth_token" }'

# Mentions, next page
curl -X POST "https://api.getxapi.com/twitter/notifications" \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "auth_token": "your_auth_token", "tab": "mentions", "cursor": "PASTE_NEXT_CURSOR" }'

const response = await fetch("https://api.getxapi.com/twitter/notifications", {
  method: "POST",
  headers: {
    Authorization: "Bearer API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ auth_token: "your_auth_token", tab: "all" }),
});
const { data } = await response.json();
for (const n of data.notifications) {
  console.log(n.type, n.from_users[0]?.userName, n.text);
}

import requests

response = requests.post(
    "https://api.getxapi.com/twitter/notifications",
    headers={"Authorization": "Bearer API_KEY"},
    json={"auth_token": "your_auth_token", "tab": "all"},
)
data = response.json()["data"]
for n in data["notifications"]:
    print(n["type"], n["from_users"][0]["userName"] if n["from_users"] else None, n["text"])

Notifications

On this page