Aggregated Twitter Score sum and count of an account's smart followers, optionally filtered by tags/categories.

GET https://twitterscore.io/api/v1/get_followers_score_sum

Returns the target account's basic profile together with two aggregates over its smart followers (monitored, active, non-suspended accounts that follow it): smart_followers_count and followers_score_sum, the sum of those followers' Twitter Scores. Pass comma-separated tag_ids and/or category_ids to aggregate only over followers that carry any of the given tags (OR) and/or any of the given categories (OR); when both are given they combine with AND, and each follower is counted once even if it matches several ids. The tags and categories in the response describe the TARGET account, not its followers, and use the tag_id/tag_name and category_id/category_name key names. Useful for a single-call "quality of audience" number without paging through get_followers.

Required: one of username, twitter_id. Nested fields

tags[].tag_id (integer): Tag id.
tags[].tag_name (string): Tag name.
categories[].category_id (integer): Category id.
categories[].category_name (string): Category name.

Parameters

Parameter	Type	Required	Description
`username`	string	no	X handle of the target account (trailing slash / whitespace tolerated; resolved via current username, slug, then previous usernames). Either `username` or `twitter_id` is required.
`twitter_id`	integer	no	Numeric X user id of the target account. Looked up first; falls back to `username` if no account has this id.
`category_ids`	string	no	Comma-separated account-category ids; a follower matches if it has ANY of them. Whitespace around items is trimmed, empty items skipped. If any item is not an integer the whole list is ignored (no error).
`tag_ids`	string	no	Comma-separated tag ids; a follower matches if it has ANY of them. Combined with `category_ids` using AND. If any item is not an integer the whole list is ignored (no error).

At least one of username, twitter_id is required.

Example request

curl -s "https://twitterscore.io/api/v1/get_followers_score_sum?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/get_followers_score_sum",
    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/get_followers_score_sum?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,
  "twitter_id": "295218901",
  "username": "VitalikButerin",
  "name": "vitalik.eth",
  "description": "mi pinxe lo crino tcati",
  "profile_image": "https://twitterscore.io/media/profiles/VitalikButerin.jpg",
  "twitter_score": 1000,
  "followers_count": 5812345,
  "smart_followers_count": 18342,
  "followers_score_sum": 1267540.5,
  "tags": [
    {
      "tag_id": 11,
      "tag_name": "Ethereum"
    }
  ],
  "categories": [
    {
      "category_id": 3,
      "category_name": "Influencers"
    }
  ]
}

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.