# Accounts ranked by smart-follower momentum (Smart Follows page) over 1, 7 or 30 days

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

Returns the ranked list behind the Smart Follows page (formerly "Alpha"): non-suspended accounts that are followed by at least one "smart" account in the chosen bucket, with how many smart followers they have in total, how many of those (re)followed them during the window, and — as the default sort key — the change in that new-follower count versus the previous window. Buckets select which smart-follower set is counted: `all`, `vc` (venture capitals), `inf` (influencers) or `angels`. Default ranking is `by=alpha` descending: the accounts gaining the most new smart followers compared with the previous period come first; `sort=asc` flips it to show accounts losing smart-follower momentum. `by=score` and `by=followers` rank by the account's current Twitter Score and follower count instead. Ties are broken by current Twitter Score (descending) and duplicate usernames are collapsed. Rows are read from a daily pre-computed, ranked slice of at most 1000 rows, so `total` never exceeds 1000. Each row also carries a short list of the account's most notable smart followers (`top_alpha_followers`) for display as an avatar stack. The response echoes the applied `days` and `bucket`.
**Nested fields**

- `data[].twitter_id` (string): Account's numeric Twitter/X id as a string (empty string if missing).
- `data[].username` (string): Handle without the @.
- `data[].name` (string): Display name; falls back to the username when empty.
- `data[].profile_url` (string): Relative TwitterScore profile path, "/twitter/{slug}" (slug falls back to username; "#" when both are empty). Prefix with https://twitterscore.io.
- `data[].profile_image` (string): Avatar URL: the TwitterScore S3 copy (aws_image_url), else the original Twitter image URL (tw_image_url), else null.
- `data[].blue_verified` (boolean): Whether the account has X Premium (blue) verification.
- `data[].description` (string): Profile bio (empty string when none).
- `data[].twitter_score` (integer): Current Twitter Score (0-1000), integer.
- `data[].twitter_score_diff` (integer): Twitter Score change over the window (period snapshot score_diff); 0 when the account has no period snapshot.
- `data[].current_followers` (integer): Current follower count.
- `data[].followers_diff` (integer): current_followers minus followers at the start of the window; may be negative.
- `data[].total_alpha_followers` (integer): Number of currently active smart followers in the selected bucket (always > 0 — the view excludes rows with zero).
- `data[].new_alpha_followers_diff` (integer): Number of smart followers from the bucket that (re)followed the account during the window (new_alpha_followers_count). Note: this is the period count, not the versus-previous-period delta (new_diff) that `by=alpha` sorts on; new_diff itself is not exposed.
- `data[].top_alpha_followers` (array): Short list of notable smart followers for display (avatar stack); empty array when none. Entries without a name/username are dropped.
- `data[].top_alpha_followers[].name` (string): Follower's display name (falls back to username).
- `data[].top_alpha_followers[].username` (string): Follower's handle (may be empty string).
- `data[].top_alpha_followers[].image` (string): Follower's avatar URL (empty string when none).
- `data[].top_alpha_followers[].score` (integer): Follower's Twitter Score, rounded to an integer.
- `data[].top_alpha_followers[].verified` (boolean): Follower's blue-verified flag.

## Parameters

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `days` | integer (`1`, `7`, `30`) | no | `7` | Period window in days: 1, 7 or 30. Any other integer returns {"success": false, "message": "Days param is only available: 1\|7\|30"}; a non-numeric value falls back to 7. |
| `by` | string (`alpha`, `score`, `followers`) | no | `alpha` | Ranking column: `alpha` = change in the number of new smart followers versus the previous period (internal column new_diff), `score` = current Twitter Score (current_project_score), `followers` = current follower count (current_followers). Case-sensitive; any other value returns {"success": false, "message": "Sorting is only possible by [score\|followers\|alpha]"}. |
| `sort` | string (`desc`, `asc`, `descending`, `ascending`) | no | `desc` | Sort direction: `asc` or `ascending` (case-insensitive) for ascending, anything else (including the default) for descending. |
| `bucket` | string (`all`, `vc`, `inf`, `angels`) | no | `all` | Which smart-follower set is counted: `all`, `vc` (venture capitals), `inf` (influencers) or `angels`. Case-insensitive, whitespace trimmed; unknown values silently fall back to `all` (no error). |
| `page` | integer | no | `1` | 1-based page number. Non-numeric, 0 or negative values are treated as 1; a page past the last returns an empty `data` array. |
| `size` | integer | no | `10` | Rows per page, capped at 100. Values below 1 are treated as 1; a non-numeric value falls back to 10. |

## Example request

```bash
curl -s "https://twitterscore.io/api/v1/get_smart_follows?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_follows",
    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_follows?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,
  "bucket": "all",
  "data": [
    {
      "twitter_id": "295218901",
      "username": "VitalikButerin",
      "name": "vitalik.eth",
      "profile_url": "/twitter/VitalikButerin",
      "profile_image": "https://twitterscore.s3.amazonaws.com/profiles/VitalikButerin.jpg",
      "blue_verified": true,
      "description": "mi pinxe lo crino tcati",
      "twitter_score": 1000,
      "twitter_score_diff": 0,
      "current_followers": 5812345,
      "followers_diff": 14135,
      "total_alpha_followers": 2417,
      "new_alpha_followers_diff": 36,
      "top_alpha_followers": [
        {
          "name": "Balaji",
          "username": "balajis",
          "image": "https://twitterscore.s3.amazonaws.com/profiles/balajis.jpg",
          "score": 942,
          "verified": true
        },
        {
          "name": "Hasu",
          "username": "hasufl",
          "image": "https://twitterscore.s3.amazonaws.com/profiles/hasufl.jpg",
          "score": 611,
          "verified": false
        }
      ]
    }
  ]
}
```

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