# Top 10 accounts by search or profile-open activity on TwitterScore over the last 24 hours.

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

Returns the ten accounts most looked up on twitterscore.io in the past 24 hours — the same data as the /topResearched/ page. `type=searching` (default) ranks by how often the account was searched; `type=opening` ranks by how often its profile page was opened. No target account is needed. Each row is enriched from the account table when an ACTIVE account with that username exists (verified badge, Twitter Score, follower count and its change since the previous snapshot, tags, categories, relative `profile_url`); otherwise `verified`=false, `current_followers`/`followers_diff`=0, `tags`/`categories`=[] and `profile_url`/`twitter_score` come from the lookup log itself. `description` always comes from the log row. `total` is always at most 10, so with the default `size` everything fits on one page. The underlying ranking is cached for 60 minutes.
**Nested fields**

- `accounts[].username` (string): X handle as recorded in the lookup log.
- `accounts[].name` (string): Display name from the account table when found, else from the log (falls back to username).
- `accounts[].profile_url` (string): Relative TwitterScore profile path like /twitter/VitalikButerin when the account is in the table and has a slug; otherwise the absolute URL recorded in the lookup log.
- `accounts[].profile_image` (string): Avatar URL from the account table when it has an image file, else the image URL recorded in the log, or null.
- `accounts[].verified` (boolean): X verified badge; false when the account is not in the table.
- `accounts[].twitter_score` (number): Twitter Score (0-1000, float). From the account table when found, otherwise the project_score recorded in the log row (NOT NULL, default 0).
- `accounts[].current_followers` (integer): Current follower count; 0 when the account is not in the table.
- `accounts[].followers_diff` (integer): current_followers minus the previous stored follower count; 0 when unknown.
- `accounts[].description` (string): X bio as recorded in the log row (may be empty).
- `accounts[].tags` (array): Tags: [{id, name}]. A tag that belongs to several tag-categories may be listed once per tag-category.
- `accounts[].tags[].id` (integer): Tag id.
- `accounts[].tags[].name` (string): Tag name.
- `accounts[].categories` (array): Account categories: [{id, name}].
- `accounts[].categories[].id` (integer): Category id.
- `accounts[].categories[].name` (string): Category name.

## Parameters

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `type` | string (`searching`, `opening`) | no | `searching` | Ranking source: `searching` (search queries) or `opening` (profile opens). Whitespace is trimmed; empty falls back to `searching`. Any other value returns success=false with message "Param `type` must be one of [searching\|opening]". |
| `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 25; 0 or negative becomes 1; non-numeric falls back to 10. |

## Example request

```bash
curl -s "https://twitterscore.io/api/v1/get_top_researched?type=searching" \
  -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_top_researched",
    params={"type": "searching"},
    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_top_researched?type=searching", {
  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": 10,
  "page": 1,
  "size": 2,
  "pages": 5,
  "accounts": [
    {
      "username": "VitalikButerin",
      "name": "vitalik.eth",
      "profile_url": "/twitter/VitalikButerin",
      "profile_image": "https://twitterscore.io/media/profiles/VitalikButerin.jpg",
      "verified": true,
      "twitter_score": 1000,
      "current_followers": 5812345,
      "followers_diff": 1532,
      "description": "mi pinxe lo crino tcati",
      "tags": [
        {
          "id": 11,
          "name": "Ethereum"
        }
      ],
      "categories": [
        {
          "id": 3,
          "name": "Influencers"
        }
      ]
    },
    {
      "username": "ethereum",
      "name": "Ethereum",
      "profile_url": "/twitter/ethereum",
      "profile_image": "https://twitterscore.io/media/profiles/ethereum.jpg",
      "verified": true,
      "twitter_score": 912,
      "current_followers": 3654210,
      "followers_diff": -214,
      "description": "Ethereum is a global, open-source platform for decentralized applications.",
      "tags": [
        {
          "id": 11,
          "name": "Ethereum"
        }
      ],
      "categories": [
        {
          "id": 1,
          "name": "Projects"
        }
      ]
    }
  ]
}
```

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