# Monitored accounts that followed or unfollowed a given account (follow/unfollow log, incoming)

`GET https://twitterscore.io/api/v1/friendshipHistory/followed`

Returns the incoming follow activity of one account: every recorded event where a TwitterScore-monitored account followed (`action: "Followed"`) or unfollowed (`action: "Unfollowed"`) it, newest first, with the follower's profile summary, Twitter Score, follower count, tags, categories and the event date. Identify the account by `username` or `twitter_id`. Only followers that are active, non-suspended accounts under TwitterScore monitoring are included — this is the "who in the crypto graph followed X" view, not a complete follower log. Narrow to one day with `date` (YYYY-MM-DD), or to followers carrying given tags / categories with comma-separated `tag_ids` / `category_ids` (ids from get_tags_list / get_categories_list). Pages hold at most 25 rows.

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

- `data[].action` (string): "Followed" when the follower followed the account, "Unfollowed" when it unfollowed.
- `data[].twitter_id` (string): Follower's numeric Twitter/X id as a string.
- `data[].username` (string): Follower's handle.
- `data[].name` (string): Follower's display name.
- `data[].twitter_score` (number): Follower's current Twitter Score (0-1000 scale) as a float (Account.project_score FloatField, may have decimals).
- `data[].followers_count` (integer): Follower's current follower count (current, not historical).
- `data[].description` (string): Follower's bio (empty string when none).
- `data[].profile_image` (string): Follower's avatar URL from the stored S3 profile image (https://<bucket>.s3.amazonaws.com/profiles/<file>), or null when no image is stored.
- `data[].tags` (array): Tags of the follower; empty array when none.
- `data[].tags[].id` (integer): Tag id.
- `data[].tags[].name` (string): Tag name.
- `data[].categories` (array): Account categories of the follower; empty array when none.
- `data[].categories[].id` (integer): Category id.
- `data[].categories[].name` (string): Category name.
- `data[].created_at` (string): Date of the follow/unfollow event, YYYY-MM-DD.

## Parameters

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `username` | string | no |  | Handle of the account whose incoming follows to list (surrounding whitespace and trailing slash tolerated). Resolved against current usernames/slugs first, then against previous usernames (renamed accounts). Required unless `twitter_id` is given. |
| `twitter_id` | integer | no |  | Numeric Twitter/X id of the account. Takes precedence over `username` when both are given. Required unless `username` is given. |
| `date` | string | no |  | Only events on this calendar day, format YYYY-MM-DD (date part of the recorded action timestamp). Any other format returns {"success": false, "message": "Invalid date format. Use YYYY-MM-DD."}. |
| `tag_ids` | string | no |  | Comma-separated tag ids (see /api/v1/get_tags_list); only events whose follower carries at least one of these tags are returned. If any element is non-numeric the whole list is ignored (no filter); empty elements are skipped. A follower matching several of the ids can appear as duplicate rows (no DISTINCT). |
| `category_ids` | string | no |  | Comma-separated account-category ids (see /api/v1/get_categories_list); only events whose follower is in at least one of these categories are returned. A list with a non-numeric element is ignored. Same duplicate-row caveat as tag_ids. |
| `page` | integer | no | `1` | 1-based page number. Non-numeric, 0 or negative values are treated as 1; a page past the last returns an empty `data` array. |
| `size` | integer | no | `10` | Rows per page, capped at 25. Values below 1 are treated as 1; a non-numeric value falls back to 10. |

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

## Example request

```bash
curl -s "https://twitterscore.io/api/v1/friendshipHistory/followed?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/friendshipHistory/followed",
    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/friendshipHistory/followed?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": 2318,
  "page": 1,
  "size": 2,
  "pages": 1159,
  "data": [
    {
      "action": "Followed",
      "twitter_id": "1138033434",
      "username": "paradigm",
      "name": "Paradigm",
      "twitter_score": 884.21,
      "followers_count": 251340,
      "description": "Research-driven crypto investment firm.",
      "profile_image": "https://twitterscore.s3.amazonaws.com/profiles/paradigm.jpg",
      "tags": [
        {
          "id": 4,
          "name": "VC"
        }
      ],
      "categories": [
        {
          "id": 2,
          "name": "Venture Capitals"
        }
      ],
      "created_at": "2026-10-01"
    },
    {
      "action": "Unfollowed",
      "twitter_id": "44196397",
      "username": "elonmusk",
      "name": "Elon Musk",
      "twitter_score": 1000.0,
      "followers_count": 221504311,
      "description": "",
      "profile_image": null,
      "tags": [],
      "categories": [
        {
          "id": 3,
          "name": "Influencers"
        }
      ],
      "created_at": "2026-09-30"
    }
  ]
}
```

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