API Usage Examples

Learn how you can use the TwitterScore API.

You can use either username or twitter id in any query.

1. Get Twitter Score.

https://twitterscore.io/api/v1/get_twitter_score?api_key=API_KEY&username=elonmusk

Answer example:

{
  "success": true,
  "username": "elonmusk",
  "twitter_id": "44196397",
  "twitter_score": 1000
}

---

1. Twitter Score bulk check.

https://twitterscore.io/api/v1/bulk_scores_check?api_key=API_KEY&ids=IDS&size=50

Parameters:
1. username (or twitter_id) - compulsory
2. api_key - compulsory
3. size (number of returned items in the list) – default = 10, max = 50
4. page (page number) - default = 1

Answer example:

{
  "success": true,
  "total": 2,
  "page": 1,
  "size": 2,
  "pages": 1,
  "data": [
    {
      "twitter_id": "44196397",
      "username": "elonmusk",
      "twitter_url": "https://x.com/elonmusk",
      "twitter_score": 1000.0
    },
    {
      "twitter_id": "295218901",
      "username": "VitalikButerin",
      "twitter_url": "https://x.com/VitalikButerin",
      "twitter_score": 1000.0
    }
  ]
}

---

1. Get account info.

https://twitterscore.io/api/v1/get_twitter_info?api_key=API_KEY&twitter_id=44196397

Answer example:

{
  "success": true,
  "username": "elonmusk",
  "name": "Elon Musk",
  "description": "https://t.co/dDtDyVssfm",
  "followers_count": 240113071,
  "profile_image": "...",
  "tags": [],
  "categories": [
    {"category_id": 2, "category_name": "Founders"},
    {"category_id": 8, "category_name": "Influencers"}
  ]
}

---

1. Get how much score changed for a week/month.

https://twitterscore.io/api/v1/get_twitter_scores_diff?api_key=API_KEY&twitter_id=1492434155405287424

Answer example:

{
  "success": true,
  "today": "2026-05-25",
  "week": {
    "date": "2026-05-18",
    "diff": 0,
    "diff_str": "0"
  },
  "month": {
    "date": "2026-04-25",
    "diff": -3,
    "diff_str": "-3"
  }
}

---

1. Get how much followers count changed for a week / month.

https://twitterscore.io/api/v1/get_followers_diff?api_key=API_KEY&twitter_id=1492434155405287424

Answer example:

{
  "success": true,
  "today": "2026-05-25",
  "week": {
    "date": "2026-05-18",
    "diff": -48,
    "diff_str": "-48"
  },
  "month": {
    "date": "2026-04-25",
    "diff": 39,
    "diff_str": "+39"
  }
}

---

1. Get history of followers count (for 3 / 7 / 30 / 180 / 360 / all days).

Default - 30 days

https://twitterscore.io/api/v1/followers_count_history?api_key=API_KEY&twitter_id=1492434155405287424

Answer example:

{
  "success": true,
  "total": 22,
  "page": 1,
  "size": 22,
  "pages": 1,
  "followers_count": [
    {"date": "2026-05-25", "followers_count": 54962},
    {"date": "2026-05-24", "followers_count": 54956},
    {"date": "2026-05-22", "followers_count": 54975},
    {"date": "2026-05-20", "followers_count": 54987},
    {"date": "2026-05-19", "followers_count": 55001},
    {"date": "2026-05-18", "followers_count": 55010},
    {"date": "2026-05-17", "followers_count": 55020},
    {"date": "2026-05-16", "followers_count": 55024},
    {"date": "2026-05-15", "followers_count": 55044},
    {"date": "2026-05-14", "followers_count": 55048},
    {"date": "2026-05-13", "followers_count": 55046},
    {"date": "2026-05-08", "followers_count": 55095},
    {"date": "2026-05-05", "followers_count": 55114},
    {"date": "2026-05-04", "followers_count": 55119},
    {"date": "2026-05-03", "followers_count": 55116},
    {"date": "2026-05-02", "followers_count": 55128},
    {"date": "2026-05-01", "followers_count": 55124},
    {"date": "2026-04-30", "followers_count": 55135},
    {"date": "2026-04-29", "followers_count": 55143},
    {"date": "2026-04-28", "followers_count": 55109},
    {"date": "2026-04-27", "followers_count": 55109},
    {"date": "2026-04-26", "followers_count": 55027}
  ]
}

Note: • total reflects actual datapoints returned, not the requested period. Days without a snapshot are skipped (e.g. weekends, low-activity accounts). Client charts should handle gaps. • followers_count may decrease — account losing subscribers is a normal case, not an error.

Custom - 3/7/30/180/360/all days

https://twitterscore.io/api/v1/followers_count_history?api_key=API_KEY&twitter_id=44196397&period=3d

Period values:
3 days = 3d
7 days = 7d or 1w
30 days = 30d or 1m
180 days = 180d or 6m
365 days = 365d or 1y
all time = all

Answer example:

{
  "success": true,
  "total": 3,
  "page": 1,
  "size": 3,
  "pages": 1,
  "followers_count": [
    {
      "date": "2024-10-03",
      "followers_count": 199987720
    },
    {
      "date": "2024-10-02",
      "followers_count": 199881491
    },
    {
      "date": "2024-10-01",
      "followers_count": 199725509
    }
  ]
}

---

1. Get list of all categories

https://twitterscore.io/api/v1/get_categories?api_key=API_KEY

Answer example:

{
  "success": true,
  "total": 8,
  "page": 1,
  "size": 8,
  "pages": 1,
  "categories": [
    {"id": 1, "name": "Venture Capitals"},
    {"id": 2, "name": "Founders"},
    {"id": 3, "name": "Projects"},
    {"id": 4, "name": "Exchanges"},
    {"id": 5, "name": "Auditors"},
    {"id": 7, "name": "Media"},
    {"id": 8, "name": "Influencers"},
    {"id": 9, "name": "Angels"}
  ]
}

---

1. Get list of all tags and tag's category

https://twitterscore.io/api/v1/get_tags?api_key=API_KEY&size=3&page=1

Parameters:
1. api_key - compulsory
2. size (number of returned items in the list) – default = 10, max = 25
3. page - default = 1

