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
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.
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
UseGET /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
CallGET /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
Storenotifications[].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. Storenext_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 whenhas_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
Related. Timeline, DM History, User Mentions, and Webhooks.
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." }