# ScoreSaber API
> Live player, score and ranking data from ScoreSaber, the global leaderboard for Beat Saber, the VR rhythm game, via its public API. ScoreSaber ranks tens of thousands of players worldwide by performance points (pp). Get a player's full profile — their pp, their global and country rank, their country, and their score statistics: total score, ranked plays and average ranked accuracy. Pull a player's plays, each with the song and mapper, the map's difficulty and star rating, the pp earned, the accuracy, the full-combo flag and the headset used. Get the top players in the world, or filtered to one country. Read ScoreSaber's global numbers — the total ranked players and the current world number one. Live, no key, nothing stored. Distinct from other gaming and social-profile APIs — this is ScoreSaber's pp ranking and its players. Perfect for leaderboard, esports and gaming-community apps.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/scoresaber-api/..."
```

## Pricing
- **Free** (Free) — 12,000 calls/Mo, 3 req/s
- **Starter** ($7/Mo) — 172,000 calls/Mo, 8 req/s
- **Pro** ($19/Mo) — 935,000 calls/Mo, 18 req/s
- **Business** ($47/Mo) — 5,300,000 calls/Mo, 40 req/s

## Endpoints

### Players

#### `GET /v1/player` — Player profile + score stats

**Parameters:**
- `id` (query, required, string) — ScoreSaber player id Example: `1922350521131465`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/scoresaber-api/v1/player?id=1922350521131465"
```

**Response:**
```json
{
    "data": {
        "id": "1922350521131465",
        "pp": 21515.25,
        "name": "oermergeesh",
        "banned": false,
        "source": "ScoreSaber",
        "country": "US",
        "inactive": false,
        "global_rank": 1,
        "total_score": 3965871513,
        "country_rank": 1,
        "replays_watched": null,
        "total_play_count": 4094,
        "ranked_play_count": 1155,
        "total_ranked_score": 1617837297,
        "average_ranked_accuracy_pct": 95.8073
    },
    "meta": {
        "timestamp": "2026-06-10T14:02:20.839Z",
        "request_id": "4a8d2273-8d2f-4faa-adf5-ea949becddda"
    },
    "status": "ok",
    "message": "Player retrieved successfully",
    "success": true
}
```

#### `GET /v1/scores` — Player plays with pp + accuracy

**Parameters:**
- `id` (query, required, string) — ScoreSaber player id Example: `1922350521131465`
- `sort` (query, optional, string) — top or recent Example: `top`
- `limit` (query, optional, string) — Max 1-50 Example: `10`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/scoresaber-api/v1/scores?id=1922350521131465&sort=top&limit=10"
```

**Response:**
```json
{
    "data": {
        "id": "1922350521131465",
        "sort": "top",
        "count": 10,
        "scores": [
            {
                "pp": 805.44,
                "song": "1nput This 2 Y0ur Spine",
                "score": 2081872,
                "stars": 13.32,
                "mapper": "Voidless & CMP1111",
                "set_at": "2026-01-24T03:57:56.000Z",
                "headset": 0,
                "difficulty": "Expert+",
                "full_combo": true,
                "score_rank": 1,
                "song_author": "Camellia",
                "accuracy_pct": 97.66,
                "missed_notes": 0
            },
            {
                "pp": 800.92,
                "song": "Echoes of Memoria",
                "score": 3057188,
                "stars": 13.11,
                "mapper": "Fnyt & THMX",
                "set_at": "2026-01-17T20:54:13.000Z",
                "headset": 0,
                "difficulty": "Expert+",
                "full_combo": true,
                "score_rank": 1,
                "song_author": "Ludicin",
                "accuracy_pct": 97.7039,
                "missed_notes": 0
            },
            {
                "pp": 784.7,
                "song": "Zetsubou MENBRE GIRL",
                "score": 1821302,
                "stars": 11.01,
                "mapper": "Gabriel",
                "set_at": "2026-04-20T03:51:24.000Z",
                "headset": 0,
                "difficulty": "Expert+",
           
…(truncated, see openapi.json for full schema)
```

### Rankings

#### `GET /v1/leaderboard` — Top players worldwide or by country

**Parameters:**
- `page` (query, optional, string) — Page Example: `1`
- `country` (query, optional, string) — 2-letter country code Example: `DE`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/scoresaber-api/v1/leaderboard?page=1&country=DE"
```

**Response:**
```json
{
    "data": {
        "page": 1,
        "count": 50,
        "source": "ScoreSaber",
        "country": "DE",
        "players": [
            {
                "id": "2769016623220259",
                "pp": 17722.56,
                "name": "NailikLP",
                "country": "DE",
                "global_rank": 36,
                "country_rank": 1
            },
            {
                "id": "76561198448469526",
                "pp": 16220.14,
                "name": "Dr.Bread",
                "country": "DE",
                "global_rank": 98,
                "country_rank": 2
            },
            {
                "id": "76561198253282811",
                "pp": 15377.35,
                "name": "Taddus",
                "country": "DE",
                "global_rank": 170,
                "country_rank": 3
            },
            {
                "id": "76561199093163807",
                "pp": 15286.95,
                "name": "DJ Alfred",
                "country": "DE",
                "global_rank": 181,
                "country_rank": 4
            },
            {
                "id": "76561198156925313",
                "pp": 14956.75,
                "name": "~Rainz~",
                "country": "DE",
                "global_rank": 215,
                "country_rank": 5
            },
            {
                "id": "76561198442753567",
                "pp": 14454.25,
                "name": "schonk",
                "country": "DE",

…(truncated, see openapi.json for full schema)
```

### Stats

#### `GET /v1/stats` — ScoreSaber global stats + world #1

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/scoresaber-api/v1/stats"
```

**Response:**
```json
{
    "data": {
        "source": "ScoreSaber",
        "world_number_one": {
            "id": "1922350521131465",
            "pp": 21515.25,
            "name": "oermergeesh",
            "country": "US"
        },
        "total_ranked_players": 39777
    },
    "meta": {
        "timestamp": "2026-06-10T14:02:21.562Z",
        "request_id": "3222e4d7-90c9-4314-a48a-2c402f5fed34"
    },
    "status": "ok",
    "message": "Stats retrieved successfully",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/scoresaber-api
OpenAPI spec: https://www.oanor.com/api/scoresaber-api/openapi.json