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

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 ([email protected])"

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 ([email protected])"},
    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)

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 ([email protected])" },
});
const data = await r.json();
if (data.success === false) throw new Error(data.message);
console.log(data);

Example response

{
  "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 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. Limits: per-minute rate and monthly quota by plan, see Rate limits. Machine-readable definition: /openapi.json.

This page as Markdown.