Skip to main content
GET https://xquik.com/api/v1/x/users/{id}/mentions Retrieve tweets that mention one profile. Store tweet IDs, authors, timestamps, media, engagement counts, and pagination cursors.
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 tweet returned · All plans from $0.00012/credit
This route returns tweets that mention one X account. Use it for brand mentions, support inboxes, lead routing, and agent handoffs. The route is GET /api/v1/x/users/{id}/mentions.
The Node.js and Python snippets write one JSON Lines row per mentioned tweet. Store each row with the latest next_cursor before requesting the next page.

Direct mention handoff

GET /x/users/{id}/mentions returns the newest tweets mentioning one account. Use it for a support, community, brand monitoring, lead routing, or agent workflow. This mentions timeline endpoint accepts a username or numeric user ID. It returns one JSON page at a time. Use mention_extractor for a saved extraction, estimate, or CSV, JSON, or XLSX file export. Store mentioned_user_id_or_username, tweet_id, text, tweet_url, author_id, author_username, author_name, author_followers, author_verified, author_profile_picture, created_at, and conversation_id. Also store reply context, engagement counts, media URLs, page_cursor, has_next_page, and next_cursor. Treat next_cursor as opaque. Pass it back as cursor only when has_next_page is true. Use sinceTime and untilTime to bound a poller window. Zero affordable results return 402 insufficient_credits.

Build a mentions triage job

These checkpoints fit a support inbox, lead queue, campaign report, or agent workflow. They cover mention pages for a fixed time window, with a cursor to resume.

Resolve the target

Use a username when the handle is stable. Store a numeric user ID for repeat jobs and warehouse joins.

Bound the window

Pass sinceTime and untilTime for a closed mention window. Do this when a poller, support queue, or campaign report needs one.

Route the row

Store author fields, reply context, and conversation_id for triage or scoring. Also store engagement counts, tweet_url, and media_urls for triage or scoring.

Cursor checkpoint

Store page_cursor, next_cursor, and has_next_page before requesting another mentions page.

Which timeline endpoint?

  • Use GET /api/v1/x/users/{id}/mentions for one user’s mentions timeline.
  • Use GET /api/v1/x/users/{id}/tweets for one user’s profile timeline.
  • Use GET /api/v1/x/tweets/search for keyword, operator, or advanced search.
  • Use GET /api/v1/x/timeline for the authenticated account’s home timeline.

Path parameters

Query parameters

Tweet result filters

These optional filters apply to tweets[] returned by this route. They keep the same mentions target. Xquik filters rows after it fetches each page. Selective filters can return fewer rows than an unfiltered page.See tweet filters for every filter. Common ones are fromUser, language, sinceDate, mediaType, minLikes, and hashtags.

Choose fields

Headers

Response

200 OK

400 Invalid user ID

{ "error": "invalid_user_id", "message": "Send a user ID, @username or profile URL, such as x.com/nasa." }

401 Unauthenticated

Anonymous requests get WWW-Authenticate: Bearer and a guest wallet checkout action. This is not a Payment challenge.

402 Payment required

Account keys get account options. Guest keys get guest top-up only. No checkout starts automatically. Confirm any payment action.

502 X API unavailable

The read service returned an error. Retry after a short delay.

429 Rate limit exceeded

You exceeded your tier rate limit. Wait for the Retry-After header before retrying.

424 Dependency failed

The normalized v1 response contract can return 424 when the read service is unavailable.

Response examples

  • 400 { "error": "invalid_input", "message": "Invalid input. Check the request body." }
  • 401 { "error": "unauthenticated", "message": "Authentication required." }
  • 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." }
  • 404 { "error": "user_not_found", "message": "X user not found. Check the username." }
  • 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." }