Search Leaderboards
GET /leaderboard/search
Search ScoreSaber leaderboards with comprehensive filtering options.
Page number for pagination
Filter for ranked maps only
Filter for qualified maps only
Filter for verified maps only
Category ID for filtering (e.g., 0 for trending, 1 for date ranked)
Sort order (0 for ascending, 1 for descending)
Search query for song name or mapper
Array of matching leaderboards
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.
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.
The ScoreSaber leaderboard ID
Complete leaderboard information
BeatSaver map information including download URL, uploader, ratings
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.
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
Complete leaderboard information
BeatSaver map information
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.
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
}
}