Twitter (X) API Mentions: Get Every Post That Mentions an Account

- Two pull sources:
/twitter/user/mentions(userName,sinceTime,untilTime,cursor) and/twitter/tweet/advanced_searchwithquery=@handle. Same tweet objects, same 20-post pages, same price. - Measured overlap: of 616 mentions of 10 organization accounts in one 6-hour window, 97.4% came from both sources, 1.3% only from the mentions endpoint and 1.3% only from search.
- What a mention feed is made of: 83.6% replies, 3.4% quotes, 13.0% standalone posts; 68.3% of the 496 distinct authors had a blue check.
- Incremental polling: pass a
sinceTimewith a small overlap, dedupe byid, stop paging at the first known id, and end on an empty page, becausehas_next_pagecan be true on the last real page. - Cost: $0.15 per 1,000 tweets returned; an empty check costs the $0.00015 minimum, so polling every 60 s has a floor of $6.48 a month, every 5 min $1.30. X's rate card is $0.005 per post read.
- Push instead of poll:
POST /oapi/tweet_filter/add_rulewithvalue: "@handle", activate it withupdate_rule, and new mentions arrive at your webhook.
This guide is for developers who need mentions of an X (Twitter) account as data: a support queue that picks up every post tagging your brand, a bot that answers when someone mentions it, a dashboard that counts mentions per hour. If you only want to see who mentioned you inside the X app, the consumer guide on searching mentions covers the Notifications tab and search operators; keyword alerts and X's Account Activity API have their own guides, linked at the end.
Instead of restating the docs, we measured the question every mention integration eventually hits: if you ask the dedicated mentions endpoint and a search for @handle about the same accounts and the same hours, do you get the same posts? We pulled both for 10 organization accounts, including @vercel, @stripe and @Docker, over one fixed 6-hour window and compared them post by post. The numbers drive the code below: which source to call, how to page and stop, how to dedupe, and what continuous polling costs on TwitterAPI.io and on X's official rate card.
97.4%
Three API routes to an account's mentions
On TwitterAPI.io there are two read endpoints that return mentions, plus one search operator that narrows them to direct replies. All three return the same tweet object (id, url, text, createdAt, isReply, inReplyToUsername, entities, quoted_tweet, author, the engagement counts) at the top level of the response as tweets[], with has_next_page and next_cursor for paging. None of them needs an X account, an OAuth app or a user token: the only credential is the X-API-Key header.
The dedicated endpoint takes the window as unix seconds; the docs at docs.twitterapi.io/api-reference/endpoint/get_user_mention say 9-10 digit values, and that milliseconds return HTTP 400. In search, the same window is written into the query as since_time:<unix> and until_time:<unix>. The search route is the one to use when the mention has to be filtered further: @stripe -from:stripe lang:en drops the account's own posts and anything not in English, and @stripe -filter:replies keeps only standalone posts.
Both endpoints are billed the same way: 15 credits per tweet returned ($0.15 per 1,000 tweets), with a minimum of 15 credits ($0.00015) for a request that returns nothing. There is no cost reason to prefer one over the other; the reasons are parameters and coverage, which the next section measures.
# 1. The dedicated endpoint (unix seconds, not milliseconds)
curl -s "https://api.twitterapi.io/twitter/user/mentions?userName=stripe&sinceTime=1767225600" \
-H "X-API-Key: $TWITTERAPI_IO_API_KEY"
# 2. Search with the @handle operator (URL-encode the query)
curl -s -G "https://api.twitterapi.io/twitter/tweet/advanced_search" \
--data-urlencode "query=@stripe since_time:1767225600" \
--data-urlencode "queryType=Latest" \
-H "X-API-Key: $TWITTERAPI_IO_API_KEY"
# 3. Only direct replies to the account
curl -s -G "https://api.twitterapi.io/twitter/tweet/advanced_search" \
--data-urlencode "query=to:stripe" --data-urlencode "queryType=Latest" \
-H "X-API-Key: $TWITTERAPI_IO_API_KEY"Do the mentions endpoint and an @handle search return the same posts?
Mostly, but not exactly. We asked both sources for the mentions of 10 organization accounts inside one identical 6-hour UTC window, paged each source up to 6 pages, and compared tweet ids. Where a source hit the page cap before the window start (all of @vercel, and the search side of @stripe), we compared only the span both sources fully covered, so a post could not count as missing just because we stopped paging.
Result. The union held 616 distinct mention posts. 600 of them (97.4%) were returned by both sources, 8 (1.3%) only by /twitter/user/mentions, and 8 (1.3%) only by the @handle search. Each source alone therefore covered 98.7% of what the two found together. Six of the ten accounts matched exactly; the differences sat in the four busiest feeds.
What the differences look like. All 16 one-sided posts carried the literal @handle in their text, so neither source was skipping a different kind of mention (such as reply-chain mentions without the handle). 14 of the 16 were replies, and every one came from an author with fewer than 10,000 followers, most with fewer than 100. We cannot see why an individual post was absent from one source; the sample is one window of one day, and the gap could be indexing timing at the moment of collection. What the data does support is a design rule: if your feed must not drop a mention (a support queue, a moderation tool), query both and merge by id; if a 1-2% miss rate is acceptable (trend counts, dashboards), one source is enough and costs half.
An earlier, smaller sample on our consumer guide to searching mentions (240 posts from six accounts) found the two sets identical. This larger pull shows that identical is the common case per account, not a guarantee across a busy feed.

