# Leaderboard of accounts most mentioned by smart accounts over the last 1, 7 or 30 days (Smart Mentions page).

`GET https://twitterscore.io/api/v1/get_smart_mentions`

Returns the Smart Mentions ranking: up to 1,000 accounts ordered by how many times they were mentioned by TwitterScore-tracked authors in the selected window (`days` = 1, 7 or 30), paginated up to 100 per page. No target account is needed. Each row gives the account's profile, its Twitter Score and follower count with their change over the period (`*_diff_int` plus a human-readable `*_diff_str` with space-grouped thousands), all-time mention totals (`mentions_total`, `unique_mentioners_total`), the period's mentions and unique mentioners (`mentions_diff_int`, `unique_mentioners_diff_int`), the single highest-scored mentioner (`top_mentioner`) and up to six top mentioners (`mentioners_list`), plus the account's categories. `category_id` filters the board to one account category (0 = all, -1 = accounts with no category). `by` changes the ranking column: `mentions` (period mentions, default), `mentioners` (ALL-TIME unique mentioners), `score`, `followers`; ties are broken by all-time mentions descending. Only non-suspended accounts with at least one period mention and at least 2/3/4 distinct mentioning authors (for 1/7/30 days) are listed. Data comes from a pre-aggregated cache refreshed by cron; the extra `days` and `category_name` fields echo the applied filters.
**Nested fields**

- `data[].twitter_id` (string): X user id as a string.
- `data[].username` (string): X handle.
- `data[].name` (string): Display name (falls back to username).
- `data[].profile_url` (string): Relative TwitterScore profile path like /twitter/VitalikButerin (slug, else username), or "#" when neither is set.
- `data[].profile_image` (string): Avatar URL (AWS copy, else X image URL), or null.
- `data[].blue_verified` (boolean): X verified badge.
- `data[].description` (string): X bio (may be empty).
- `data[].twitter_score` (integer): Current Twitter Score (0-1000) from the period snapshot, truncated to int.
- `data[].twitter_score_diff_int` (integer): Twitter Score change over the window.
- `data[].twitter_score_diff_str` (string): Same value formatted with spaces as thousands separators (e.g. "1 532", "-1 532").
- `data[].current_followers` (integer): Current follower count.
- `data[].followers_diff_int` (integer): Follower change over the window.
- `data[].followers_diff_str` (string): Formatted follower change.
- `data[].mentions_total` (integer): All-time mentions by tracked authors.
- `data[].mentions_diff_int` (integer): Mentions received in the window (ranking value for by=mentions; per-author contribution is capped).
- `data[].mentions_diff_str` (string): Formatted window mentions.
- `data[].unique_mentioners_total` (integer): All-time distinct mentioning authors (ranking value for by=mentioners).
- `data[].unique_mentioners_diff_int` (integer): Distinct mentioning authors in the window.
- `data[].unique_mentioners_diff_str` (string): Formatted window unique mentioners.
- `data[].top_mentioner` (object): Highest-scored mentioner in the window: {name, username, image, score, verified}; null when none computed.
- `data[].top_mentioner.name` (string): Mentioner display name (falls back to username).
- `data[].top_mentioner.username` (string): Mentioner handle.
- `data[].top_mentioner.image` (string): Mentioner avatar URL or empty string.
- `data[].top_mentioner.score` (integer): Mentioner Twitter Score, rounded to int.
- `data[].top_mentioner.verified` (boolean): Mentioner verified badge.
- `data[].mentioners_list` (array): Up to 6 top mentioners in the window, same object shape as top_mentioner, ordered by Twitter Score desc then mention count desc. Empty for rows outside the top-2000 targets by period mentions.
- `data[].categories` (array): Account categories: [{id, name}].
- `data[].categories[].id` (integer): Category id.
- `data[].categories[].name` (string): Category name.

## Parameters

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `days` | integer (`1`, `7`, `30`) | no | `7` | Lookback window in days: 1, 7 or 30. Non-numeric falls back to 7; any other number returns success=false with message "Days params is only available: 1\|7\|30". |
| `category_id` | integer | no | `0` | Account category filter: 0 = all accounts, -1 = accounts without a category, otherwise a category id from get_categories. Unknown id returns success=false with message "Category with id=N not found". Non-numeric falls back to 0. |
| `by` | string (`score`, `followers`, `mentions`, `mentioners`) | no | `mentions` | Ranking column: `mentions` = mentions received in the window, `mentioners` = all-time unique mentioners, `score` = Twitter Score, `followers` = follower count. Any other value returns success=false with message "Sorting is only possible by [score\|followers\|mentions\|mentioners]". |
| `sort` | string (`asc`, `desc`, `ascending`, `descending`) | no | `desc` | `asc`/`ascending` (case-insensitive) for ascending; anything else descending. |
| `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` | Rows per page. Clamped to 100; 0 or negative becomes 1; non-numeric falls back to 10. |

## Example request

```bash
curl -s "https://twitterscore.io/api/v1/get_smart_mentions?days=7" \
  -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_smart_mentions",
    params={"days": 7},
    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_smart_mentions?days=7", {
  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": 1000,
  "page": 1,
  "size": 1,
  "pages": 1000,
  "days": 7,
  "category_name": "all",
  "data": [
    {
      "twitter_id": "295218901",
      "username": "VitalikButerin",
      "name": "vitalik.eth",
      "profile_url": "/twitter/VitalikButerin",
      "profile_image": "https://twitterscore.io/media/profiles/VitalikButerin.jpg",
      "blue_verified": true,
      "description": "mi pinxe lo crino tcati",
      "twitter_score": 1000,
      "twitter_score_diff_int": 0,
      "twitter_score_diff_str": "0",
      "current_followers": 5812345,
      "followers_diff_int": 1532,
      "followers_diff_str": "1 532",
      "mentions_total": 184233,
      "mentions_diff_int": 2417,
      "mentions_diff_str": "2 417",
      "unique_mentioners_total": 41208,
      "unique_mentioners_diff_int": 1136,
      "unique_mentioners_diff_str": "1 136",
      "top_mentioner": {
        "name": "Ethereum",
        "username": "ethereum",
        "image": "https://twitterscore.io/media/profiles/ethereum.jpg",
        "score": 912,
        "verified": true
      },
      "mentioners_list": [
        {
          "name": "Ethereum",
          "username": "ethereum",
          "image": "https://twitterscore.io/media/profiles/ethereum.jpg",
          "score": 912,
          "verified": true
        },
        {
          "name": "Coinbase",
          "username": "coinbase",
          "image": "https://twitterscore.io/media/profiles/coinbase.jpg",
          "score": 871,
          "verified": true
        }
      ],
      "categories": [
        {
          "id": 3,
          "name": "Influencers"
        }
      ]
    }
  ]
}
```

## 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`, `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).