Skip to main content
GET https://xquik.com/api/v1/x/notifications
Requested result counts are upper bounds for paid authenticated calls. Remaining credits may not cover the full page or ID list. If so, Xquik returns fewer results. If zero paid results are affordable, it returns 402 insufficient_credits.
1 credit per result returned · All plans from $0.00012/credit
The route reads notifications through your connected X account. Without one, it returns 424 account_required. Use Connect X account 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 or type=Verified for verified-account activity. Or omit type for all notification rows. Store next_cursor only when has_next_page is true.
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. Use them for private support dashboards, CRM queues, and agent workflows.

Notification triage handoff

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

Mention queue

Use type=Mentions for replies and mentions that need a support or brand review queue.

Verified activity

Use type=Verified when you route verified-account activity ahead of the general inbox.

All inbox

Omit type or pass All for every notification row visible to the connected account.

Stable upserts

Store notifications[].id as notification_id for deduplication and replay-safe imports.

Private text

Keep notifications[].message in private support, CRM, or agent memory systems.

Next page

Store has_next_page and next_cursor. Then pass next_cursor back as cursor only when has_next_page is true.

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 an X (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. X documents its user mentions timeline as paginated posts that mention one user.

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 when a 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.

Twitter notification API questions

Why are X (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. Another connected client also keeps the notification.

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

Which inbox endpoint?

Account notifications

Use GET /x/notifications for connected-account notification rows with All, Verified, or Mentions filters.

Home timeline

Use GET /x/timeline for the connected account’s home timeline tweets.

Participant DMs

Use GET /x/dm/{userId}/history when the workflow needs private direct-message conversation rows.

Public mentions

Use GET /x/users/{id}/mentions when you need public mention timeline rows for a user.

Account monitor events

Use List events after account or keyword monitors have captured replayable webhook events.

Webhook delivery

Use Webhooks when notification-like activity should push to your system without a poll.

Headers

Response

200 OK

Response examples

200 example

  • 400 { "error": "invalid_input", "message": "Invalid input. Check the request body." }
  • 401 { "error": "unauthenticated", "message": "Authentication required. Provide a valid API key or bearer token." }
  • 402 { "error": "insufficient_credits", "message": "Insufficient credits. Top up or subscribe to continue." }
  • 403 { "error": "api_key_paused", "message": "This API key is paused. Resume it at dashboard.xquik.com/api-keys to use it again." }
  • 424 { "error": "x_api_unavailable", "message": "X data source temporarily unavailable. Try again later." }
  • 429 { "error": "rate_limit_exceeded", "message": "Too many requests. Try again later.", "retryAfter": 60 }
  • 502 { "error": "x_api_unavailable", "message": "X data source temporarily unavailable. Try again later." }
  • 503 { "error": "x_api_unavailable", "message": "Xquik is busy right now. Retry shortly." }