What a mention feed is made of: replies, quotes, verified authors
The same 616 posts tell you what your consumer code will receive. Mentions are overwhelmingly replies: 83.6% had isReply: true, 3.4% were quotes (quoted_tweet present, not a reply) and only 13.0% were standalone posts. That matters because a reply mentions the account either because the author addressed it or because the handle was carried into a reply chain; only 22.6% of all mentions were replies whose inReplyToUsername was the monitored account itself.
Volume per hour. Across the ten accounts, mention volume ranged from 0.8 to 28.5 posts per hour, with a median of 9.55. @vercel was the busiest at 28.5 an hour, followed by @stripe (18.0) and @Docker (16.3); @n8n_io was the quietest at 0.8. A mentions feed for a mid-size developer brand is therefore a few posts every few minutes, not a firehose, which is why polling every 1-5 minutes is a reasonable default.
Blue checks. 68.3% of the 496 distinct authors carried author.isBlueVerified: true, counted once per author. Practitioners commonly use the blue check as a rough priority signal for triage queues; whether it tracks quality for your audience is something to calibrate on your own data, since the share varied from 48% (@supabase) to 85% (@NotionHQ) in this sample.
Routing rule of thumb. If you only care about posts addressed to you, to:handle or a filter on inReplyToUsername keeps roughly the 22.6% slice; if you care about every place your name appears (brand monitoring), keep the full set and use isReply, quoted_tweet and conversationId to group the thread around each mention.

