Twitter Mentions API | Tweets Mentioning a User
Return the tweets that mention a given account, cursor-paginated. This is the canonical way to read a handle's mentions; it is a thin wrapper over a to:username search and returns the same tweet objects. Cost: $0.0008 per call.
User Mentions returns the tweets that mention a given @handle, cursor-paginated as full tweet objects. It is the canonical way to read a profile's mentions and is a thin wrapper over a to:username search, returning the same tweet objects. Each page is one $0.0008 standard read.
Authorization
bearerAuth Pass your API key as a bearer token on every request: Authorization: Bearer <API_KEY>.
In: header
Query Parameters
Handle without the leading @ to find mentions of.
Pagination cursor from a previous response.
Accepted but not honoured on this endpoint: the upstream page is fixed at roughly 20 results and raising count does not return more. Use cursor to read further.
Comma-separated list of dotted field paths to keep in the response (one parameter, never repeated), applied to every object in the returned lists and to nested objects (for example fields=id,text,author.username; the list's own name may prefix a path, fields=tweets.id). A path prefix that lands on an array applies to each element (media.media_url_https). Pagination and envelope keys (next_cursor, cursor, has_more, count, partial, error, message, reason) are always kept. Unknown paths are ignored; up to 50 paths of up to 6 segments. Projection never changes status codes or billing, and applies to data reads only: account, feedback, session status, monitor (other than deliveries), webhook and stream-compat reads return their bodies unchanged.
Set to 1 (or true) to apply the built-in compact preset: ids, url, text, created_at, lang, the engagement counts, the is_retweet/is_reply/is_quote flags, conversation ids, the author's id/username/name/followers_count/verification, and the quoted or retweeted tweet's id/url/author username. The preset trims what it recognises and leaves alone what it would empty, so it never turns a body into {}. Combine with fields to add paths on top of the preset. Typically cuts a tweet page by 70 to 90 percent for LLM tool callers.
Filter this page's tweets by X's Paid partnership label: only keeps tweets whose is_paid_promotion is true, exclude keeps the rest. Omit it for every tweet. It filters the page X returned and does not fetch more, so a filtered page can hold fewer tweets than asked for, or none, while next_cursor still pages on. The response carries paid_promotion_filter { mode, kept, removed }, and count reflects what is returned. Any other value is a 400. Billing is the same as without it.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/user/mentions?username=twitterapis&count=20&fields=id%2Ctext%2Ccreated_at%2Cauthor.username&compact=1&paid_promotion=only"{ "tweets": [ { "id": "1759555444333222111", "text": "@twitterapis just shipped great docs.", "author": { "id": "9921", "username": "devjane" } } ], "next_cursor": "DAABCgABF..."}{ "error": "bad_request", "message": "Missing or malformed parameter. Fix the request before retrying."}{ "error": "unauthorized", "message": "The API key is missing, malformed, or revoked. Check the Authorization header."}{ "error": "insufficient_credits", "message": "Your balance is exhausted. Top up your credits to continue.", "top_up_url": "https://www.twitterapis.com/dashboard/buy-credits?utm_source=api&utm_medium=402"}{ "error": "forbidden", "message": "X refused this resource for the acting account: on a read, the account is not a participant in the DM thread, the target is protected or has blocked it, or the session was attestation-blocked for calling from a datacenter or rotating IP; on a write, the account is not authorized for the action or has no logged-in session. The credentials are still valid, so do not re-register."}{ "error": "not_found", "message": "The resource does not exist, for example a deleted tweet or a private account."}{ "error": "rate_limited", "message": "Too many requests. Back off and retry with exponential backoff."}{ "error": "server_error", "message": "Something failed on our side. Retry with backoff; if it persists, contact support."}Pricing
| Unit | Price |
|---|---|
| Per call | $0.0008 |
| Per 1,000 calls | $0.80 |
| Per 1,000 records (~20 per call) | ~$0.04 |
Each page of mentions is one $0.0008 read. For continuous monitoring, poll on an interval and dedupe by tweet ID rather than re-reading all pages.
When to use
Use it for mention monitoring, for example tracking every tweet that mentions your product handle.
Notes
- Equivalent to a tweet/advanced_search with query "to:username"; both return the same tweet objects.
Pagination
This endpoint is cursor-paginated and returns roughly 20 records per call. Pass the next_cursor from each response back as the cursor parameter to read the next page. Stop when the records array comes back empty: follower-graph endpoints return a non-null cursor even on the final page, so the empty array is the only reliable stop signal. See Pagination for the full loop.
Related endpoints
- Advanced Tweet Search: Search tweets with Twitter's full query-operator syntax, paginated with cursors.
- User Tweets: Fetch a user's public timeline (original tweets, retweets, and their own replies).
- User Info by Username: Fetch a full profile by @handle.
FAQ
How is User Mentions related to search?
It is equivalent to an Advanced Tweet Search with the query to:username. Both return the same tweet objects, so use whichever reads cleaner.
Can I monitor mentions in near real time?
Yes. Poll on an interval, keep a high-water-mark tweet ID, and surface only net-new mentions to avoid double counting.
What does each mention row contain?
Each row is a full tweet object with author, text, timestamp, and engagement counts, so you can triage mentions without a second call.
Full Tweet History GET
Collect a user's tweet history in bulk, auto-paginating server-side across upstream pages. Unlike GET /user/tweets (one upstream page per call), this drives pagination for you and returns a large batch in one request. Each call is bounded by both `max` and a server-side time budget, so it always returns inside a normal client timeout. When more history remains the response carries a `next_cursor` — pass it back as `cursor` to continue, and repeat until `next_cursor` is null. A public read: no registered session required. Cost: $0.0024 per call.
User Affiliates GET
Return the affiliated accounts linked under an organization's Verified Organizations profile. Useful for mapping a company to its employees and brand accounts. Cost: $0.0008 per call.