Paginated feed of tweets that mention an account, with engagement metrics and enriched author data.
GET https://twitterscore.io/api/v1/get_mentions_feed
Returns the tweets stored by TwitterScore that @-mention the target account, newest first by default, one page at a time (max 25 per page). Each item carries the tweet text (t.co short links are replaced with their display form, remaining t.co links stripped), creation time, favorites/retweets/replies/views, attached media and URLs, the quoted tweet when there is one, and an author block with the author's Twitter Score, follower count, tags and categories (those four are present only for authors that are tracked TwitterScore accounts; for other authors they are null/empty). The target's own tweets that mention itself are excluded. Optional author filters (tag_id, category_id, tag_category_id) keep only mentions written by accounts carrying that tag/category; when any author filter is set, authors that are not tracked TwitterScore accounts are dropped. by selects the sort column (tweet time, an engagement counter, or the author's Twitter Score). The filter ids are passed straight to the database lookup, so a non-numeric value surfaces as server_error rather than invalid_params.
Required: one of username, twitter_id.
Nested fields
mentions[].id(string): Tweet id as a string.mentions[].text(string): Tweet text with t.co links replaced by their display URL and remaining t.co links stripped; null if the stored tweet has no text.mentions[].created_at(string): Tweet creation time, ISO 8601 with offset (e.g. 2026-10-02T14:03:21+00:00). Always present.mentions[].favorites(integer): Like count.mentions[].retweets(integer): Retweet count.mentions[].replies(integer): Reply count.mentions[].views(integer): View count.mentions[].author(object): Tweet author.mentions[].author.twitter_id(string): Author's X user id as a string.mentions[].author.username(string): Author handle; "unknown" if TwitterScore has no profile data for the author.mentions[].author.name(string): Author display name; "Unknown" if not known.mentions[].author.profile_image(string): Avatar URL: the stored AWS image URL (absolute) when present, otherwise a site-relative image path ("/media/..."), or empty string when none.mentions[].author.blue_verified(boolean): X verified badge; false when the author is unknown.mentions[].author.followers_count(integer): Author's current follower count; null when the author is not a tracked TwitterScore account.mentions[].author.twitter_score(number): Author's Twitter Score (0-1000, float); null when the author is not a tracked TwitterScore account.mentions[].author.tags(array): Author's tags as [{id, name}]; empty when unknown.mentions[].author.categories(array): Author's categories as [{id, name}]; empty when unknown.mentions[].media(array): Attached media: [{url, type}].mentions[].media[].url(string): Media URL.mentions[].media[].type(string): Media type as reported by X (e.g. photo, video).mentions[].urls(array): Links in the tweet: [{url, expanded_url, display_url}].mentions[].urls[].url(string): Original URL (replaced by display_url when it was a t.co link found in the text).mentions[].urls[].expanded_url(string): Fully expanded URL.mentions[].urls[].display_url(string): Short display form.mentions[].quoted_tweet(object): Present only when the tweet quotes another tweet that is also stored; same shape as a mention item (including the extended author block) minusquoted_tweet. Absent (not null) otherwise.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
username |
string | no | X handle of the mentioned (target) account. Either username or twitter_id is required. |
|
twitter_id |
integer | no | Numeric X user id of the target account. Looked up first; falls back to username on a miss. |
|
page |
integer | no | 1 |
1-based page number. Non-numeric, 0 or negative falls back to 1; a page past the last returns an empty list. |
size |
integer | no | 10 |
Tweets per page. Clamped to 25; 0 or negative becomes 1; non-numeric falls back to 10. |
by |
string (created_at, favorites, retweets, replies, views, score) |
no | created_at |
Sort column: created_at (tweet time), favorites, retweets, replies, views, or score (author's Twitter Score; authors that are not tracked TwitterScore accounts have no score and sort first in ascending, last in descending order). Any other value returns success=false with message "Sorting is only possible by [created_at|favorites|retweets|replies|views|score]". |
sort |
string (asc, desc, ascending, descending) |
no | desc |
asc/ascending (case-insensitive) for ascending; anything else descending. |
tag_id |
integer | no | Keep only mentions whose author carries this tag. Non-numeric value → server_error. | |
category_id |
integer | no | Keep only mentions whose author has this account category. Non-numeric value → server_error. | |
tag_category_id |
integer | no | Keep only mentions whose author has at least one tag in this tag-category. Non-numeric value → server_error. |
At least one of username, twitter_id is required.
Example request
curl -s "https://twitterscore.io/api/v1/get_mentions_feed?username=VitalikButerin" \
-H "X-API-Key: $TWITTERSCORE_API_KEY" \
-H "User-Agent: my-app/1.0 ([email protected])"
import os, requests
r = requests.get(
"https://twitterscore.io/api/v1/get_mentions_feed",
params={"username": "VitalikButerin"},
headers={"X-API-Key": os.environ["TWITTERSCORE_API_KEY"],
"User-Agent": "my-app/1.0 ([email protected])"},
timeout=15,
)
data = r.json()
if not data.get("success", True): # errors arrive as success=false (see /developers/errors/)
raise RuntimeError(data["message"])
print(data)
const r = await fetch("https://twitterscore.io/api/v1/get_mentions_feed?username=VitalikButerin", {
headers: { "X-API-Key": process.env.TWITTERSCORE_API_KEY,
"User-Agent": "my-app/1.0 ([email protected])" },
});
const data = await r.json();
if (data.success === false) throw new Error(data.message);
console.log(data);
Example response
{
"success": true,
"total": 3156,
"page": 1,
"size": 1,
"pages": 3156,
"mentions": [
{
"id": "1841234567890123456",
"text": "Great thread by @VitalikButerin on account abstraction vitalik.eth.limo",
"created_at": "2026-10-02T14:03:21+00:00",
"favorites": 412,
"retweets": 57,
"replies": 23,
"views": 88214,
"author": {
"twitter_id": "1456789012",
"username": "cryptodev_eth",
"name": "Crypto Dev",
"profile_image": "https://twitterscore.io/media/profiles/cryptodev_eth.jpg",
"blue_verified": true,
"followers_count": 48213,
"twitter_score": 312,
"tags": [
{
"id": 22,
"name": "Ethereum"
}
],
"categories": [
{
"id": 8,
"name": "Influencers"
}
]
},
"media": [
{
"url": "https://pbs.twimg.com/media/GZabc123.jpg",
"type": "photo"
}
],
"urls": [
{
"url": "vitalik.eth.limo",
"expanded_url": "https://vitalik.eth.limo/",
"display_url": "vitalik.eth.limo"
}
]
}
]
}
Errors
Error codes this endpoint can return (see Errors for the body format): api_key_missing, api_key_invalid, api_access_deactivated, api_key_revoked, invalid_params, account_not_found, method_not_allowed, rate_limited, quota_exceeded, server_error.
Authentication: X-API-Key header (or Authorization: Bearer), see Authentication; existing integrations that pass ?api_key= keep working. Limits: per-minute rate and monthly quota by plan, see Rate limits. Machine-readable definition: /openapi.json.
This page as Markdown.