Answer example:

{
  "success": true,
  "total": 56,
  "page": 1,
  "size": 3,
  "pages": 19,
  "tags": [
    {
      "id": 1,
      "name": "a16z",
      "tag_categories": [
        {"id": 1, "name": "Tier 1 VC"}
      ]
    },
    {
      "id": 2,
      "name": "Coinbase Ventures",
      "tag_categories": [
        {"id": 1, "name": "Tier 1 VC"}
      ]
    },
    {
      "id": 3,
      "name": "Paradigm",
      "tag_categories": [
        {"id": 1, "name": "Tier 1 VC"}
      ]
    }
  ]
}

---

1. Get number of followers in each category

https://twitterscore.io/api/v1/get_categorized_followers_count?twitter_id=44196397&api_key=API_KEY

Answer example:

{
  "success": true,
  "categories": [
    {"name": "All", "cnt": 19995, "id": null},
    {"name": "Projects", "id": 3, "cnt": 3593},
    {"name": "Venture Capitals", "id": 1, "cnt": 698},
    {"name": "Influencers", "id": 8, "cnt": 4366},
    {"name": "Founders", "id": 2, "cnt": 6174},
    {"name": "Angels", "id": 9, "cnt": 949},
    {"name": "Media", "id": 7, "cnt": 276},
    {"name": "Exchanges", "id": 4, "cnt": 77},
    {"name": "Auditors", "id": 5, "cnt": 4},
    {"name": "NoCategory", "id": 0, "cnt": 5274}
  ]
}

---

1. Get the number of tagged subscribers in each category

https://twitterscore.io/api/v1/get_tagged_followers_count?api_key=API_KEY&twitter_id=44196397

Answer example:

{
  "success": true,
  "data": [
    {
      "tag_category_id": 1,
      "tag_category_name": "Tier 1 VC",
      "tags": [
        {"tag_id": 1, "tag_name": "a16z", "cnt": 74},
        {"tag_id": 2, "tag_name": "Coinbase Ventures", "cnt": 48},
        {"tag_id": 11, "tag_name": "Binance", "cnt": 34},
        {"tag_id": 25, "tag_name": "Dragonfly Capital", "cnt": 19},
        {"tag_id": 4, "tag_name": "Sequoia", "cnt": 18},
        {"tag_id": 3, "tag_name": "Paradigm", "cnt": 17},
        {"tag_id": 71, "tag_name": "YZi Labs", "cnt": 11},
        {"tag_id": 66, "tag_name": "ConsenSys", "cnt": 10},
        {"tag_id": 7, "tag_name": "Delphi", "cnt": 10},
        {"tag_id": 15, "tag_name": "Pantera Capital", "cnt": 10},
        {"tag_id": 68, "tag_name": "Y Combinator", "cnt": 10},
        {"tag_id": 5, "tag_name": "Multicoin Capital", "cnt": 9},
        {"tag_id": 69, "tag_name": "BlackRock", "cnt": 8},
        {"tag_id": 10, "tag_name": "Blockchain Capital", "cnt": 6},
        {"tag_id": 24, "tag_name": "Galaxy", "cnt": 6},
        {"tag_id": 65, "tag_name": "HashKey Capital", "cnt": 5},
        {"tag_id": 67, "tag_name": "VanEck", "cnt": 5},
        {"tag_id": 9, "tag_name": "Polychain", "cnt": 3}
      ]
    },
    {
      "tag_category_id": 2,
      "tag_category_name": "Tier 2 VC",
      "tags": [
        {"tag_id": 14, "tag_name": "CoinFund", "cnt": 9},
        {"tag_id": 23, "tag_name": "Electric Capital", "cnt": 8},
        {"tag_id": 32, "tag_name": "Fabric Ventures", "cnt": 8},
        {"tag_id": 31, "tag_name": "IOSG Ventures", "cnt": 8},
        {"tag_id": 35, "tag_name": "Jump Capital", "cnt": 8},
        {"tag_id": 30, "tag_name": "YGG Ventures", "cnt": 8},
        {"tag_id": 40, "tag_name": "Variant", "cnt": 7},
        {"tag_id": 16, "tag_name": "Arrington Capital", "cnt": 6},
        {"tag_id": 43, "tag_name": "HTX Ventures", "cnt": 6},
        {"tag_id": 39, "tag_name": "Ryze Labs", "cnt": 6},
        {"tag_id": 57, "tag_name": "IDEO Ventures", "cnt": 5},
        {"tag_id": 26, "tag_name": "Mechanism Capital", "cnt": 5},
        {"tag_id": 37, "tag_name": "ParaFi Capital", "cnt": 5},
        {"tag_id": 29, "tag_name": "Sfermion", "cnt": 5},
        {"tag_id": 47, "tag_name": "The Spartan Group", "cnt": 5},
        {"tag_id": 28, "tag_name": "Tribe Capital", "cnt": 5},
        {"tag_id": 27, "tag_name": "eGirl Capital", "cnt": 5},
        {"tag_id": 36, "tag_name": "CMS Holdings", "cnt": 4},
        {"tag_id": 46, "tag_name": "OKX Ventures", "cnt": 4},
        {"tag_id": 12, "tag_name": "Solana Ventures", "cnt": 4},
        {"tag_id": 41, "tag_name": "Union Square Ventures", "cnt": 4},
        {"tag_id": 48, "tag_name": "Hypersphere", "cnt": 2},
        {"tag_id": 70, "tag_name": "SamsungNext", "cnt": 2},
        {"tag_id": 38, "tag_name": "Bitscale Capital", "cnt": 1}
      ]
    },
    {
      "tag_category_id": 3,
      "tag_category_name": "Ecosystems",
      "tags": [
        {"tag_id": 22, "tag_name": "Ethereum", "cnt": 98},
        {"tag_id": 13, "tag_name": "Solana", "cnt": 87}
      ]
    },
    {
      "tag_category_id": 4,
      "tag_category_name": "Other",
      "tags": [
        {"tag_id": 6, "tag_name": "NFT", "cnt": 936},
        {"tag_id": 62, "tag_name": "Meme", "cnt": 30},
        {"tag_id": 63, "tag_name": "Chinese", "cnt": 17},
        {"tag_id": 8, "tag_name": "Animoca Brands", "cnt": 12},
        {"tag_id": 19, "tag_name": "FTX", "cnt": 10},
        {"tag_id": 42, "tag_name": "Social Capital", "cnt": 8},
        {"tag_id": 44, "tag_name": "Winklevoss Capital", "cnt": 5},
        {"tag_id": 61, "tag_name": "Lemniscap", "cnt": 3},
        {"tag_id": 45, "tag_name": "Not3Lau Capital", "cnt": 3},
        {"tag_id": 64, "tag_name": "Korean", "cnt": 2},
        {"tag_id": 49, "tag_name": "Metapurse", "cnt": 2},
        {"tag_id": 34, "tag_name": "Republic Capital", "cnt": 2}
      ]
    }
  ]
}

