# Paginated list of an account's smart followers, filterable by category, tag or tag-category.

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

Returns the accounts in TwitterScore's monitored ("smart") set that currently follow the target account, one page at a time. Identify the target by `username` or `twitter_id`. Each row is a follower profile with its Twitter Score, follower count, tags, categories and `subscribed_at` (when TwitterScore first recorded the follow). Rows can be narrowed to followers that carry a given category (`category_id`), tag (`tag_id`) or whose tags belong to a given tag-category (`tag_category_id`); several filters combine with AND. Sorting is by Twitter Score (default), by follower count or by `subscribed_at`, descending unless `sort=asc`. Note the data key is `top_followers` (legacy name) and the page size is capped at 25. Only followers that are active, not suspended and on TwitterScore monitoring are counted; the raw X follower list is not exposed. The filter ids are passed straight to the database lookup, so a non-numeric value (e.g. `tag_id=abc`) is not rejected as a parameter error but surfaces as `server_error` ("Unexpected error [...]").

**Required:** one of `username`, `twitter_id`.
**Nested fields**

- `top_followers[].twitter_id` (string): Follower's X user id, as a string (ids exceed 2^53).
- `top_followers[].username` (string): Follower's X handle.
- `top_followers[].name` (string): Follower's display name.
- `top_followers[].description` (string): Follower's X bio (may be empty string).
- `top_followers[].twitter_score` (number): Follower's Twitter Score on the 0-1000 scale (stored as float).
- `top_followers[].followers_count` (integer): Follower's own current X follower count.
- `top_followers[].profile_image` (string): URL of the follower's avatar hosted by TwitterScore (ImageField .url), or null.
- `top_followers[].tags` (array): Tags attached to the follower.
- `top_followers[].tags[].id` (integer): Tag id.
- `top_followers[].tags[].name` (string): Tag name.
- `top_followers[].categories` (array): Account categories attached to the follower.
- `top_followers[].categories[].id` (integer): Category id.
- `top_followers[].categories[].name` (string): Category name.
- `top_followers[].subscribed_at` (string): ISO 8601 UTC datetime with millisecond precision and Z suffix (e.g. 2023-04-18T09:12:44.318Z; Django JSON encoder) when TwitterScore first recorded this follow. Not the real follow date on X.

## Parameters

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `username` | string | no |  | X handle of the target account (with or without @, trailing slash and surrounding whitespace tolerated). Resolved against current username, then slug, then previous usernames. Either `username` or `twitter_id` is required. |
| `twitter_id` | integer | no |  | Numeric X user id of the target account. Looked up first when both are given; if no account has this id the lookup falls back to `username`. |
| `page` | integer | no | `1` | 1-based page number. Non-numeric, 0 or negative falls back to 1; a page past the last one returns an empty list. |
| `size` | integer | no | `10` | Rows per page. Values above 25 are clamped to 25; 0 or negative becomes 1; non-numeric falls back to 10. |
| `by` | string (`score`, `followers`, `subscribed_at`) | no | `score` | Sort column. `score` = follower's Twitter Score, `followers` = follower's own follower count, `subscribed_at` = when TwitterScore first saw the follow. Any other value returns success=false with message "Sorting is only possible by [followers\|score\|subscribed_at]". |
| `sort` | string (`asc`, `desc`, `ascending`, `descending`) | no | `desc` | Sort direction. `asc`/`ascending` (case-insensitive) for ascending; anything else is descending. |
| `category_id` | integer | no |  | Keep only followers that have this account category (id from get_categories). Non-numeric value → server_error. |
| `tag_id` | integer | no |  | Keep only followers that carry this tag (id from get_tags). Non-numeric value → server_error. |
| `tag_category_id` | integer | no |  | Keep only followers that carry at least one tag belonging to 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_followers?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_followers",
    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_followers?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": 4821,
  "page": 1,
  "size": 2,
  "pages": 2411,
  "top_followers": [
    {
      "twitter_id": "295218901",
      "username": "VitalikButerin",
      "name": "vitalik.eth",
      "description": "mi pinxe lo crino tcati",
      "twitter_score": 1000,
      "followers_count": 5812345,
      "profile_image": "https://twitterscore.io/media/profiles/VitalikButerin.jpg",
      "tags": [
        {
          "id": 11,
          "name": "Ethereum"
        }
      ],
      "categories": [
        {
          "id": 3,
          "name": "Influencers"
        }
      ],
      "subscribed_at": "2023-04-18T09:12:44.318Z"
    },
    {
      "twitter_id": "2312333412",
      "username": "ethereum",
      "name": "Ethereum",
      "description": "Ethereum is a global, open-source platform for decentralized applications.",
      "twitter_score": 912,
      "followers_count": 3654210,
      "profile_image": "https://twitterscore.io/media/profiles/ethereum.jpg",
      "tags": [
        {
          "id": 11,
          "name": "Ethereum"
        }
      ],
      "categories": [
        {
          "id": 1,
          "name": "Projects"
        }
      ],
      "subscribed_at": "2022-11-02T17:40:05.002Z"
    }
  ]
}
```

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