# Daily follower-count snapshots for an account over a period

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

Returns the account's follower count per day for the chosen period, newest day first, paginated. Each item is one daily snapshot taken when TwitterScore scanned the account's audience; days without a scan are skipped, so total reflects the number of snapshots actually stored, not the number of calendar days in the period. Use period=all together with page to walk the full history. Only accounts that TwitterScore monitors have snapshots: for a profile known only as a follower (not monitored) the list is empty with total 0.

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

- `followers_count[].date` (string): Snapshot date in YYYY-MM-DD.
- `followers_count[].followers_count` (integer): Follower count recorded on that date.

## Parameters

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `username` | string | no |  | X/Twitter handle of the account, 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. |
| `period` | string (`3d`, `7d`, `1w`, `30d`, `1m`, `180d`, `6m`, `365d`, `1y`, `all`) | no | `30d` | Look-back window, case-insensitive. 3d=3 days, 7d/1w=7 days, 30d/1m=30 days, 180d/6m=180 days, 365d/1y=365 days, all=entire stored history. The window covers today and the previous N-1 days (N calendar days inclusive). Any unrecognised value (including 360d mentioned in the public docs) silently falls back to 30 days. |
| `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 | `30` | Snapshots per page, capped at 30. Non-numeric values fall back to 30; 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/followers_count_history?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/followers_count_history",
    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/followers_count_history?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": 3,
  "page": 1,
  "size": 3,
  "pages": 1,
  "followers_count": [
    {
      "date": "2026-10-03",
      "followers_count": 5812344
    },
    {
      "date": "2026-10-02",
      "followers_count": 5811902
    },
    {
      "date": "2026-10-01",
      "followers_count": 5811475
    }
  ]
}
```

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