# Previous usernames (handles) of an account, with the date each rename was detected

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

Returns the handles the account used before its current one, newest first, as detected by TwitterScore's daily scans. Each item is one rename: the handle the account left and `detected_at`, the UTC time our scan noticed the change; the rename itself happened shortly before. Coverage: accounts TwitterScore tracks are followed since 2025-03-13; for accounts it knows only from the follower graph the history is partial. `total: 0` therefore means no rename was detected, not that the handle never changed. `total` counts the detected renames, so a handle the account returned to and left again appears twice. Internal artefacts of TwitterScore's own pipeline (suspension renames, double logging) are filtered out. `username` may also be a previous handle of the account; a handle that another account uses now usually resolves to that account, so query by `twitter_id` to get a specific account's history. The list holds the latest 500 renames.

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

- `previous_usernames[].username` (string): The handle the account left.
- `previous_usernames[].detected_at` (string): When TwitterScore's scan detected the rename, RFC 3339 UTC (e.g. 2026-01-01T22:09:31Z).

## Parameters

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `username` | string | no |  | X/Twitter handle without the leading @ (whitespace/slashes stripped). Also matches the profile slug and previous handles of renamed accounts. |
| `twitter_id` | integer | no |  | Numeric X/Twitter user id. Tried before `username` when both are given. |

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

## Example request

```bash
curl -s "https://twitterscore.io/api/v1/get_username_history?username=KaiDotNow" \
  -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_username_history",
    params={"username": "KaiDotNow"},
    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_username_history?username=KaiDotNow", {
  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,
  "twitter_id": "1019625684153585664",
  "username": "KaiDotNow",
  "total": 1,
  "previous_usernames": [
    {
      "username": "KardiaChain",
      "detected_at": "2026-01-01T22:09:31Z"
    }
  ]
}
```

## 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/); existing integrations that pass `?api_key=` keep working. Limits: per-minute rate and monthly quota by plan, see [Rate limits](/developers/rate-limits/). Machine-readable definition: [/openapi.json](/openapi.json).