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

By TwitterAPI.io Team•14 min read
Diagram: the mentions endpoint and an @handle search feed one merge step that dedupes by tweet id, with a filter-rule webhook as the push alternative
Two pull sources merged by tweet id, or one push rule. Overlap measured on 616 mentions of 10 organization accounts, collected in 2026.
TL;DR
  • Two pull sources: /twitter/user/mentions (userName, sinceTime, untilTime, cursor) and /twitter/tweet/advanced_search with query=@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 sinceTime with a small overlap, dedupe by id, stop paging at the first known id, and end on an empty page, because has_next_page can 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_rule with value: "@handle", activate it with update_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.

Mentions returned by both the mentions endpoint and an @handle search (616 posts, 10 accounts)

97.4%

01 — Section

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.

RouteKey parametersReturnsUse it for
/twitter/user/mentionsuserName, sinceTime, untilTime, cursorposts that mention the handle, 20 per page, newest firstone account, a clean time window
/twitter/tweet/advanced_search @handlequery, queryType=Latest, cursorthe same mentions, plus any operator you addcombining with -from:, lang:, filter:
/twitter/tweet/advanced_search to:handlequery, queryTypeonly replies addressed to the accounta support inbox of direct replies

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.

bash
# 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"
02 — Section

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.

AccountMentions (union)In bothOnly mentions endpointOnly search
@vercel12011730
@stripe1079908
@Docker989530
@Cloudflare737210
@supabase595810
@figma, @NotionHQ, @linear, @Railway, @n8n_io15915900

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.

Horizontal stacked bar chart of mention posts per account split into returned by both sources, only by the mentions endpoint, and only by @handle search; 97.4% overlap overall
Per-account overlap of /twitter/user/mentions and advanced_search @handle over one 6-hour window, 616 posts, deduplicated by tweet id; collected in 2026.
03 — Section

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.

Share of the 616 mentionsValue
Replies (isReply: true)83.6%
Replies directly to the monitored account22.6%
Quotes (not replies)3.4%
Standalone posts13.0%
Text contains the literal @handle99.8%
Distinct authors with a blue check (of 496)68.3%

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.

Bar chart of mentions per hour for ten organization accounts, from 28.5 per hour for @vercel to 0.8 for @n8n_io, with the reply share of each
Mentions per hour and reply share per account, union of both sources, one 6-hour UTC window; collected in 2026.
04 — Section

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.

json
{
  "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"
}
05 — Section

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.

Polling cadenceChecks in 30 daysFloor (one source)Floor (both sources)
Every 60 seconds43,200$6.48$12.96
Every 5 minutes8,640$1.30$2.59

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):

Account volume (measured)Mentions in 30 daysTwitterAPI.ioOfficial X API
Busiest, 28.5 per hour20,520$3.08$102.60
Median, 9.55 per hour6,876$1.03$34.38
Quietest, 0.8 per hour576$0.09$2.88

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.

06 — Section

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.

python
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())
07 — Section

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.

ItemTwitterAPI.ioOfficial X API
Mentions endpoint/twitter/user/mentions?userName=/2/users/:id/mentions
Identifierhandlenumeric user id
AuthX-API-Key headerOAuth 2.0 user token or bearer
Page sizeup to 205 to 100
Price per 1,000 posts$0.15$5.00

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.

08 — Section

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.

09 — Section

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.

python
"""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.

10 — Questions

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.

11 — Further reading

Continue

Sources & further reading
More from this series

Writing about something you built with TwitterAPI.io? Our community rewards program pays API credits for honest tutorials, build logs and videos.

Build it

Stop reading. Start building.

Starter credits cover real testing on real data. Google sign-in, no card, no application queue.

Get an API key

Already building with TwitterAPI.io? Publish an honest tutorial or build log about it and earn up to $200 a month in API credits.