> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xquik.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Twitter notifications API, mentions & activity feed

> Retrieve a connected X account's notifications. Filter mentions or verified activity, store triage rows, and page older rows with next_cursor. 1 credit each.

<Panel>
  <Tabs defaultTabIndex={0} sync={false}>
    <Tab title="200" id="response-x-notifications-200">
      ```json theme={null}
      {
        "notifications": [
          {
            "id": "1234567890",
            "type": "like",
            "message": "elonmusk liked your tweet",
            "timestamp": "2025-01-15T12:00:00Z"
          }
        ],
        "has_next_page": true,
        "next_cursor": "DAACCgACGRElMJcAAA"
      }
      ```
    </Tab>

    <Tab title="401" id="response-x-notifications-401">
      ```json theme={null}
      {
        "error": "unauthenticated",
        "message": "Authentication required. Provide a valid API key or bearer token."
      }
      ```
    </Tab>

    <Tab title="402" id="response-x-notifications-402">
      ```json theme={null}
      {
        "error": "insufficient_credits",
        "message": "Insufficient credits. Top up or subscribe to continue."
      }
      ```
    </Tab>

    <Tab title="424" id="response-x-notifications-424">
      ```json theme={null}
      {
        "error": "x_api_unavailable",
        "message": "X data source temporarily unavailable. Try again later."
      }
      ```
    </Tab>

    <Tab title="429" id="response-x-notifications-429">
      ```json theme={null}
      {
        "error": "rate_limit_exceeded",
        "message": "Too many requests. Try again later.",
        "retryAfter": 60
      }
      ```
    </Tab>

    <Tab title="502" id="response-x-notifications-502">
      ```json theme={null}
      {
        "error": "x_api_unavailable",
        "message": "X data source temporarily unavailable. Try again later."
      }
      ```
    </Tab>

    <Tab title="503" id="response-x-notifications-503">
      ```json theme={null}
      {
        "error": "x_api_unavailable",
        "message": "Xquik is busy right now. Retry shortly."
      }
      ```
    </Tab>
  </Tabs>
</Panel>

<blockquote className="agent-llms-directive">
  For the complete documentation index, see <a href="/llms.txt">llms.txt</a>.
</blockquote>

<Note>
  Requested result counts are upper bounds for paid authenticated calls. When remaining credits cannot cover the full page or ID list, Xquik returns fewer results. If zero paid results are affordable, it returns `402 insufficient_credits`.
</Note>

