# 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 | Default | 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

```bash
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 (contact@example.com)"
```

```python
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 (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_followers_score_sum?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,
  "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](/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).