# Paginated list of unique accounts that mentioned a target account in a period, with the target's profile.

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

Returns the distinct tracked accounts that authored at least one tweet mentioning the target within a time window, sorted by their Twitter Score (default) or follower count, up to 100 per page. The window is either a rolling `days` back from the current moment (1, 7 or 30, default 7) or an explicit inclusive calendar range `date_from`..`date_to` (both required together, YYYY-MM-DD, interpreted as UTC midnight bounds); when a range is given `days` is ignored. Only authors present in TwitterScore's account table are listed (they are the only ones with a score to sort by), and the target never counts as its own mentioner. `tag_id` / `category_id` keep only mentioners carrying that tag / category (AND when both given). The response also carries the target's profile (`twitter_id`, `username`, `name`, `description`, `followers_count`, `profile_image`, `tags`, `categories`) and echoes the window as either `days` or `date_from`+`date_to`. Each mentioner row has `twitter_id`, `username`, `name`, `profile_image`, `blue_verified`, `twitter_score`, `followers_count`.

**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.
- `mentioners[].twitter_id` (string): Mentioner's X user id as a string.
- `mentioners[].username` (string): Mentioner's handle.
- `mentioners[].name` (string): Mentioner's display name.
- `mentioners[].profile_image` (string): Mentioner's avatar URL, or null.
- `mentioners[].blue_verified` (boolean): X verified badge.
- `mentioners[].twitter_score` (number): Mentioner's Twitter Score (0-1000, float).
- `mentioners[].followers_count` (integer): Mentioner's current follower count.

## Parameters

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `username` | string | no |  | X handle of the target account. 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` on a miss. |
| `days` | integer (`1`, `7`, `30`) | no | `7` | Rolling lookback window: 1, 7 or 30 days back from the request time (not aligned to midnight). Non-numeric falls back to 7; other numbers return success=false with message "Days params is only available: 1\|7\|30". Ignored when `date_from`/`date_to` are given. |
| `date_from` | string | no |  | Start date (inclusive, from 00:00 UTC) in YYYY-MM-DD. Must be sent together with `date_to` (else message "`date_from` and `date_to` must be provided together"), parse as YYYY-MM-DD (else "Invalid date format. Use YYYY-MM-DD") and be on or before `date_to` (else "`date_from` must be on or before `date_to`"). All three are success=false responses. |
| `date_to` | string | no |  | End date (inclusive, whole day up to 24:00 UTC) in YYYY-MM-DD. Must be sent together with `date_from`. |
| `by` | string (`score`, `followers`) | no | `score` | Sort column for mentioners: `score` (Twitter Score) or `followers` (follower count). Any other value returns success=false with message "Sorting is only possible by [score\|followers]". |
| `sort` | string (`asc`, `desc`, `ascending`, `descending`) | no | `desc` | `asc`/`ascending` (case-insensitive) for ascending; anything else descending. |
| `tag_id` | integer | no |  | Keep only mentioners carrying this tag (single integer id; non-numeric is silently ignored). |
| `category_id` | integer | no |  | Keep only mentioners with this account category (single integer id; non-numeric is silently ignored). |
| `page` | integer | no | `1` | 1-based page number. Non-numeric, 0 or negative falls back to 1; a page past the last returns an empty list. |
| `size` | integer | no | `10` | Rows per page. Clamped to 100; 0 or negative becomes 1; non-numeric falls back to 10. |

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

## Example request

```bash
curl -s "https://twitterscore.io/api/v1/get_mentioners?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_mentioners",
    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_mentioners?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,
  "total": 1136,
  "page": 1,
  "size": 2,
  "pages": 568,
  "twitter_id": "295218901",
  "username": "VitalikButerin",
  "name": "vitalik.eth",
  "description": "mi pinxe lo crino tcati",
  "followers_count": 5812345,
  "profile_image": "https://twitterscore.io/media/profiles/VitalikButerin.jpg",
  "tags": [
    {
      "tag_id": 11,
      "tag_name": "Ethereum"
    }
  ],
  "categories": [
    {
      "category_id": 3,
      "category_name": "Influencers"
    }
  ],
  "days": 7,
  "mentioners": [
    {
      "twitter_id": "2312333412",
      "username": "ethereum",
      "name": "Ethereum",
      "profile_image": "https://twitterscore.io/media/profiles/ethereum.jpg",
      "blue_verified": true,
      "twitter_score": 912,
      "followers_count": 3654210
    },
    {
      "twitter_id": "574032254",
      "username": "coinbase",
      "name": "Coinbase",
      "profile_image": "https://twitterscore.io/media/profiles/coinbase.jpg",
      "blue_verified": true,
      "twitter_score": 871,
      "followers_count": 7120456
    }
  ]
}
```

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