# Follower-count change over the last week and last month

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

Returns how much the account's follower count changed over the trailing 7 and 30 days, computed from TwitterScore's daily audience snapshots. For each window the response gives the baseline snapshot date (the oldest snapshot inside the window), the signed numeric difference between the newest and that oldest snapshot, and the same difference pre-formatted as a signed string. With a single snapshot in a window the diff is 0 but date is still that snapshot's date; with no snapshot in the window (including profiles that TwitterScore does not monitor) date is null and diff is 0.

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

- `week.date` (string): Date (YYYY-MM-DD) of the oldest snapshot inside the 7-day window, i.e. the baseline the diff is measured from. null when no snapshot exists in the window.
- `week.diff` (integer): Newest snapshot followers minus baseline snapshot followers; negative when followers were lost; 0 when fewer than two snapshots exist.
- `week.diff_str` (string): diff as a signed string: "+3127", "-45" or "0".
- `month.date` (string): Baseline snapshot date for the 30-day window, or null.
- `month.diff` (integer): Signed follower change over the 30-day window.
- `month.diff_str` (string): diff as a signed string.

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

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

## Example request

```bash
curl -s "https://twitterscore.io/api/v1/get_followers_diff?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_diff",
    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_diff?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,
  "today": "2026-10-03",
  "week": {
    "date": "2026-09-26",
    "diff": 3127,
    "diff_str": "+3127"
  },
  "month": {
    "date": "2026-09-03",
    "diff": 14890,
    "diff_str": "+14890"
  }
}
```

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