Scores Endpoints

API endpoints for retrieving and filtering player scores, leaderboard scores, and score history

Get Score by ID

GET /scores/:scoreId

Fetch detailed information about a specific score.

scoreId · string · required

The score ID

score · object

Complete score information including player, leaderboard, and performance data

Example Request

curl https://api.scoresaber.com/scores/123456789

Example Response

{
  "scoreId": "123456789",
  "score": 987654,
  "accuracy": 95.5,
  "pp": 250.5,
  "rank": 42,
  "timeSet": "2024-01-01T12:00:00.000Z",
  "player": {
    "id": "76561198059961776",
    "name": "Player Name"
  },
  "leaderboard": {
    "id": 123456,
    "songName": "Song Name",
    "difficulty": "ExpertPlus"
  }
}

---

Get Player Scores from ScoreSaber

GET /scores/player/scoresaber/:playerId/:sort/:page

Fetch a player’s scores directly from ScoreSaber with optional filtering.

playerId · string · required

The ScoreSaber player ID

sort · 'top' | 'recent' · required

Sort order: top for best scores or recent for most recent scores

page · number · required

Page number for pagination (starts at 1)

search · string

Search query to filter scores by song name

comparisonPlayerId · string

Another player’s ID to compare scores against

scores · array

Array of player scores from ScoreSaber

metadata · object

Pagination metadata

Example Request

curl "https://api.scoresaber.com/scores/player/scoresaber/76561198059961776/top/1?search=reality"

Example Response

{
  "scores": [
    {
      "scoreId": "123456789",
      "score": 987654,
      "pp": 250.5,
      "leaderboard": {
        "songName": "Reality Check",
        "difficulty": "ExpertPlus"
      }
    }
  ],
  "metadata": {
    "total": 100,
    "page": 1,
    "itemsPerPage": 8
  }
}

---

Get Player Scores (SSR/Medals)

GET /scores/player/:mode/:playerId/:field/:direction/:page

Fetch player scores with advanced filtering and sorting options.

mode · 'ssr' | 'medals' · required

Scoring mode: ssr for SSR scores or medals for medal-based filtering

playerId · string · required

The ScoreSaber player ID

field · 'pp' | 'medals' | 'misses' | 'acc' | 'score' | 'maxcombo' | 'date' · required

Field to sort by

direction · 'asc' | 'desc' · required

Sort direction: asc for ascending or desc for descending

page · number · required

Page number for pagination (starts at 1)

search · string

Search query to filter scores by song name

hmd · string

Filter by headset type (e.g., Quest 3, Valve Index, Vive Pro 2). See full list of supported HMDs in the HMD schema.

includePlayers · string | string[]

Comma-separated player IDs or array of player IDs to include in results

scores · array

Array of filtered and sorted scores

metadata · object

Pagination and filter metadata

Example Request

curl "https://api.scoresaber.com/scores/player/ssr/76561198059961776/pp/desc/1?hmd=Quest%203"

Example Response

{
  "scores": [
    {
      "scoreId": "123456789",
      "score": 987654,
      "pp": 250.5,
      "accuracy": 95.5,
      "hmd": "Quest 3",
      "leaderboard": {
        "songName": "Song Name",
        "difficulty": "ExpertPlus"
      }
    }
  ],
  "metadata": {
    "total": 500,
    "page": 1,
    "itemsPerPage": 12
  }
}

---

Get Score History Graph

GET /scores/history-graph/:playerId/:leaderboardId

Fetch score history graph data for a player on a specific leaderboard.

playerId · string · required

The ScoreSaber player ID

leaderboardId · number · required

The leaderboard ID

history · array

Array of score history data points for graphing

Example Request

curl https://api.scoresaber.com/scores/history-graph/76561198059961776/123456

Example Response

{
  "history": [
    {
      "date": "2024-01-01T12:00:00.000Z",
      "score": 950000,
      "accuracy": 94.5,
      "pp": 240.0
    },
    {
      "date": "2024-01-15T14:30:00.000Z",
      "score": 987654,
      "accuracy": 95.5,
      "pp": 250.5
    }
  ]
}

---

Get Leaderboard Scores

GET /scores/leaderboard/:leaderboardId/:page

Fetch scores for a specific leaderboard with optional country filtering.

leaderboardId · number · required

The leaderboard ID

page · number · required

Page number for pagination (starts at 1)

country · string

Two-letter country code to filter scores (e.g., US, GB, JP)

scores · array

Array of scores on the leaderboard

metadata · object

Pagination metadata

Example Request

curl https://api.scoresaber.com/scores/leaderboard/123456/1?country=US

Example Response

{
  "scores": [
    {
      "rank": 1,
      "score": 987654,
      "accuracy": 95.5,
      "pp": 250.5,
      "player": {
        "id": "76561198059961776",
        "name": "Player Name",
        "country": "US"
      }
    }
  ],
  "metadata": {
    "total": 1000,
    "page": 1,
    "itemsPerPage": 12
  }
}

---

Get Friend Leaderboard Scores

POST /scores/friend/leaderboard/:leaderboardId/:page

Fetch scores from a list of friends on a specific leaderboard.

leaderboardId · number · required

The leaderboard ID

page · number · required

Page number for pagination (starts at 1)

friendIds · string[] · required

Array of friend player IDs (minimum 1, maximum 16 including yourself)

scores · array

Array of friend scores on the leaderboard

metadata · object

Pagination metadata

Example Request

curl -X POST https://api.scoresaber.com/scores/friend/leaderboard/123456/1 \
  -H "Content-Type: application/json" \
  -d '{"friendIds": ["76561198059961776", "76561198012345678"]}'

Example Response

{
  "scores": [
    {
      "rank": 42,
      "score": 987654,
      "accuracy": 95.5,
      "pp": 250.5,
      "player": {
        "id": "76561198059961776",
        "name": "Friend Name"
      }
    }
  ],
  "metadata": {
    "total": 2,
    "page": 1,
    "itemsPerPage": 12
  }
}

---

Get Top Scores

GET /scores/top/:page

Fetch the top scores across all leaderboards.

page · number · required

Page number for pagination (starts at 1)

scores · array

Array of top scores

metadata · object

Pagination metadata

Example Request

curl https://api.scoresaber.com/scores/top/1

Example Response

{
  "scores": [
    {
      "rank": 1,
      "score": 999999,
      "accuracy": 99.9,
      "pp": 500.0,
      "player": {
        "id": "76561198059961776",
        "name": "Top Player"
      },
      "leaderboard": {
        "id": 123456,
        "songName": "Hardest Song Ever",
        "difficulty": "ExpertPlus"
      }
    }
  ],
  "metadata": {
    "total": 10000,
    "page": 1,
    "itemsPerPage": 12
  }
}