# Twitter Scores for up to 50 accounts in one request

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

Looks up many accounts at once from a comma-separated list of `ids` (numeric X/Twitter ids) or `usernames` (handles) and returns each one's Twitter Score with a link to the profile. `ids` wins when both are non-empty. Only the first 50 comma-separated entries are considered (extra entries are silently dropped; the cap is applied before validation, so non-numeric entries still consume slots) and non-numeric ids are skipped. Accounts that TwitterScore does not know are simply absent from the result — there is no per-item error — so `total` is the number of MATCHED accounts, not the number requested. Matched rows keep the order of the input list and are paginated with `page`/`size` (size default 10, max 50).

**Required:** one of `ids`, `usernames`.
**Nested fields**

- `data[].twitter_id` (string): Numeric X/Twitter id as a string (CONVERT(..., CHAR) in SQL).
- `data[].username` (string): Handle as stored by TwitterScore (canonical casing).
- `data[].twitter_url` (string): Profile link, "https://x.com/<username>".
- `data[].twitter_score` (number): Twitter Score 0–1000; stored as DOUBLE, emitted as a float (e.g. 1000.0).

## Parameters

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `ids` | string | no |  | Comma-separated numeric X/Twitter ids, at most 50 (the rest are ignored). Non-numeric entries are dropped; if none remain the call still succeeds with total 0. Takes precedence over `usernames` whenever non-empty. |
| `usernames` | string | no |  | Comma-separated handles without @, at most 50; surrounding whitespace per entry is stripped. Used only when `ids` is empty. |
| `page` | integer | no | `1` | 1-based page of the matched rows. Non-integer or 0 falls back to 1; negative values are floored to 1. A page past the end returns an empty `data` with the same total/pages. |
| `size` | integer | no | `10` | Rows per page; values above 50 are capped to 50, non-integer values fall back to 10, values below 1 are floored to 1. |

At least one of `ids`, `usernames` is required.

## Example request

```bash
curl -s "https://twitterscore.io/api/v1/bulk_scores_check?ids=295218901,44196397" \
  -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/bulk_scores_check",
    params={"ids": "295218901,44196397"},
    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/bulk_scores_check?ids=295218901,44196397", {
  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": 2,
  "page": 1,
  "size": 2,
  "pages": 1,
  "data": [
    {
      "twitter_id": "295218901",
      "username": "VitalikButerin",
      "twitter_url": "https://x.com/VitalikButerin",
      "twitter_score": 1000.0
    },
    {
      "twitter_id": "44196397",
      "username": "elonmusk",
      "twitter_url": "https://x.com/elonmusk",
      "twitter_score": 1000.0
    }
  ]
}
```

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