<Callout icon="coins" color="#5c3327">
  **1 credit per result returned** · [All plans](https://xquik.com/#pricing) from \$0.00012/credit
</Callout>

The route reads notifications through your connected X account. Without one, it
returns `424 account_required`. Use [Connect X account](/api-reference/x-accounts/connect)
to add one. When your connected X accounts are busy, it returns `503`. Retry
after the `Retry-After` delay.

Get notifications reads the connected account inbox. Use `type=Mentions` for
mention triage, `type=Verified` for verified-account activity, or omit `type`
for all notification rows. Store `next_cursor` only when `has_next_page` is
true.

<CodeGroup>
  ```bash Mentions theme={null}
  curl -G https://xquik.com/api/v1/x/notifications \
    --data-urlencode "type=Mentions" \
    -H "x-api-key: xq_YOUR_KEY_HERE" | jq

  # Page 2
  curl -G https://xquik.com/api/v1/x/notifications \
    --data-urlencode "type=Mentions" \
    --data-urlencode "cursor=abc123" \
    -H "x-api-key: xq_YOUR_KEY_HERE" | jq
  ```

  ```javascript Node.js theme={null}
  function notificationsUrl({ cursor, type = "Mentions" }) {
    const params = new URLSearchParams({ type });
    if (cursor) params.set("cursor", cursor);
    return `https://xquik.com/api/v1/x/notifications?${params}`;
  }

  function toNotificationRows(page, { inboxType }) {
    return page.notifications.map((notification) => ({
      record_type: "notification",
      inbox_type: inboxType,
      notification_id: notification.id,
      notification_type: notification.type ?? null,
      message_preview: notification.message ?? null,
      created_at: notification.timestamp ?? null,
      source_endpoint: "GET /api/v1/x/notifications",
      page_next_cursor: page.has_next_page ? page.next_cursor : null,
    }));
  }

  async function saveNotificationRows(rows) {
    // Replace this with a private support inbox, CRM, queue, or agent memory write.
    return rows.length;
  }

  const inboxType = "Mentions";
  const response = await fetch(notificationsUrl({ type: inboxType }), {
    headers: { "x-api-key": "xq_YOUR_KEY_HERE" },
  });
  const data = await response.json();
  const rows = toNotificationRows(data, { inboxType });
  await saveNotificationRows(rows);

  // Paginate
  if (data.has_next_page) {
    const next = await fetch(notificationsUrl({ type: inboxType, cursor: data.next_cursor }), {
      headers: { "x-api-key": "xq_YOUR_KEY_HERE" },
    });
    const nextRows = toNotificationRows(await next.json(), { inboxType });
    await saveNotificationRows(nextRows);
  }
  ```

  ```python Python theme={null}
  import requests

  def to_notification_rows(page, inbox_type):
      return [
          {
              "record_type": "notification",
              "inbox_type": inbox_type,
              "notification_id": notification["id"],
              "notification_type": notification.get("type"),
              "message_preview": notification.get("message"),
              "created_at": notification.get("timestamp"),
              "source_endpoint": "GET /api/v1/x/notifications",
              "page_next_cursor": page["next_cursor"] if page["has_next_page"] else None,
          }
          for notification in page["notifications"]
      ]

  def save_notification_rows(rows):
      # Replace this with a private support inbox, CRM, queue, or agent memory write.
      return len(rows)

  inbox_type = "Mentions"
  response = requests.get(
      "https://xquik.com/api/v1/x/notifications",
      params={"type": inbox_type},
      headers={"x-api-key": "xq_YOUR_KEY_HERE"},
  )
  data = response.json()
  save_notification_rows(to_notification_rows(data, inbox_type))

  # Paginate
  while data["has_next_page"]:
      data = requests.get(
          "https://xquik.com/api/v1/x/notifications",
          params={"type": inbox_type, "cursor": data["next_cursor"]},
          headers={"x-api-key": "xq_YOUR_KEY_HERE"},
      ).json()
      save_notification_rows(to_notification_rows(data, inbox_type))
  ```
</CodeGroup>

The Node.js and Python snippets normalize each page for notification triage.
Keep full message text in private systems. Use `notification_id`,
`notification_type`, `created_at`, `inbox_type`, and `page_next_cursor` for
private support dashboards, CRM queues, and agent workflows.

## Notification triage handoff

Use `GET /api/v1/x/notifications` when a support inbox, CRM workflow, or agent
queue needs account-level activity for a connected X account. The endpoint
returns notification IDs, types, message previews, and timestamps. It omits
full tweet and direct-message payloads.

<CardGroup cols={2}>
  <Card title="Mention queue" icon="at-sign">
    Use `type=Mentions` for replies and mentions that need a support or brand
    review queue.
  </Card>

  <Card title="Verified activity" icon="badge-check">
    Use `type=Verified` when you route verified-account activity ahead of the
    general inbox.
  </Card>

  <Card title="All inbox" icon="inbox">
    Omit `type` or pass `All` when the workflow needs every notification row
    visible to the connected account.
  </Card>

  <Card title="Stable upserts" icon="key-round">
    Store `notifications[].id` as `notification_id` for deduplication and replay-safe
    imports.
  </Card>

  <Card title="Private text" icon="lock-keyhole">
    Keep `notifications[].message` in private support, CRM, or agent memory
    systems.
  </Card>

  <Card title="Next page" icon="arrow-right">
    Store `has_next_page` and `next_cursor`, then pass `next_cursor` back as `cursor`
    only when `has_next_page` is true.
  </Card>
</CardGroup>

## Poll Twitter notifications with the API

Call `GET /x/notifications` with a connected account's Xquik API key. Omit
`type` to read all notification categories. Use `type=Mentions` for a
mention queue or `type=Verified` for verified-account activity.

Each row can contain a notification ID, type, message, and timestamp. The route
does not return full tweet, profile, or direct-message objects. Keep message
text in a private support inbox, CRM, or agent queue.

### Build a Twitter API mentions queue

Store `notifications[].id` as the stable notification key. Record the connected
account ID beside every row. Upsert repeated notification IDs instead of
creating duplicate support tasks.

Route mention rows by `notification_type`, `message`, and `timestamp`. If an
agent needs the complete public tweet, follow the related
[user mentions endpoint](/api-reference/x/user-mentions). [X documents its user
mentions timeline as a paginated feed of posts that mention one
user.](https://docs.x.com/x-api/posts/timelines/introduction)

### Resume notification pages

Every response is one inbox page. Store `next_cursor` only when
`has_next_page` equals `true`. Save the page's notification rows before
updating the saved cursor.

When the destination supports transactions, save the page and cursor together.
Otherwise, upsert by notification ID. Update the cursor after the destination
writes the full page. Keep the preceding cursor until validating its
replacement.

### Choose polling or webhook delivery

This endpoint uses polling. The notification delay includes the
worker's polling interval. Run each new request from the latest confirmed
cursor. Stop when `has_next_page` is false.

Use [Xquik webhooks](/webhooks/overview) when an Xquik monitor should push
captured events to your HTTPS endpoint. X also offers a separate Account
Activity API for real-time account events. [Its documentation lists mentions,
replies, reposts, likes, follows, and direct
messages.](https://docs.x.com/x-api/account-activity/introduction)

## Twitter notification API questions

### Why are Twitter API notifications delayed?

A polling worker sees notifications only when its next request runs. Shorten
the polling interval within your rate limits. Store every cursor. A later
page can otherwise look like missing notifications.

### Can I delete or clear notifications with this route?

No. This route only reads notifications. Deleting a local triage row does not
remove the notification from X or another connected client.

### What happens when a notification request fails?

`401` means the connected account needs a valid key. `402` means the account
needs more credits. Wait for `Retry-After` after `429`. `424 account_required`
means you have no connected X account. Resume from the saved cursor after other
`424`, `502` or `503` responses.

## Query parameters

<ParamField query="type" type="string">
  Notification filter. `All` (default), `Verified`, or `Mentions`. Unrecognized values fall back to `All`.
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor. Pass the `next_cursor` value from the previous response to fetch the next page.
</ParamField>

## Which inbox endpoint?

<CardGroup cols={2}>
  <Card title="Account notifications" icon="bell">
    Use `GET /x/notifications` for connected-account notification rows with
    `All`, `Verified`, or `Mentions` filters.
  </Card>

  <Card title="Home timeline" icon="house">
    Use [`GET /x/timeline`](/api-reference/x/timeline) for the connected
    account's home timeline tweets.
  </Card>

  <Card title="Participant DMs" icon="message-square">
    Use [`GET /x/dm/{userId}/history`](/api-reference/x/dm-history) when the
    workflow needs private direct-message conversation rows.
  </Card>

  <Card title="Public mentions" icon="message-square-reply">
    Use [`GET /x/users/{id}/mentions`](/api-reference/x/user-mentions) when you
    need public mention timeline rows for a user.
  </Card>

  <Card title="Account monitor events" icon="radio">
    Use [`List events`](/api-reference/events/list) after account or keyword
    monitors have captured replayable webhook events.
  </Card>

  <Card title="Webhook delivery" icon="webhook">
    Use [`Webhooks`](/webhooks/overview) when notification-like activity should
    push to your system instead of waiting for a poll.
  </Card>
</CardGroup>

## Headers

<ParamField header="x-api-key" type="string" required>
  Your API key. Session cookie authentication is also supported.
</ParamField>

## Response

### 200 OK

<ResponseField name="notifications" type="object[]">
  Array of notification objects.
  **Notification object fields.**

  <ResponseField name="id" type="string">
    Notification ID.
  </ResponseField>

  <ResponseField name="type" type="string">
    Notification type (for example mention, like, retweet). Omitted if unavailable.
  </ResponseField>

  <ResponseField name="message" type="string">
    Notification message text. Omitted if unavailable.
  </ResponseField>

  <ResponseField name="timestamp" type="string">
    ISO 8601 timestamp. Omitted if unavailable.
  </ResponseField>
</ResponseField>

<ResponseField name="has_next_page" type="boolean">
  Whether more notifications are available.
</ResponseField>

<ResponseField name="next_cursor" type="string">
  Opaque cursor for the next page. Empty string when no more results.
</ResponseField>

<Note>
  **Related.** [Timeline](/api-reference/x/timeline), [DM History](/api-reference/x/dm-history), [User Mentions](/api-reference/x/user-mentions), and [Webhooks](/webhooks/overview).
</Note>

<div className="related-api-links">
  <Accordion title="Related timeline, bookmark & notification APIs" icon="link">
    * Account feeds: [Home timeline](/api-reference/x/timeline) · [Notifications](/api-reference/x/notifications) · [Mentions](/api-reference/x/user-mentions)
    * Saved and private: [Bookmarks](/api-reference/x/bookmarks) · [Bookmark folders](/api-reference/x/bookmark-folders) · [DM history](/api-reference/x/dm-history)
  </Accordion>
</div>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.