# Number of monitored followers per tag, grouped by tag category

`GET https://twitterscore.io/api/v1/get_tagged_followers_count`

Counts how many of the account's monitored followers carry each TwitterScore tag (for example Tier 1 VC, Ethereum, CEX), grouped by the tag's category (VC tier, Ecosystems, ...). Groups are ordered by tag-category id ascending and tags inside a group by count descending. A follower with several tags is counted once per tag. Only active monitored followers with an active follow relationship are counted. Tags that are not assigned to any tag category are not included in the output. The data array is empty when none of the account's monitored followers is tagged.

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

- `data[].tag_category_id` (number): Tag-category id. Normally an integer; serialised as a float (e.g. 2.0) whenever at least one follower tag has no tag category, because pandas widens the column to float before grouping.
- `data[].tag_category_name` (string): Tag-category name (e.g. "VC Tier", "Ecosystems").
- `data[].tags` (array): Tags in this category, ordered by cnt descending.
- `data[].tags[].tag_id` (integer): Tag id as used by get_tags and get_followers filters.
- `data[].tags[].tag_name` (string): Tag name.
- `data[].tags[].cnt` (integer): Number of monitored followers carrying this tag.

## Parameters

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `username` | string | no |  | X/Twitter handle of the account, without the leading @. Surrounding whitespace and a trailing slash are tolerated; renamed handles are resolved via previous-username history. |
| `twitter_id` | integer | no |  | Numeric X/Twitter user id of the account. Tried first when both are sent; falls back to username if the id resolves nothing. |

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

## Example request

```bash
curl -s "https://twitterscore.io/api/v1/get_tagged_followers_count?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_tagged_followers_count",
    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_tagged_followers_count?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,
  "data": [
    {
      "tag_category_id": 1,
      "tag_category_name": "VC Tier",
      "tags": [
        {
          "tag_id": 13,
          "tag_name": "Tier 2 VC",
          "cnt": 388
        },
        {
          "tag_id": 12,
          "tag_name": "Tier 1 VC",
          "cnt": 143
        }
      ]
    },
    {
      "tag_category_id": 2,
      "tag_category_name": "Ecosystems",
      "tags": [
        {
          "tag_id": 41,
          "tag_name": "Ethereum",
          "cnt": 6120
        },
        {
          "tag_id": 44,
          "tag_name": "Solana",
          "cnt": 2310
        },
        {
          "tag_id": 47,
          "tag_name": "Base",
          "cnt": 1175
        }
      ]
    }
  ]
}
```

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