---

1. Get paginated list of followers (filtered by size, tag, category, tag 's category).

https://twitterscore.io/api/v1/get_followers?api_key=API_KEY&twitter_id=44196397

Parameters:
1. username (or twitter_id) - compulsory
2. api_key - compulsory
3. category_id - you can filter followers by category id
4. tag_id - you can filter followers by tag id
5. tag_category_id - you can filter followers by tag category id
6. size (number of returned items in the list) – default = 10, max = 25
7. page - default = 1

Get top 3 followers

https://twitterscore.io/api/v1/get_followers?api_key=API_KEY&twitter_id=44196397&size=3

Answer example:

{
  "success": true,
  "total": 19584,
  "page": 1,
  "size": 3,
  "pages": 6528,
  "top_followers": [
    {
      "twitter_id": "5943622",
      "username": "pmarca",
      "name": "Marc Andreessen 🇺🇸",
      "description": "You're not talking to someone who woke up a loser. That loser attitude, that loser premise makes no sense to me.",
      "twitter_score": 1000.0,
      "followers_count": 3054319,
      "profile_image": "https://twitterscore.s3.amazonaws.com/media/profiles/5943622.jpg",
      "tags": [
        {"id": 1, "name": "a16z"}
      ],
      "categories": [
        {"id": 2, "name": "Founders"},
        {"id": 9, "name": "Angels"}
      ],
      "subscribed_at": "2021-08-06T09:02:57.858Z"
    },
    {
      "twitter_id": "18876842",
      "username": "jessepollak",
      "name": "jesse.base.eth",
      "description": "@base builder #001 | DM @jessexbt_ai to get building",
      "twitter_score": 1000.0,
      "followers_count": 352911,
      "profile_image": "https://twitterscore.s3.amazonaws.com/media/profiles/18876842.jpg",
      "tags": [
        {"id": 2, "name": "Coinbase Ventures"}
      ],
      "categories": [
        {"id": 9, "name": "Angels"}
      ],
      "subscribed_at": "2021-09-06T14:38:32.655Z"
    },
    {
      "twitter_id": "636513296",
      "username": "nikitabier",
      "name": "Nikita Bier",
      "description": "head of product @x, advisor @solana, venture partner @lightspeedvp, ex-founder @gasappteam (acq by discord), ex-founder @thetbhapp (acq by facebook)",
      "twitter_score": 1000.0,
      "followers_count": 1074399,
      "profile_image": "https://twitterscore.s3.amazonaws.com/media/profiles/636513296.jpg",
      "tags": [],
      "categories": [
        {"id": 2, "name": "Founders"},
        {"id": 9, "name": "Angels"}
      ],
      "subscribed_at": "2021-09-06T13:28:06.269Z"
    }
  ]
}

Get followers from category "Founders"

https://twitterscore.io/api/v1/get_followers?api_key=API_KEY&twitter_id=44196397&category_id=2&size=2

Answer example:

{
  "success": true,
  "total": 6113,
  "page": 1,
  "size": 2,
  "pages": 3057,
  "top_followers": [
    {
      "twitter_id": "26377478",
      "username": "laurashin",
      "name": "Laura Shin",
      "description": "Crypto journalist 🎧 Host @unchained_pod 📚 Author, The Cryptopians 💌 Sign up https://t.co/gf90Q5GrXy Ads [e-mail]",
      "twitter_score": 1000.0,
      "followers_count": 286056,
      "profile_image": "https://twitterscore.s3.amazonaws.com/media/profiles/26377478.png",
      "tags": [
        {"id": 6, "name": "NFT"}
      ],
      "categories": [
        {"id": 2, "name": "Founders"},
        {"id": 8, "name": "Influencers"}
      ],
      "subscribed_at": "2021-08-22T21:04:58.190Z"
    },
    {
      "twitter_id": "902926941413453824",
      "username": "cz_binance",
      "name": "CZ 🔶 BNB",
      "description": "Buy the book (proceeds go to charity):\nEnglish: https://t.co/UxgYxYJ3NF\nChinese: https://t.co/ItFd8FEyuK \n\n@binance\n@BNBchain\n@YZiLabs\n@GiggleAcademy",
      "twitter_score": 1000.0,
      "followers_count": 11411794,
      "profile_image": "https://twitterscore.s3.amazonaws.com/media/profiles/902926941413453824.jpg",
      "tags": [
        {"id": 11, "name": "Binance"}
      ],
      "categories": [
        {"id": 2, "name": "Founders"}
      ],
      "subscribed_at": "2021-11-24T07:21:44.634Z"
    }
  ]
}

Get followers with tag "Coinbase Ventures"

https://twitterscore.io/api/v1/get_followers?api_key=API_KEY&twitter_id=44196397&tag_id=2&size=2

Answer example:

{
  "success": true,
  "total": 48,
  "page": 1,
  "size": 2,
  "pages": 24,
  "top_followers": [
    {
      "twitter_id": "14379660",
      "username": "brian_armstrong",
      "name": "Brian Armstrong",
      "description": "Co-founder & CEO at @Coinbase. Creating more economic freedom in the world. ENS: barmstrong.eth Co-founder @researchhub @newlimit",
      "twitter_score": 1000.0,
      "followers_count": 2322709,
      "profile_image": "https://twitterscore.s3.amazonaws.com/media/profiles/14379660.png",
      "tags": [
        {"id": 2, "name": "Coinbase Ventures"}
      ],
      "categories": [
        {"id": 2, "name": "Founders"},
        {"id": 9, "name": "Angels"}
      ],
      "subscribed_at": "2021-08-03T02:32:22.948Z"
    },
    {
      "twitter_id": "18876842",
      "username": "jessepollak",
      "name": "jesse.base.eth",
      "description": "@base builder #001 | DM @jessexbt_ai to get building",
      "twitter_score": 1000.0,
      "followers_count": 352911,
      "profile_image": "https://twitterscore.s3.amazonaws.com/media/profiles/18876842.jpg",
      "tags": [
        {"id": 2, "name": "Coinbase Ventures"}
      ],
      "categories": [
        {"id": 9, "name": "Angels"}
      ],
      "subscribed_at": "2021-09-06T14:38:32.655Z"
    }
  ]
}

Get followers from tag's category "Ecosystems"

https://twitterscore.io/api/v1/get_followers?api_key=API_KEY&twitter_id=44196397&tag_category_id=3&size=2

Answer example:

{
  "success": true,
  "total": 180,
  "page": 1,
  "size": 2,
  "pages": 90,
  "top_followers": [
    {
      "twitter_id": "295218901",
      "username": "VitalikButerin",
      "name": "vitalik.eth",
      "description": "I choose balance. First-level balance.\n\nmi pinxe lo crino tcati\n\nhttps://t.co/gCQrmCby7P",
      "twitter_score": 1000.0,
      "followers_count": 6454273,
      "profile_image": "https://twitterscore.s3.amazonaws.com/media/profiles/295218901.jpg",
      "tags": [
        {"id": 22, "name": "Ethereum"}
      ],
      "categories": [
        {"id": 2, "name": "Founders"}
      ],
      "subscribed_at": "2021-08-04T19:01:17.141Z"
    },
    {
      "twitter_id": "2327407569",
      "username": "toly",
      "name": "toly 🇺🇸",
      "description": "Co-Founder of Solana Labs. Award winning phone creator. NFA, don't trust me, mostly technical gibberish. https://t.co/LomgbTpb6h",
      "twitter_score": 1000.0,
      "followers_count": 1254284,
      "profile_image": "https://twitterscore.s3.amazonaws.com/media/profiles/2327407569.jpg",
      "tags": [
        {"id": 13, "name": "Solana"}
      ],
      "categories": [
        {"id": 2, "name": "Founders"},
        {"id": 8, "name": "Influencers"},
        {"id": 9, "name": "Angels"}
      ],
      "subscribed_at": "2021-11-26T04:09:36.723Z"
    }
  ]
}

Get followers from category "Projects" with tag "Binance"

https://twitterscore.io/api/v1/get_followers?api_key=API_KEY&twitter_id=44196397&category_id=3&tag_id=11&size=2

Answer example:

{
  "success": true,
  "total": 6,
  "page": 1,
  "size": 2,
  "pages": 3,
  "top_followers": [
    {
      "twitter_id": "877807935493033984",
      "username": "binance",
      "name": "Binance",
      "description": "The world's leading blockchain ecosystem and digital asset exchange | #Binance #BNB | Support: @BinanceHelpDesk | Posts are not directed towards UK users.",
      "twitter_score": 919.77,
      "followers_count": 16029849,
      "profile_image": "https://twitterscore.s3.amazonaws.com/media/profiles/877807935493033984.jpg",
      "tags": [
        {"id": 11, "name": "Binance"}
      ],
      "categories": [
        {"id": 1, "name": "Venture Capitals"},
        {"id": 3, "name": "Projects"},
        {"id": 4, "name": "Exchanges"}
      ],
      "subscribed_at": "2021-08-03T01:50:58.670Z"
    },
    {
      "twitter_id": "1400391752368992260",
      "username": "BinanceWallet",
      "name": "Binance Wallet",
      "description": "Experience Web3 effortlessly with #Binance Wallet\nSimple, Secure, Rewarding.",
      "twitter_score": 261.88,
      "followers_count": 2861977,
      "profile_image": "https://twitterscore.s3.amazonaws.com/media/profiles/1400391752368992260.jpg",
      "tags": [
        {"id": 11, "name": "Binance"}
      ],
      "categories": [
        {"id": 3, "name": "Projects"}
      ],
      "subscribed_at": "2025-11-22T02:17:49.411Z"
    }
  ]
}

---

1. Get friendship History.

Get friendship History - followed

https://twitterscore.io/api/v1/friendshipHistory/followed?username=USERNAME&api_key=API_KEY&date=DATE&tag_id=TAG_ID&size=SIZE

Parameters:
1. username (or twitter_id) - compulsory
2. api_key - compulsory
3. date (YYYY-MM-DD) - optional, filters to a specific snapshot date.
   Without it the endpoint returns the full follow/unfollow history.
4. tag_id (comma-separated string of tag ids, e.g. 1,2,3,4) - optional,
   filter accounts by tag id (OR logic across IDs)
5. page - default = 1
6. size (number of returned items) - default = 10, min = 1, max = 25

Answer example:

{
  "success": true,
  "total": 7,
  "page": 1,
  "size": 5,
  "pages": 2,
  "data": [
    {
      "action": "Unfollowed",
      "twitter_id": "22441326",
      "username": "elainegija",
      "name": "Elaine Ramirez | 일레인 기자",
      "twitter_score": 13.05,
      "followers_count": 1624,
      "description": "Operations & growth for media & web3. ex @CoinDesk @ForbesAsia @BBGIndustry @Forkast_News. Without fear, without favour. Art by @michaelroyart",
      "profile_image": "https://twitterscore.s3.amazonaws.com/media/profiles/22441326.jpg",
      "tags": [],
      "categories": [],
      "created_at": "2024-02-02"
    },
    {
      "action": "Followed",
      "twitter_id": "768656754892689409",
      "username": "PatrickXDai",
      "name": "PatrickX",
      "twitter_score": 26.42,
      "followers_count": 14496,
      "description": "Dreamer",
      "profile_image": "https://twitterscore.s3.amazonaws.com/media/profiles/768656754892689409.jpg",
      "tags": [],
      "categories": [
        {"id": 2, "name": "Founders"}
      ],
      "created_at": "2024-02-02"
    },
    {
      "action": "Unfollowed",
      "twitter_id": "626942964",
      "username": "paddybaker_",
      "name": "Paddy B",
      "twitter_score": 35.30,
      "followers_count": 1778,
      "description": "Do insto/pro comms at @krakenfx. Used to write stuff at @coindesk | @crypto_briefing before.",
      "profile_image": "https://twitterscore.s3.amazonaws.com/media/profiles/626942964.jpg",
      "tags": [],
      "categories": [],
      "created_at": "2024-02-02"
    },
    {
      "action": "Followed",
      "twitter_id": "2813365387",
      "username": "benjaminopowers",
      "name": "Benjamin Powers",
      "twitter_score": 34.39,
      "followers_count": 4048,
      "description": "Comms/strategy @150bond. Tech reporter at heart covering AI, government and tech policy. Prev The Messenger, Grid, CoinDesk",
      "profile_image": "https://twitterscore.s3.amazonaws.com/media/profiles/2813365387.jpg",
      "tags": [],
      "categories": [],
      "created_at": "2024-02-02"
    },
    {
      "action": "Unfollowed",
      "twitter_id": "1208938772789964800",
      "username": "guccitroII",
      "name": "guccitroll",
      "twitter_score": 77.35,
      "followers_count": 7169,
      "description": "CRYPTO FOREVER ♡ software engineer",
      "profile_image": "https://twitterscore.s3.amazonaws.com/media/profiles/1208938772789964800.jpg",
      "tags": [],
      "categories": [
        {"id": 2, "name": "Founders"}
      ],
      "created_at": "2024-02-02"
    }
  ]
}

Get friendship History - following

https://twitterscore.io/api/v1/friendshipHistory/following?username=USERNAME&api_key=API_KEY&date=DATE&size=SIZE

Answer example:

{
  "success": true,
  "total": 9,
  "page": 1,
  "size": 3,
  "pages": 3,
  "data": [
    {
      "action": "Following",
      "twitter_id": "1264901941",
      "username": "matiroy",
      "name": "Mati Roy",
      "twitter_score": 5.50,
      "followers_count": 16108,
      "description": "Chief Product & Data Officer at @Netholabs | director at @SparksPreserve | ex OpenAI, xAI",
      "profile_image_url": "https://twitterscore.s3.amazonaws.com/media/profiles/1264901941.jpg",
      "created_at": "2024-11-07",
      "tags": [],
      "categories": []
    },
    {
      "action": "Following",
      "twitter_id": "13218102",
      "username": "JohnCornyn",
      "name": "Senator John Cornyn",
      "twitter_score": 70.85,
      "followers_count": 413318,
      "description": "Proudly representing Texas in the U.S. Senate. Lifelong conservative. Fighting for Texas values & border security with 99% voting record with Pres. Trump 🇺🇸",
      "profile_image_url": "https://twitterscore.s3.amazonaws.com/media/profiles/13218102.jpg",
      "created_at": "2024-11-07",
      "tags": [],
      "categories": []
    },
    {
      "action": "Following",
      "twitter_id": "15075999",
      "username": "hughhewitt",
      "name": "Hugh Hewitt",
      "twitter_score": 87.97,
      "followers_count": 268676,
      "description": "Broadcasting 3-6 PM EST on Salem News Channel/affiliates nationwide. Fox News Contributor. Browns/Tribe/Cavs/Buckeyes \"We are not enemies, but friends.\" Lincoln",
      "profile_image_url": "https://twitterscore.s3.amazonaws.com/media/profiles/15075999.jpg",
      "created_at": "2024-11-07",
      "tags": [],
      "categories": []
    }
  ]
}

---

1. Check your API limits.

https://twitterscore.io/api/v1/limits?api_key=API_KEY

Answer example:

{"user_id": 20991, "rates": [{"period": "month", "total": 200000, "used": 10700, "remaining": 189300, "reset_time_at": "2025-05-12T18:27:41.280"}, {"period": "minute", "total": 60}]}

---

NEW ENDPOINTS 🔥

---

1. Get aggregated TwitterScore sum of smart followers.

https://twitterscore.io/api/v1/get_followers_score_sum?api_key=API_KEY&twitter_id=TWITTER_ID&category_ids=CATEGORY_IDS&tag_ids=TAG_IDS

Parameters:
1. username (or twitter_id) - compulsory
2. api_key - compulsory
3. category_ids (comma-separated string of category ids, e.g. 2,8) -
   optional, filter smart followers by category (OR logic within field)
4. tag_ids (comma-separated string of tag ids, e.g. 1,2,11) -
   optional, filter smart followers by tag (OR logic within field)

When both category_ids and tag_ids are passed — applied as AND
(a follower must match a category AND a tag).

Answer example:

{
  "success": true,
  "twitter_id": "44196397",
  "username": "elonmusk",
  "name": "Elon Musk",
  "description": "https://t.co/dDtDyVssfm",
  "profile_image": "https://twitterscore.s3.amazonaws.com/media/profiles/44196397.jpg",
  "twitter_score": 1000.0,
  "followers_count": 240113071,
  "smart_followers_count": 19584,
  "followers_score_sum": 1484037.27,
  "tags": [],
  "categories": [
    {"category_id": 2, "category_name": "Founders"},
    {"category_id": 8, "category_name": "Influencers"}
  ]
}

---

1. Get top accounts by mentions over a period (SMART MENTIONS PAGE).

https://twitterscore.io/api/v1/get_smart_mentions?api_key=API_KEY&days=DAYS&category_id=CATEGORY_ID&by=BY&sort=SORT&page=PAGE&size=SIZE

Parameters:
1. api_key - compulsory
2. days (1, 7 or 30) - default = 7
3. category_id (Category.id, 0 = all, -1 = NoCategory) - default = 0
4. by (score / followers / mentions / mentioners) - default = mentions
5. sort (asc / desc) - default = desc
6. page - default = 1
7. size (number of returned items) - default = 10, min = 1, max = 100

Answer example:

{
  "success": true,
  "total": 77,
  "page": 1,
  "size": 1,
  "pages": 77,
  "days": 30,
  "category_name": "Exchanges",
  "data": [
    {
      "twitter_id": "574032254",
      "username": "coinbase",
      "name": "Coinbase 🛡️",
      "profile_url": "/twitter/coinbase",
      "profile_image": "https://twitterscore.s3.amazonaws.com/media/profiles/574032254.png",
      "blue_verified": true,
      "description": "The future of finance is on Coinbase. For support: @CoinbaseSupport",
      "twitter_score": 1000,
      "twitter_score_diff_int": 0,
      "twitter_score_diff_str": "0",
      "current_followers": 6915974,
      "followers_diff_int": 3010,
      "followers_diff_str": "3 010",
      "mentions_total": 52110,
      "mentions_diff_int": 189,
      "mentions_diff_str": "189",
      "unique_mentioners_total": 9508,
      "unique_mentioners_diff_int": 114,
      "unique_mentioners_diff_str": "114",
      "top_mentioner": {
        "name": "CoinDesk",
        "username": "CoinDesk",
        "image": "https://twitterscore.s3.amazonaws.com/media/profiles/1333467482.jpg",
        "score": 963,
        "verified": true
      },
      "mentioners_list": [
        {
          "name": "CoinDesk",
          "username": "CoinDesk",
          "image": "https://twitterscore.s3.amazonaws.com/media/profiles/1333467482.jpg",
          "score": 963,
          "verified": true
        },
        {
          "name": "Jake Chervinsky",
          "username": "jchervinsky",
          "image": "https://twitterscore.s3.amazonaws.com/media/profiles/47003920.jpg",
          "score": 662,
          "verified": true
        },
        {
          "name": "jeff.hl",
          "username": "chameleon_jeff",
          "image": "https://twitterscore.s3.amazonaws.com/media/profiles/1622260212798291972.jpg",
          "score": 597,
          "verified": true
        },
        {
          "name": "DEGEN NEWS",
          "username": "DegenerateNews",
          "image": "https://twitterscore.s3.amazonaws.com/media/profiles/1505874016761831430.jpg",
          "score": 594,
          "verified": true
        },
        {
          "name": "Paul Grewal",
          "username": "iampaulgrewal",
          "image": "https://twitterscore.s3.amazonaws.com/media/profiles/2956378446.jpg",
          "score": 509,
          "verified": true
        },
        {
          "name": "Base Build",
          "username": "buildonbase",
          "image": "https://twitterscore.s3.amazonaws.com/media/profiles/1444011503275810822.jpg",
          "score": 459,
          "verified": true
        }
      ],
      "categories": [
        {"id": 4, "name": "Exchanges"},
        {"id": 1, "name": "Venture Capitals"}
      ]
    }
  ]
}

---

1. Get list of unique mentioners for an account.

https://twitterscore.io/api/v1/get_mentioners?api_key=API_KEY&username=USERNAME&days=DAYS&date_from=DATE_FROM&date_to=DATE_TO&category_id=CATEGORY_ID&tag_ids=TAG_IDS&by=BY&sort=SORT&page=PAGE&size=SIZE

Parameters:
1. username (or twitter_id) - compulsory
2. api_key - compulsory
3. days (1, 7 or 30) - default = 7
4. date_from (DD-MM-YYYY, paired with date_to) - optional
5. date_to (DD-MM-YYYY, paired with date_from) - optional
6. category_id (Category.id, comma-separated allowed) - optional,
   filter mentioners by category
7. tag_ids (comma-separated string of tag ids, e.g. 1,2,11) - optional,
   filter mentioners by tag (OR logic within field)
8. by (score / followers) - default = score
9. sort (asc / desc) - default = desc
10. page - default = 1
11. size (number of returned items) - default = 10, min = 1, max = 100

If both date_from and date_to are provided, days is ignored.
Passing only one of the pair returns an error.
Date window is inclusive: [date_from 00:00 UTC, date_to+1 day 00:00 UTC).
When both category_id and tag_ids are passed - applied as AND.

Answer example:

{
  "success": true,
  "total": 24,
  "page": 1,
  "size": 3,
  "pages": 8,
  "twitter_id": "44196397",
  "username": "elonmusk",
  "name": "Elon Musk",
  "description": "https://t.co/dDtDyVssfm",
  "followers_count": 240113071,
  "profile_image": "https://twitterscore.s3.amazonaws.com/media/profiles/44196397.jpg",
  "tags": [],
  "categories": [
    {"category_id": 2, "category_name": "Founders"},
    {"category_id": 8, "category_name": "Influencers"}
  ],
  "days": 7,
  "mentioners": [
    {
      "twitter_id": "1319287761048723458",
      "username": "MarioNawfal",
      "name": "Mario Nawfal",
      "profile_image": "https://twitterscore.s3.amazonaws.com/media/profiles/1319287761048723458.jpg",
      "blue_verified": true,
      "twitter_score": 746.87,
      "followers_count": 3523098
    },
    {
      "twitter_id": "2361631088",
      "username": "CathieDWood",
      "name": "Cathie Wood",
      "profile_image": "https://twitterscore.s3.amazonaws.com/media/profiles/2361631088.jpg",
      "blue_verified": true,
      "twitter_score": 650.59,
      "followers_count": 2276085
    },
    {
      "twitter_id": "1234260054368342016",
      "username": "theallinpod",
      "name": "The All-In Podcast",
      "profile_image": "https://twitterscore.s3.amazonaws.com/media/profiles/1234260054368342016.jpg",
      "blue_verified": false,
      "twitter_score": 317.40,
      "followers_count": 573756
    }
  ]
}

---

1. Get smart mentions feed for an account.

https://twitterscore.io/api/v1/get_mentions_feed?api_key=API_KEY&username=USERNAME&category_id=CATEGORY_ID&tag_id=TAG_ID&tag_category_id=TAG_CATEGORY_ID&by=BY&sort=SORT&page=PAGE&size=SIZE

Parameters:
1. username (or twitter_id) - compulsory
2. api_key - compulsory
3. by (score / favorites / retweets / replies / views / created_at) -
   default = created_at (newest first)
4. sort (asc / desc) - default = desc
5. category_id (int) - optional, filter mentions to authors in given category
6. tag_id (int) - optional, filter mentions to authors with given tag
7. tag_category_id (int) - optional, filter to authors in given tag's category
8. page - default = 1
9. size (number of returned items) - default = 10, min = 1, max = 25

Answer example:

{
  "success": true,
  "total": 102992,
  "page": 1,
  "size": 1,
  "pages": 102992,
  "mentions": [
    {
      "id": "2058589123267494355",
      "text": "JUST IN: @elonmusk's SpaceX has officially disclosed its Bitcoin treasury in a new SEC filing, revealing it holds 18,712 $BTC.\n\nThe position, valued at $1.293 billion, represents a nearly 119% unrealized gain and places SpaceX ahead of Tesla as the 7th largest corporate BTC holder.\n\ncryptopotato.com/spacex-reveals…",
      "created_at": "2026-05-24T16:41:08+00:00",
      "favorites": 1,
      "retweets": 0,
      "replies": 0,
      "views": 154,
      "author": {
        "twitter_id": "2367079278",
        "username": "Crypto_Potato",
        "name": "CryptoPotato Official",
        "profile_image": "https://twitterscore.s3.amazonaws.com/media/profiles/2367079278.jpg",
        "blue_verified": true,
        "followers_count": 38114,
        "twitter_score": 46.86,
        "tags": [],
        "categories": []
      },
      "media": [],
      "urls": [
        {
          "url": "cryptopotato.com/spacex-reveals…",
          "expanded_url": "https://cryptopotato.com/spacex-reveals-how-much-bitcoin-btc-it-owns/",
          "display_url": "cryptopotato.com/spacex-reveals…"
        }
      ]
    }
  ]
}

---

1. Get trending accounts.

https://twitterscore.io/api/v1/get_trending?api_key=API_KEY&days=DAYS&category_id=CATEGORY_ID&by=BY&sort=SORT&page=PAGE&size=SIZE

Parameters:
1. api_key - compulsory
2. days (3, 7 or 30) - default = 30
3. by (followers / score) - default = score
4. sort (asc / desc) - default = desc
5. category_id (Category.id; 0 = all, -1 = NoCategory) - default = 0 (all)
6. page - default = 1
7. size (number of returned items) - default = 10, min = 1, max = 100

Sort behavior:
- by=score    — primary key: twitter_score_diff_int (delta over period),
                secondary: current twitter_score (same direction).
- by=followers — primary key: followers_diff_int,
                 secondary: current twitter_score (same direction).

Answer example:

{
  "success": true,
  "total": 1000,
  "page": 1,
  "size": 2,
  "pages": 500,
  "days": 30,
  "category_name": "all",
  "data": [
    {
      "twitter_id": "23395456",
      "name": "Spencer Pratt",
      "username": "spencerpratt",
      "description": "This account is being used for campaign purposes by Pratt for Mayor 2026.",
      "img": "https://twitterscore.s3.amazonaws.com/media/profiles/23395456.jpg",
      "url": "https://twitterscore.io/twitter/spencerpratt",
      "curr_followers": 1160267,
      "prev_followers": 1156415,
      "twitter_score": 114,
      "prev_twitter_score": 42,
      "twitter_score_diff_str": "72",
      "twitter_score_diff_int": 72,
      "followers_diff_int": 3852,
      "followers_diff_str": "3 852",
      "user_tags": []
    },
    {
      "twitter_id": "2989966781",
      "name": "Leopold Aschenbrenner",
      "username": "leopoldasch",
      "description": "https://t.co/XSH2wseW3E",
      "img": "https://twitterscore.s3.amazonaws.com/media/profiles/2989966781.jpg",
      "url": "https://twitterscore.io/twitter/leopoldasch",
      "curr_followers": 200815,
      "prev_followers": 199941,
      "twitter_score": 332,
      "prev_twitter_score": 273,
      "twitter_score_diff_str": "59",
      "twitter_score_diff_int": 59,
      "followers_diff_int": 874,
      "followers_diff_str": "874",
      "user_tags": []
    }
  ]
}

---

1. Get top researched accounts (last 24 hours).

https://twitterscore.io/api/v1/get_top_researched?api_key=API_KEY&type=TYPE&page=PAGE&size=SIZE

Parameters:
1. api_key - compulsory
2. type (searching / opening) - default = searching
   - searching: top accounts by number of profile searches
   - opening:   top accounts by number of profile opens
3. page - default = 1
4. size (number of returned items) - default = 10, min = 1, max = 25

Note: the endpoint always returns only top 10 accounts (total = 10).
Setting size > 10 has no effect; pagination is rarely useful.

Answer example:

{
  "success": true,
  "total": 10,
  "page": 1,
  "size": 2,
  "pages": 5,
  "accounts": [
    {
      "username": "xleva_eth",
      "name": "xLeva",
      "profile_url": "/twitter/xleva_eth",
      "profile_image": "https://twitterscore.s3.amazonaws.com/media/profiles/1571986153284272128.jpg",
      "verified": false,
      "twitter_score": 3.68,
      "current_followers": 3679,
      "followers_diff": 3679,
      "description": "On chain alpha researcher| Degen early play hunter \nTestnet  Airdrop  Narrative",
      "tags": [],
      "categories": []
    },
    {
      "username": "Fujina73",
      "name": "Fujina",
      "profile_url": "/twitter/Fujina73",
      "profile_image": "https://twitterscore.s3.amazonaws.com/media/profiles/852373151883206656.jpg",
      "verified": false,
      "twitter_score": 0.0,
      "current_followers": 8069,
      "followers_diff": 8069,
      "description": "Ambassador: @spaace_io\nCreator in @EVEDEX\nContribute: @axisrobotics",
      "tags": [],
      "categories": []
    }
  ]
}

---

1. Get tokenless projects.

https://twitterscore.io/api/v1/get_tokenless?api_key=API_KEY&by=BY&sort=SORT&page=PAGE&size=SIZE

Parameters:
1. api_key - compulsory
2. by (followers / score) - default = score
3. sort (asc / desc) - default = desc
4. page - default = 1
5. size (number of returned items) - default = 10, min = 1, max = 100

Sort behavior:
- by=score    — ranked by current twitter_score
- by=followers — ranked by followers_diff_int (delta over the
                 tracked period — same data that powers /tokenless/)

Answer example:

{
  "success": true,
  "total": 1000,
  "page": 1,
  "size": 1,
  "pages": 500,
  "data": [
    {
      "twitter_id": "946213559213555712",
      "name": "OpenSea",
      "username": "opensea",
      "description": "The best place to discover, own, and trade onchain | Get help at https://t.co/f3KCJaxqBz | UK users: @OpenSea_UK",
      "twitter_score": 851.53,
      "curr_followers_int": 2266678,
      "curr_followers_str": "2.27M",
      "prev_followers_int": 2266784,
      "prev_followers_str": "2.27M",
      "followers_diff_int": -106,
      "followers_diff_str": "-106",
      "img": "https://twitterscore.s3.amazonaws.com/media/profiles/946213559213555712.jpg"
    }
  ]
}

---

1. Get Smart Follows accounts.

https://twitterscore.io/api/v1/get_alpha?api_key=API_KEY&days=DAYS&bucket=BUCKET&by=BY&sort=SORT&page=PAGE&size=SIZE

Parameters:
1. api_key - compulsory
2. days (1 / 7 / 30) - default = 7
3. bucket (all / vc / inf / angels) - default = all
4. by (alpha / score / followers) - default = alpha
5. sort (asc / desc) - default = desc
6. page - default = 1
7. size (number of returned items) - default = 10, min = 1, max = 100
Bucket filter:
- bucket=all     — all alpha follower categories combined
- bucket=vc      — Venture Capitals
- bucket=inf     — Influencers
- bucket=angels  — Angel Investors
Sort behavior:
- by=alpha     — ranked by new_alpha_followers_diff (delta over the days period — same data that powers /Alpha/)
- by=score     — ranked by current twitter_score
- by=followers — ranked by current_followers

Answer example:

{
  "success": true,
  "total": 162958,
  "page": 1,
  "size": 1,
  "pages": 162958,
  "days": 7,
  "bucket": "vc",
  "data": [
    {
      "twitter_id": "94543804",
      "username": "TansuYegen",
      "name": "Tansu Yegen",
      "profile_url": "/twitter/TansuYegen",
      "profile_image": "https://twitterscore.s3.amazonaws.com/media/profiles/94543804.jpg",
      "blue_verified": true,
      "description": "Sharing lifestyle content, AI, tech, and science with a global lens 🌐 | All opinions are my own",
      "twitter_score": 34,
      "twitter_score_diff": 0,
      "current_followers": 1677921,
      "followers_diff": 1677888,
      "total_alpha_followers": 6,
      "new_alpha_followers_diff": 6,
      "top_alpha_followers": [
        {
          "name": "MaxStealth",
          "username": "MaxStealth5",
          "image": "https://twitterscore.s3.amazonaws.com/media/profiles/1294929693997596672.jpg",
          "score": 83,
          "verified": true
        }
      ]
    }
  ]
}

DEPRECATED

---

• Get top 5 followers by score.

https://twitterscore.io/api/v1/get_twitter_top_followers?api_key=API_KEY&twitter_id=44196397

Answer example:

{
  "success": true,
  "top_followers": [
    {
      "twitter_id": 811350,
      "username": "alexisohanian",
      "name": "Alexis Ohanian 🇦🇲",
      "twitter_score": 1000,
      "followers_count": 571523,
      "profile_image": "https://twitterscore.s3.amazonaws.com/media/profiles/811350.jpg"
    },
    {
      "twitter_id": 26377478,
      "username": "laurashin",
      "name": "Laura Shin",
      "twitter_score": 1000,
      "followers_count": 250687,
      "profile_image": "https://twitterscore.s3.amazonaws.com/media/profiles/26377478.png"
    },
    {
      "twitter_id": 710463119886262300,
      "username": "cburniske",
      "name": "Chris Burniske",
      "twitter_score": 1000,
      "followers_count": 300969,
      "profile_image": "https://twitterscore.s3.amazonaws.com/media/profiles/710463119886262272.jpg"
    },
    {
      "twitter_id": 14379660,
      "username": "brian_armstrong",
      "name": "Brian Armstrong",
      "twitter_score": 1000,
      "followers_count": 1374700,
      "profile_image": "https://twitterscore.s3.amazonaws.com/media/profiles/14379660.png"
    },
    {
      "twitter_id": 295218901,
      "username": "VitalikButerin",
      "name": "vitalik.eth",
      "twitter_score": 1000,
      "followers_count": 5433227,
      "profile_image": "https://twitterscore.s3.amazonaws.com/media/profiles/295218901.jpg"
    }
  ]
}

This request is deprecated. It can be completely replaced by request - Get paginated list of followers

---

• Get top followers paginate

https://twitterscore.io/api/v1/top_followers_paginate?twitter_id=44196397&api_key=API_KEY&size=2&page=1

Parameters:
1. username (or twitter_id) - compulsory
2. api_key - compulsory
3. size (number of returned items in the list) – default = 5, max = 25
4. page - default = 1

Answer example:

{
  "success": true,
  "total": 11950,
  "page": 1,
  "size": 2,
  "pages": 5975,
  "top_followers": [
    {
      "twitter_id": 339061487,
      "username": "APompliano",
      "name": "Anthony Pompliano 🌪",
      "twitter_score": 1000,
      "followers_count": 1665993,
      "profile_image": "https://twitterscore.s3.amazonaws.com/media/profiles/339061487.jpg"
    },
    {
      "twitter_id": 1605,
      "username": "sama",
      "name": "Sam Altman",
      "twitter_score": 1000,
      "followers_count": 3029658,
      "profile_image": "https://twitterscore.s3.amazonaws.com/media/profiles/1605.jpg"
    }
  ]
}

This request is deprecated. It can be completely replaced by request - Get paginated list of followers

---

If you can't find the feature you need here, feel free to contact us. We'll work together to find a solution for your problem.