# 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 exist in TwitterScore's account table; 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 unknown to the account table 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 via datetime.isoformat() (e.g. 2026-10-02T14:03:21+00:00). The column is NOT NULL in the database, so it is always present in practice.
- `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 the author is in neither the account nor the friend table.
- `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 the local image path prefixed with MEDIA_URL ("/media/...", relative), 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 in the account table.
- `mentions[].author.twitter_score` (number): Author's Twitter Score (0-1000, float); null when not in the account table.
- `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 (media_url column).
- `mentions[].media[].type` (string): Media type as reported by X (media_type column, 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) minus `quoted_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 absent from the account table sort as NULL — first in ascending, last in descending order on MySQL/MariaDB). 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

```bash
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 (contact@example.com)"
```

```python
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 (contact@example.com)"},
    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)
```

```javascript
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 (contact@example.com)" },
});
const data = await r.json();
if (data.success === false) throw new Error(data.message);
console.log(data);
```

## Example response

```json
{
  "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": 11,
            "name": "Ethereum"
          }
        ],
        "categories": [
          {
            "id": 3,
            "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](/developers/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](/developers/authentication/). Limits: per-minute rate and monthly quota by plan, see [Rate limits](/developers/rate-limits/). Machine-readable definition: [/openapi.json](/openapi.json).