# Trending accounts ranked by Twitter Score or follower change over 3, 7 or 30 days

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

Returns the ranked list that powers the /trending/ page: non-suspended accounts whose Twitter Score was above zero at the start of the period, with current vs start-of-period follower counts and Twitter Score for the chosen window (3, 7 or 30 days) and the deltas between them. Rows come from a pre-aggregated, cron-refreshed slice of at most 1000 ranked rows per (days, category, sort, direction) combination, so `total` never exceeds 1000. Sort by Twitter Score change (`by=score`, default) or follower change (`by=followers`); ties are broken by the current Twitter Score. Restrict to one account category with `category_id` (ids from /api/v1/get_categories_list); `0` means every category, `-1` means accounts with no category. Accounts on the trending blacklist are removed before pagination. Each row carries the account's tags together with the tag-category each tag belongs to (`user_tags`). The response echoes the resolved `days` and `category_name` next to the pagination fields.
**Nested fields**

- `data[].twitter_id` (string): The account's numeric Twitter/X id as a string (CAST ... AS CHAR in the SQL view; preserves 64-bit precision).
- `data[].name` (string): Display name.
- `data[].username` (string): Handle without the @.
- `data[].description` (string): Profile bio (empty string when none).
- `data[].img` (string): Avatar URL (TwitterScore S3 copy, aws_image_url). When no image is stored the value is settings.MEDIA_URL + "profiles/NoImageFound.png": "/media/profiles/NoImageFound.png" on a deployment that serves media locally, or "https://<bucket>.s3.amazonaws.com/media/profiles/NoImageFound.png" when USE_S3 is on.
- `data[].url` (string): Public TwitterScore profile page, https://twitterscore.io/twitter/{slug}.
- `data[].curr_followers` (integer): Follower count at the end of the window (period snapshot).
- `data[].prev_followers` (integer): Follower count at the start of the window.
- `data[].twitter_score` (integer): Twitter Score at the end of the window (0-1000 scale, integer).
- `data[].prev_twitter_score` (integer): Twitter Score at the start of the window; always > 0 because the SQL view requires prev_project_score > 0.
- `data[].twitter_score_diff_int` (integer): twitter_score minus prev_twitter_score (snapshot score_diff); may be negative. Sort key for by=score.
- `data[].twitter_score_diff_str` (string): twitter_score_diff_int formatted with a space as thousands separator, e.g. "1 250" or "-32".
- `data[].followers_diff_int` (integer): curr_followers minus prev_followers; may be negative. Sort key for by=followers.
- `data[].followers_diff_str` (string): followers_diff_int formatted with a space as thousands separator, e.g. "14 135".
- `data[].user_tags` (array): Tags attached to the account. Empty array when the account has no tags.
- `data[].user_tags[].id` (number): Tag id (see /api/v1/get_tags_list). Integral value, but may be serialised as a float such as 17.0 because the id column passes through a pandas DataFrame containing NULLs (see notes).
- `data[].user_tags[].name` (string): Tag name.
- `data[].user_tags[].categories_id` (number): Id of the tag-category the tag belongs to (same float caveat as id).
- `data[].user_tags[].categories_name` (string): Name of the tag-category the tag belongs to.

## Parameters

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `days` | integer (`3`, `7`, `30`) | no | `30` | Comparison window in days. Only 3, 7 or 30 are accepted. The value is first clamped to at most 30 (so 31, 100, ... become 30), then checked: any other integer (0, 1, 2, 4..29, negatives) returns {"success": false, "message": "Days params is only available: 30\|7\|3"}. A non-numeric value falls back to 30. |
| `by` | string (`score`, `followers`) | no | `score` | Ranking column. `score` sorts by the Twitter Score change over the window (twitter_score_diff_int), `followers` by the follower change (followers_diff_int). Case-sensitive; any other value (including `Score`) returns {"success": false, "message": "Sorting is only possible by [followers\|score]"}. |
| `sort` | string (`desc`, `asc`, `descending`, `ascending`) | no | `desc` | Sort direction. `asc` or `ascending` (case-insensitive) sorts ascending (biggest losses first); anything else, including the default, sorts descending. |
| `category_id` | integer | no | `0` | Account category filter. 0 = all categories, -1 = accounts without any category (reported as category_name "NoCategory"), otherwise a category id from /api/v1/get_categories_list. An unknown positive id returns {"success": false, "message": "Category with id=N not found"}. A non-numeric value falls back to 0. |
| `page` | integer | no | `1` | 1-based page number. Non-numeric, 0 or negative values are treated as 1. A page past the last one returns an empty `data` array. |
| `size` | integer | no | `10` | Rows per page, capped at 100. Values below 1 are treated as 1; a non-numeric value falls back to 10. |

## Example request

```bash
curl -s "https://twitterscore.io/api/v1/get_trending?days=7" \
  -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_trending",
    params={"days": 7},
    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_trending?days=7", {
  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": 1000,
  "page": 1,
  "size": 1,
  "pages": 1000,
  "days": 7,
  "category_name": "all",
  "data": [
    {
      "twitter_id": "295218901",
      "name": "vitalik.eth",
      "username": "VitalikButerin",
      "description": "mi pinxe lo crino tcati",
      "img": "https://twitterscore.s3.amazonaws.com/profiles/VitalikButerin.jpg",
      "url": "https://twitterscore.io/twitter/VitalikButerin",
      "curr_followers": 5812345,
      "prev_followers": 5798210,
      "twitter_score": 1000,
      "prev_twitter_score": 998,
      "twitter_score_diff_str": "2",
      "twitter_score_diff_int": 2,
      "followers_diff_int": 14135,
      "followers_diff_str": "14 135",
      "user_tags": [
        {
          "id": 17,
          "name": "Ethereum",
          "categories_id": 3,
          "categories_name": "Ecosystem"
        }
      ]
    }
  ]
}
```

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