Skip to main content

​
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
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us