Notifications

GET/tw-v2/interaction/notifications

Description

Retrieve the authenticated user's notifications timeline on Twitter/X. Returns notifications including likes, retweets, mentions, and follows.

Parameters

Parameter	Type	Required	Description
authToken	string	required	Twitter authentication token (auth_token cookie value)
timelineType	string	optional	Type of notifications to retrieve: 'All', 'Verified', or 'Mentions' (default: 'All')
count	number	optional	Number of results to return per page (min: 1, max: 100, default: 20)
cursor	string	optional	Pagination cursor for fetching next page of results. Obtained from previous response.
proxy	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/notifications?${params}`, {
  method: 'GET',
  headers: {
    'X-API-Key': 'YOUR_API_KEY'
  }
});

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

Response

Success Response (200 OK)

200

{
  "data": [
    {
      "id": "F1jG7mhWwAAAAAAB15VmQrFiaySXms5dAAA",
      "type": "device_follow_tweet_notification_entry",
      "timestamp": "2025-10-05T06:39:17.402Z",
      "message": "New post notifications for tradinglord",
      "users": [
        {
          "id": "841016244270706688",
          "username": "tradinglord",
          "name": "tradinglord",
          "followerCount": 117834,
          "isBlueVerified": true
        }
      ],
      "url": "/2/notifications/device_follow.json",
      "icon": "bell_icon"
    },
    {
      "id": "F1jG7mhWwAAAAAAB15VmQrFiaySWMQX0Luk",
      "type": "generic_magic_rec_first_degree_tweet_recent",
      "timestamp": "2025-10-04T22:40:41.212Z",
      "message": "Recent post from gainzy",
      "users": [
        {
          "id": "4107711",
          "username": "gainzy222",
          "name": "gainzy",
          "followerCount": 317001,
          "isBlueVerified": true
        }
      ],
      "tweets": [
        {
          "id": "1974456667409699279",
          "text": "sigh",
          "author": {
            "id": "4107711",
            "username": "gainzy222"
          },
          "type": "quote"
        }
      ],
      "url": "https://twitter.com/gainzy222/status/1974456667409699279",
      "icon": "recommendation_icon"
    },
    {
      "id": "F1jG7mhWwAAAAAAB15VmQrFiaySWc3a7cAA",
      "type": "generic_magic_rec_first_degree_tweet_recent",
      "timestamp": "2025-10-04T22:40:41.211Z",
      "message": "Recent post from elonmusk",
      "users": [
        {
          "id": "44196397",
          "username": "elonmusk",
          "name": "Elon Musk",
          "followerCount": 226995885,
          "isBlueVerified": true
        }
      ],
      "tweets": [
        {
          "id": "1974456429726900264",
          "text": "Optimus can now walk on highly variable ground",
          "author": {
            "id": "44196397",
            "username": "elonmusk"
          },
          "type": "tweet"
        }
      ],
      "url": "https://twitter.com/elonmusk/status/1974456429726900264",
      "icon": "recommendation_icon"
    },
    {
      "id": "F1jG7mhWwAAAAAAB15VmQrFiaySWc3a8AAA",
      "type": "favorite_notification_entry",
      "timestamp": "2025-10-04T19:22:03.210Z",
      "message": "user123 liked your post",
      "users": [
        {
          "id": "123456789",
          "username": "user123",
          "name": "User Name",
          "followerCount": 5432,
          "isBlueVerified": false
        }
      ],
      "tweets": [
        {
          "id": "1974398765432109876",
          "text": "Your tweet text here",
          "author": {
            "id": "1682313188077912064",
            "username": "your_username"
          },
          "type": "tweet"
        }
      ],
      "url": "https://twitter.com/your_username/status/1974398765432109876",
      "icon": "favorite_icon"
    },
    {
      "id": "F1jG7mhWwAAAAAAB15VmQrFiaySWjvKlAAA",
      "type": "retweet_notification_entry",
      "timestamp": "2025-10-04T18:15:42.209Z",
      "message": "anotheruser retweeted your post",
      "users": [
        {
          "id": "987654321",
          "username": "anotheruser",
          "name": "Another User",
          "followerCount": 12345,
          "isBlueVerified": true
        }
      ],
      "tweets": [
        {
          "id": "1974365432198765432",
          "text": "Another tweet you posted",
          "author": {
            "id": "1682313188077912064",
            "username": "your_username"
          },
          "type": "tweet"
        }
      ],
      "url": "https://twitter.com/your_username/status/1974365432198765432",
      "icon": "retweet_icon"
    }
  ],
  "pagination": {
    "nextCursor": "DAACDAABCgABF1jG7mhWwAAIAAIAAAABCAAD15VmQggABLFiayQACwACAAAAC0Faa2p5cE4zWGpZAAA",
    "prevCursor": null
  }
}

Notifications

Description

Parameters

Code Examples

Response

Success Response (200 OK)

API Playground

Sensitive Credentials Required