# Paginated list of an account's followers ranked by Twitter Score

> **Deprecated.** This route is kept for existing clients; new integrations should use the replacement named in the description.

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

Returns the monitored followers of a profile, highest Twitter Score first, in pages. Each entry carries the follower's score, follower count, description, tags, categories and the date TwitterScore first recorded the follow. The follower set is the same as get_twitter_top_followers (active, non-suspended monitored accounts with an active follow relationship), but without the 5-entry cap. Deprecated in the public docs in favour of get_followers, which offers the same data with filters.

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

- `top_followers[].twitter_id` (string): Follower's numeric X id as a string (safe for 64-bit ids).
- `top_followers[].username` (string): Follower's handle without @.
- `top_followers[].name` (string): Follower's display name.
- `top_followers[].description` (string): Follower's profile bio (empty string when none).
- `top_followers[].twitter_score` (number): Follower's Twitter Score on the 0–1000 scale.
- `top_followers[].followers_count` (integer): Follower's own current follower count.
- `top_followers[].profile_image` (string): Absolute URL of the follower's stored profile picture, or null.
- `top_followers[].tags` (array): Tags assigned to the follower by TwitterScore (e.g. Tier 1 VC).
- `top_followers[].tags[].id` (integer): Tag id (matches get_tags).
- `top_followers[].tags[].name` (string): Tag name.
- `top_followers[].categories` (array): Categories assigned to the follower (e.g. Projects, Influencers).
- `top_followers[].categories[].id` (integer): Category id (matches get_categories).
- `top_followers[].categories[].name` (string): Category name.
- `top_followers[].subscribed_at` (string): ISO 8601 UTC datetime when TwitterScore first recorded this follow relationship. This is the detection time in TwitterScore's database, not the moment the follow happened on X.

## Parameters

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `username` | string | no |  | X/Twitter handle of the account whose followers to list, without the leading @. Surrounding whitespace and a trailing slash are tolerated; renamed handles are resolved via previous-username history. |
| `twitter_id` | integer | no |  | Numeric X/Twitter user id of the account. Tried first when both are sent; falls back to username if the id resolves nothing. |
| `page` | integer | no | `1` | 1-based page number. Non-numeric, 0 or negative values are treated as 1. A page beyond the last returns an empty list with the same metadata. |
| `size` | integer | no | `5` | Items per page, capped at 25. Non-numeric values fall back to 5; 0 or negative values are floored to 1. |

At least one of `username`, `twitter_id` is required.

## Example request

```bash
curl -s "https://twitterscore.io/api/v1/top_followers_paginate?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/top_followers_paginate",
    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/top_followers_paginate?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": 48213,
  "page": 1,
  "size": 2,
  "pages": 24107,
  "top_followers": [
    {
      "twitter_id": "44196397",
      "username": "elonmusk",
      "name": "Elon Musk",
      "description": "",
      "twitter_score": 998.6,
      "followers_count": 221574312,
      "profile_image": "https://twitterscore.s3.amazonaws.com/media/profiles/elonmusk.jpg",
      "tags": [
        {
          "id": 7,
          "name": "Key Opinion Leader"
        }
      ],
      "categories": [
        {
          "id": 2,
          "name": "Influencers"
        }
      ],
      "subscribed_at": "2022-11-14T03:21:08.512Z"
    },
    {
      "twitter_id": "902926941413453824",
      "username": "cz_binance",
      "name": "CZ BNB",
      "description": "Co-Founder & Former CEO @binance",
      "twitter_score": 981.2,
      "followers_count": 10215733,
      "profile_image": "https://twitterscore.s3.amazonaws.com/media/profiles/cz_binance.jpg",
      "tags": [
        {
          "id": 3,
          "name": "CEX"
        }
      ],
      "categories": [
        {
          "id": 5,
          "name": "Founders"
        },
        {
          "id": 2,
          "name": "Influencers"
        }
      ],
      "subscribed_at": "2021-06-02T19:44:51.003Z"
    }
  ]
}
```

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