Skip to main content

​
Get Player Profile

GET /player/:playerId Fetch a ScoreSaber player profile with optional detail level.
​
playerId
string
required
The ScoreSaber player ID
​
type
'basic' | 'full'
default:"basic"
Detail level for the response. Use basic for minimal data or full for complete profile information
​
player
object
The player profile data from ScoreSaber

​
Example Request

curl https://api.scoresaber.com/player/76561198059961776?type=full

​
Example Response

{
  "id": "76561198059961776",
  "name": "Player Name",
  "profilePicture": "https://...",
  "country": "US",
  "pp": 12345.67,
  "rank": 1000,
  "countryRank": 100
}

​
Get Player Score Chart

GET /player/scores-chart/:playerId Fetch player score chart data for visualization.
​
playerId
string
required
The ScoreSaber player ID
​
scores
array
Array of score data points for chart rendering

​
Example Request

curl https://api.scoresaber.com/player/scores-chart/76561198059961776

​
Example Response

{
  "scores": [
    {"date": "2024-01-01", "pp": 100.5},
    {"date": "2024-01-02", "pp": 105.2}
  ]
}

​
Get Player PP Values

GET /player/pps/:playerId Fetch player’s performance points (PP) breakdown.
​
playerId
string
required
The ScoreSaber player ID
​
pps
array
Array of PP values for the player’s ranked scores

​
Example Request

curl https://api.scoresaber.com/player/pps/76561198059961776

​
Example Response

{
  "pps": [250.5, 245.3, 240.1, 235.8]
}

​
Refresh Player Data

GET /player/refresh/:playerId Refresh player data from ScoreSaber to get the latest information.
​
playerId
string
required
The ScoreSaber player ID
​
player
object
The refreshed player profile data

​
Example Request

curl https://api.scoresaber.com/player/refresh/76561198059961776

​
Example Response

{
  "success": true,
  "player": {
    "id": "76561198059961776",
    "name": "Player Name",
    "pp": 12345.67
  }
}

​
Get Player Mini Rankings

GET /player/mini-ranking/:playerId Fetch player’s mini-ranking data.
​
playerId
string
required
The ScoreSaber player ID
​
rankings
array
Array of mini-ranking data

​
Example Request

curl https://api.scoresaber.com/player/mini-ranking/76561198059961776

​
Example Response

{
  "rankings": [
    {"category": "speed", "rank": 500},
    {"category": "accuracy", "rank": 300}
  ]
}

​
Search Players

GET /player/search Search for players by name or ID.
​
query
string
Search query string (player name or ID)
​
players
array
Array of matching player profiles

​
Example Request

curl https://api.scoresaber.com/player/search?query=PlayerName

​
Example Response

{
  "players": [
    {
      "id": "76561198059961776",
      "name": "PlayerName",
      "profilePicture": "https://...",
      "country": "US"
    }
  ]
}

​
Get Player Statistics History

GET /player/history/:playerId Fetch player’s statistics history over a date range.
​
playerId
string
required
The ScoreSaber player ID
​
startDate
string
default:"Current date"
Start date in ISO format (e.g., 2024-01-01T00:00:00.000Z)
​
endDate
string
default:"50 days ago"
End date in ISO format (e.g., 2024-02-20T00:00:00.000Z)
​
history
array
Array of historical statistic data points

​
Example Request

curl "https://api.scoresaber.com/player/history/76561198059961776?startDate=2024-01-01T00:00:00.000Z&endDate=2024-02-01T00:00:00.000Z"

​
Example Response

{
  "history": [
    {
      "date": "2024-01-01",
      "rank": 1000,
      "countryRank": 100,
      "pp": 12345.67
    },
    {
      "date": "2024-01-02",
      "rank": 995,
      "countryRank": 98,
      "pp": 12350.45
    }
  ]
}

​
Get Player Score History

GET /player/score-history/:playerId/:leaderboardId/:page Fetch a player’s score history for a specific leaderboard.
​
playerId
string
required
The ScoreSaber player ID
​
leaderboardId
number
required
The leaderboard ID
​
page
number
required
Page number for pagination (starts at 1)
​
scores
array
Array of historical scores for the leaderboard
​
metadata
object
Pagination metadata including total pages and current page

​
Example Request

curl https://api.scoresaber.com/player/score-history/76561198059961776/123456/1

​
Example Response

{
  "scores": [
    {
      "scoreId": "1",
      "score": 987654,
      "accuracy": 95.5,
      "pp": 250.5,
      "timeSet": "2024-01-01T12:00:00.000Z"
    }
  ],
  "metadata": {
    "total": 1,
    "page": 1,
    "itemsPerPage": 12
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us