Leaderboard Endpoints

API endpoints for searching and retrieving leaderboard information from ScoreSaber

Search Leaderboards

GET /leaderboard/search

Search ScoreSaber leaderboards with comprehensive filtering options.

page · number · default: "1"

Page number for pagination

ranked · boolean

Filter for ranked maps only

qualified · boolean

Filter for qualified maps only

verified · boolean

Filter for verified maps only

category · number

Category ID for filtering (e.g., 0 for trending, 1 for date ranked)

minStar · number

Minimum star difficulty

maxStar · number

Maximum star difficulty

sort · number

Sort order (0 for ascending, 1 for descending)

search · string

Search query for song name or mapper

leaderboards · array

Array of matching leaderboards

metadata · object

Pagination metadata including total results and current page

Example Request

curl "https://api.scoresaber.com/leaderboard/search?ranked=true&minStar=8&maxStar=10&search=reality"

Example Response

{
  "leaderboards": [
    {
      "id": 123456,
      "songName": "Reality Check Through The Skull",
      "songAuthorName": "DM DOKURO",
      "levelAuthorName": "Nuketime",
      "difficulty": "ExpertPlus",
      "stars": 9.12,
      "ranked": true,
      "qualified": false,
      "plays": 50000,
      "dailyPlays": 250
    }
  ],
  "metadata": {
    "total": 100,
    "page": 1,
    "itemsPerPage": 10
  }
}

---

Get Ranking Request Queue

GET /leaderboard/ranking-queue

Fetch the current ScoreSaber ranking request queue showing maps pending review.

requests · array

Array of ranking requests currently in the queue

Example Request

curl https://api.scoresaber.com/leaderboard/ranking-queue

Example Response

{
  "requests": [
    {
      "leaderboardId": 789456,
      "songName": "Pending Song",
      "levelAuthorName": "Mapper Name",
      "difficulty": "ExpertPlus",
      "requestedDate": "2024-01-01T12:00:00.000Z",
      "reviewPriority": 1
    }
  ]
}

---

Get Leaderboard by ID

GET /leaderboard/by-id/:leaderboardId

Fetch detailed leaderboard information by leaderboard ID, including BeatSaver data and star change history.

leaderboardId · number · required

The ScoreSaber leaderboard ID

leaderboard · object

Complete leaderboard information

beatSaver · object

BeatSaver map information including download URL, uploader, ratings

starChangeHistory · array

History of star rating changes for this leaderboard

Example Request

curl https://api.scoresaber.com/leaderboard/by-id/123456

Example Response

{
  "leaderboard": {
    "id": 123456,
    "songName": "Reality Check Through The Skull",
    "songSubName": "",
    "songAuthorName": "DM DOKURO",
    "levelAuthorName": "Nuketime",
    "difficulty": "ExpertPlus",
    "characteristic": "Standard",
    "stars": 9.12,
    "ranked": true,
    "qualified": false,
    "rankedDate": "2020-01-15T10:30:00.000Z",
    "plays": 50000,
    "dailyPlays": 250,
    "maxScore": 1234567
  },
  "beatSaver": {
    "hash": "abc123def456",
    "key": "1a2b3",
    "name": "Reality Check Through The Skull",
    "uploader": {
      "id": 12345,
      "name": "Nuketime"
    },
    "stats": {
      "downloads": 100000,
      "upvotes": 5000,
      "downvotes": 50,
      "score": 0.99
    },
    "downloadURL": "https://cdn.beatsaver.com/..."
  },
  "starChangeHistory": [
    {
      "date": "2020-01-15T10:30:00.000Z",
      "oldStars": 0,
      "newStars": 9.12
    },
    {
      "date": "2020-06-20T14:00:00.000Z",
      "oldStars": 9.12,
      "newStars": 9.45
    }
  ]
}

---

Get Leaderboard by Hash

GET /leaderboard/by-hash/:hash/:difficulty/:characteristic

Fetch leaderboard information by map hash, difficulty, and characteristic.

hash · string · required

The map hash (e.g., abc123def456)

difficulty · 'Easy' | 'Normal' | 'Hard' | 'Expert' | 'ExpertPlus' · required

The difficulty level

characteristic · 'Standard' | 'OneSaber' | 'NoArrows' | 'Lawless' | '90Degree' | '360Degree' | 'Lightshow' · required

The map characteristic

leaderboard · object

Complete leaderboard information

beatSaver · object

BeatSaver map information

starChangeHistory · array

History of star rating changes

Example Request

curl https://api.scoresaber.com/leaderboard/by-hash/abc123def456/ExpertPlus/Standard

Example Response

{
  "leaderboard": {
    "id": 123456,
    "songName": "Reality Check Through The Skull",
    "difficulty": "ExpertPlus",
    "characteristic": "Standard",
    "stars": 9.12,
    "ranked": true
  },
  "beatSaver": {
    "hash": "abc123def456",
    "key": "1a2b3",
    "name": "Reality Check Through The Skull"
  },
  "starChangeHistory": []
}

---

Get Play Count by HMD

GET /leaderboard/play-count-by-hmd/:leaderboardId

Fetch the play count breakdown by headset type for a specific leaderboard.

leaderboardId · number · required

The leaderboard ID

hmds · object

Object mapping HMD types to play counts

Example Request

curl https://api.scoresaber.com/leaderboard/play-count-by-hmd/123456

Example Response

{
  "hmds": {
    "Quest 3": 15000,
    "Quest 2": 12000,
    "Valve Index": 8000,
    "Rift S": 5000,
    "Vive Pro 2": 3000,
    "Quest Pro": 2500,
    "Windows Mixed Reality": 2000,
    "Quest": 1500,
    "Vive": 1000,
    "Unknown": 500
  }
}