Incremental polling: page, stop at a known id, dedupe
A mentions poller has three jobs: ask only for new posts, stop paging as soon as it reaches posts it already has, and never emit the same post twice. The runnable script at the end of this page does all three; here is why each step is shaped the way it is.
Ask for a window, with overlap. Pass sinceTime (unix seconds) equal to the start of the previous pass minus a few minutes. The overlap costs a few repeated tweets per pass but protects you against clock skew and posts that become visible a little after their createdAt. On the search route the same idea is since_time: inside the query.
Stop at a known id. Both sources return newest first. When a page contains an id you already stored, every older post on later pages is also known, so stop paging that source. This keeps a steady-state pass to one page per source, which is what makes 1-minute polling affordable.
End on an empty page, not on a short page. In our pull, every source that ran out of posts inside the window returned one final page with zero tweets (17 such pages across 20 source runs), and the page before it still said has_next_page: true. The docs for the mentions endpoint state the same thing: has_next_page may be true when no more data exists. Short pages also appeared mid-stream (one search run returned 20, 20, 20, 8, 4 and then 0), so a page with fewer than 20 posts is not a reliable end marker. Average non-empty pages held 18.4 posts on the mentions endpoint and 17.5 on search. Treat an empty tweets[] or a missing next_cursor as the end.
Dedupe by id across sources. Key every post by id in one dictionary. A quote of a mention is a separate post with its own id, so it is counted once in its own right.
Store a bounded set of seen ids. The script keeps the newest 5,000 ids per handle in a JSON file. At the busiest rate we measured (28.5 an hour) that is about a week of history, far more than the 5-minute overlap needs. A database table with a unique index on id works the same way at larger scale.
Handle errors explicitly. A missing or invalid parameter returns HTTP 400 with the text in detail; an error in the body comes back as status: "error" with the reason in msg; HTTP 429 means you exceeded your QPS tier (0.2 requests per second before the first payment, 20 once paid), so wait and retry the same cursor.
{
"tweets": [
{
"id": "...",
"url": "https://x.com/<author>/status/...",
"text": "@stripe is there a way to ...",
"createdAt": "Thu Nov 19 22:41:32 +0000 2026",
"lang": "en",
"isReply": true,
"inReplyToUsername": "<someone>",
"conversationId": "...",
"likeCount": 0, "replyCount": 0, "retweetCount": 0, "quoteCount": 0,
"entities": {"user_mentions": [{"screen_name": "stripe", "...": "..."}]},
"quoted_tweet": null,
"author": {"userName": "<author>", "followers": 312, "isBlueVerified": false, "...": "..."}
}
],
"has_next_page": true,
"next_cursor": "...",
"status": "success",
"msg": "success"
}What polling mentions costs, and the official X API comparison
Two numbers decide the bill: how often you check, and how many mentions actually exist. Every check is billed at least the 15-credit minimum ($0.00015) even when it returns nothing, and every mention returned costs 15 credits. With the stop-at-known-id rule, a mention is normally returned once, plus whatever falls into your overlap window.
The floor applies to checks that find nothing; checks that return posts are billed per post instead. On top of that comes the per-mention cost. Projecting the measured hourly rates over 30 days, one source, priced on TwitterAPI.io at $0.15 per 1,000 tweets and on X's pay-per-use rate card at $0.005 per post read (docs.x.com/x-api/getting-started/pricing):
Per 1,000 tweets that is $0.15 against $5, about 33 times. X's pay-per-use plans are also capped at 3 million post reads per monthly billing cycle, with Enterprise above that; there is no such cap on TwitterAPI.io, you pay only for the data returned. Querying both sources for full coverage doubles the per-mention line (each post is returned twice) to buy the extra 1.3% we measured.
A study note for scale: collecting this page's entire dataset took 87 requests and returned 1,259 tweets for about $0.19. New accounts that pass the automatic bot check get up to $1 of free credits (at most 100,000 credits, no card, one per person or network, expiring after 31 days), enough to replicate it several times; purchased credits never expire.
Push instead of poll: a filter rule for @handle and a webhook
If you would rather not run a poller, a tweet filter rule can deliver new mentions to an HTTPS endpoint you host. Create the rule with POST /oapi/tweet_filter/add_rule, using @handle as the rule value (the same operator syntax as search, up to 255 characters, so @stripe -from:stripe works) and an interval_seconds that sets how often the rule is checked. New rules start inactive: activate them with POST /oapi/tweet_filter/update_rule, sending every field again plus is_effect: 1. Matching posts are then POSTed to the webhook URL configured in the TwitterAPI.io dashboard.
When push fits. One rule can watch several handles (@vercel OR @nextjs), your receiver wakes only when something matches, and you do not keep a cursor or a seen-id store for the polling side. You still dedupe by id in the receiver, and you still answer the webhook with HTTP 200 quickly.
When polling fits. Backfills ("all mentions since Monday"), jobs that already run on cron, environments with no public HTTPS endpoint, and cases where you want both sources merged for maximum coverage. The webhooks guide linked below compares filter-rule receivers with X's Account Activity API in detail, including retries and receiver design.
import os
import requests
BASE = "https://api.twitterapi.io"
H = {"X-API-Key": os.environ["TWITTERAPI_IO_API_KEY"], "Content-Type": "application/json"}
rule = {"tag": "mentions-stripe", "value": "@stripe", "interval_seconds": 60}
r = requests.post(f"{BASE}/oapi/tweet_filter/add_rule", headers=H, json=rule, timeout=30)
body = r.json()
if body.get("status") != "success":
raise SystemExit(body.get("msg"))
# New rules are inactive. Activate with update_rule, sending every field again.
r = requests.post(f"{BASE}/oapi/tweet_filter/update_rule", headers=H,
json={"rule_id": body["rule_id"], **rule, "is_effect": 1}, timeout=30)
print(r.json())
# Matching posts are now POSTed to the webhook URL set in the twitterapi.io dashboard.
# Your receiver should answer 200 quickly and dedupe by tweet id, exactly like the poller.
print(requests.get(f"{BASE}/oapi/tweet_filter/get_rules", headers=H, timeout=30).json())
X's own mentions endpoint: GET /2/users/:id/mentions
On the official X API, mentions live at GET https://api.x.com/2/users/:id/mentions. It takes the numeric user id, not the handle, so you resolve the handle first with a user lookup (a separate user read on the rate card). Its parameters per docs.x.com/x-api/users/get-mentions: max_results from 5 to 100, pagination_token, start_time and end_time (on or after 2010-11-06), since_id and until_id, plus the tweet.fields, user.fields and expansions field selectors. Authentication is an OAuth 2.0 user token with tweet.read and users.read, or an app bearer token.
The rate-limit table at docs.x.com/x-api/fundamentals/rate-limits lists the endpoint at 450 requests per 15 minutes per app and 300 per 15 minutes per user. Pricing is per post read at $0.005, which is where the comparison table above comes from, and pay-per-use is capped at 3 million post reads a month. The official endpoint is a reasonable choice when you already hold an X developer account and need OAuth-scoped access for a user; the trade-offs are the per-read price, the separate id lookup and the developer-app setup.
If you are moving existing code over, the mapping is direct: start_time becomes sinceTime (unix seconds), pagination_token becomes cursor, and meta.next_token becomes next_cursor. Fields are already embedded in each tweet (no expansions step): the author object sits under author, the quoted post under quoted_tweet.
Common mistakes in mention integrations
Stopping on a short page. Pages can hold fewer than 20 posts in the middle of a result set. End on an empty page or a missing cursor, and cap the page count per pass so a misconfigured window cannot run away.
Passing milliseconds. sinceTime=1767225600000 is rejected with HTTP 400; the endpoint wants unix seconds.
Counting the account's own posts. In this sample no monitored account appeared in its own mention set, but brands that reply in threads will, because their replies carry other handles. Add -from:handle in search, or skip posts where author.userName equals the handle.
Treating a 1-2% gap as zero. For counts and charts it is noise; for a support queue it is a customer who never got an answer. Decide which one you are building before choosing one source or two.
Polling faster than mentions arrive. At the median rate we measured (9.55 an hour) a 60-second poll finds nothing most of the time and pays the empty-check floor each time; a 2-5 minute cadence returns the same posts with fewer empty checks. Go faster only when reply latency is the product.
Using the handle as a stable key. Handles change. Store author.id and the tweet id; display author.userName.
How we collected this
Question. For the same accounts and the same time window, how much do /twitter/user/mentions and /twitter/tweet/advanced_search with @handle overlap, and what is the mix of replies, quotes and standalone posts in a mention feed?
Accounts and window. Ten organization accounts with steady mention volume: @vercel, @supabase, @Docker, @Cloudflare, @stripe, @figma, @NotionHQ, @linear, @Railway and @n8n_io. One fixed 6-hour UTC window, identical for every account and both sources, ending about 30 minutes before collection, collected in 2026.
Method and sample size. Up to 6 pages per account per source, through our rate-limited read client: 87 requests, 1,259 tweets returned, 616 distinct mention posts after merging by tweet id. Where a source hit the page cap before the window start, overlap was measured only over the span both sources fully covered (4.2 hours for @vercel).
What the sample cannot show. One window on one day is a snapshot: mention volume, the reply share and the small gaps between sources can differ by day, by account size and in a viral spike. We cannot tell why an individual post was missing from one source. Mention volume here is for organization accounts, not personal accounts.
Privacy. Most people who mention a brand are private individuals, so the raw pages were never stored in our repository. We kept only aggregates and de-identified rows (no tweet id, url, text, author id or handle). Only the ten organization accounts are named.
"""mentions_feed.py - collect every post that mentions an X (Twitter) account, incrementally.
pip install requests
export TWITTERAPI_IO_API_KEY=... # from the twitterapi.io dashboard
python mentions_feed.py stripe # one pass; run it from cron every 1-5 minutes
Each pass asks two sources for mentions newer than the last pass (minus a 5-minute
overlap), merges them by tweet id and stops paging a source as soon as it reaches a
post it has already seen. Cost: 15 credits ($0.00015) per tweet returned; a check
that finds nothing is billed the 15-credit minimum.
"""
import json
import os
import sys
import time
import requests
BASE = "https://api.twitterapi.io"
HEADERS = {"X-API-Key": os.environ["TWITTERAPI_IO_API_KEY"]}
STATE = "mentions_state.json"
def pages(url, params, max_pages=50):
"""Yield one list of tweets per page until the source is exhausted."""
cursor = ""
for _ in range(max_pages):
r = requests.get(url, headers=HEADERS, params={**params, "cursor": cursor}, timeout=30)
if r.status_code == 429: # over your QPS tier: wait, then retry this page
time.sleep(5)
continue
if r.status_code == 400:
raise RuntimeError(r.json().get("detail"))
r.raise_for_status()
body = r.json()
if body.get("status") == "error":
raise RuntimeError(body.get("msg"))
tweets = body.get("tweets") or []
yield tweets
cursor = body.get("next_cursor") or ""
# has_next_page can be true on the last real page; an empty page ends the walk
if not tweets or not body.get("has_next_page") or not cursor:
return
def fetch_new(handle, since_unix, seen_ids):
sources = [
(f"{BASE}/twitter/user/mentions",
{"userName": handle, "sinceTime": since_unix}),
(f"{BASE}/twitter/tweet/advanced_search",
{"query": f"@{handle} since_time:{since_unix}", "queryType": "Latest"}),
]
new = {}
for url, params in sources:
for page in pages(url, params):
fresh = [t for t in page if t["id"] not in seen_ids]
for t in fresh:
new[t["id"]] = t # dedup across both sources by tweet id
if len(fresh) < len(page): # newest first: we reached known posts, stop
break
return new
def main():
handle = sys.argv[1].lstrip("@")
state = json.load(open(STATE)) if os.path.exists(STATE) else {}
entry = state.get(handle, {"since": int(time.time()) - 3600, "seen": []})
started = int(time.time())
seen = set(entry["seen"])
new = fetch_new(handle, entry["since"] - 300, seen)
for t in sorted(new.values(), key=lambda t: int(t["id"])):
author = t.get("author") or {}
kind = "reply" if t.get("isReply") else ("quote" if t.get("quoted_tweet") else "post")
print(f'{t["createdAt"]} {kind:5} @{author.get("userName")} {t["url"]}')
print(" " + t["text"][:160].replace("\n", " "))
seen |= set(new)
state[handle] = {"since": started, "seen": sorted(seen, key=int)[-5000:]}
json.dump(state, open(STATE, "w"))
print(f"{len(new)} new mentions of @{handle}", file=sys.stderr)
if __name__ == "__main__":
main()
Researching this?Free starter credits cover end-to-end testing — Google sign-in, no card. Get a key.
Questions readers ask
Is there an API endpoint to get all mentions of a Twitter account?
Yes. On TwitterAPI.io, GET /twitter/user/mentions?userName=<handle> returns posts that mention the account, 20 per page, newest first, with optional sinceTime and untilTime in unix seconds. A search for @handle on /twitter/tweet/advanced_search returns nearly the same set; in our sample of 616 mentions, 97.4% came from both. On X's official API the endpoint is GET /2/users/:id/mentions.
Do I need an X developer account or OAuth to read mentions?
Not on TwitterAPI.io: reads need only the X-API-Key header from your dashboard, and no X account is involved. X's own /2/users/:id/mentions requires a developer app and either an OAuth 2.0 user token with tweet.read and users.read or a bearer token.
Should I use the mentions endpoint or search for @handle?
Use the mentions endpoint when you want one account and a clean time window; use search when you need extra operators such as -from:handle, lang:en or to:handle. If missing any mention is unacceptable, call both and merge by tweet id: in our measurement each one alone missed 1.3% of the posts the two found together.
How much does it cost to monitor mentions with the Twitter API?
On TwitterAPI.io each tweet returned costs 15 credits ($0.15 per 1,000), and an empty check costs the $0.00015 minimum, so a 60-second poll has a floor of $6.48 a month and a 5-minute poll $1.30. At the median mention rate we measured (9.55 an hour) the mentions themselves cost about $1.03 a month, against $34.38 at X's $0.005 per post read.
How do I get only new mentions since my last check?
Pass sinceTime (or since_time: in search) set to your previous run minus a few minutes, store seen tweet ids, stop paging a source as soon as a page contains a known id, and end on an empty page. has_next_page can still be true on the last real page.
Does the mentions API include replies and quote posts?
Yes. In our sample 83.6% of mentions were replies, 3.4% quotes and 13.0% standalone posts. Use isReply, inReplyToUsername and quoted_tweet on each tweet to tell them apart, or to:handle in search to keep only direct replies.
Can I get mentions pushed to me instead of polling?
Yes. Create a tweet filter rule with POST /oapi/tweet_filter/add_rule and value set to @handle, activate it with update_rule and is_effect: 1, and matching posts are POSTed to the webhook URL set in your dashboard.
Continue
- TwitterAPI.io API reference: get user mentions (userName, sinceTime, untilTime in seconds, cursor; has_next_page note)
- TwitterAPI.io API reference: add a tweet filter rule (tag, value, interval_seconds; new rules inactive)
- TwitterAPI.io API reference: update a tweet filter rule (all fields required, is_effect)
- X API docs: GET /2/users/{id}/mentions (parameters and authentication)
- X API docs: rate limits (mentions 450 per 15 min per app, 300 per user)
- X API docs: pay-per-use pricing ($0.005 per post read, 3M monthly cap)
- X (Twitter) API hub: endpoints, pricing and guides
- How to search mentions on Twitter (X) in the app
- Twitter keyword alerts: a developer guide
- X Account Activity API: mention events and webhooks
- Twitter (X) webhooks guide: filter-rule receivers vs Account Activity
- TwitterAPI.io pricing: $0.15 per 1,000 tweets
- TwitterAPI.io API reference and docs
- 01Twitter (X) Verification in 2026: What the Blue, Gold and Grey Checkmarks Mean and How to Get One
- 02"You Can No Longer Send Messages to This Person" on Twitter (X): What It Means and What You Can Do
- 03Twitter (X) API with LangGraph: Build a Search Agent Graph
- 04C# Twitter (X) API: a .NET client with HttpClient and System.Text.Json
- 05How to Log Out of Twitter (X) on Web, iPhone and Android
- 06How to Search and Track Mentions on Twitter (X), Including Someone Else's
- 07Base44 alternatives in 2026: Lovable, Bolt.new, Replit, v0, Emergent, open-source Dyad and coding agents compared
- 08What Is a Twitter (X) Handle? The @Username Explained
Writing about something you built with TwitterAPI.io? Our community rewards program pays API credits for honest tutorials, build logs and videos.
Stop reading. Start building.
Starter credits cover real testing on real data. Google sign-in, no card, no application queue.
Get an API keyAlready building with TwitterAPI.io? Publish an honest tutorial or build log about it and earn up to $200 a month in API credits.