> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/RealFascinated/scoresaber-reloaded/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<ParamField path="scoreId" type="string" required>
  The score ID
</ParamField>

<ResponseField name="score" type="object">
  Complete score information including player, leaderboard, and performance data
</ResponseField>

### Example Request

```bash theme={null}
curl https://api.scoresaber.com/scores/123456789
```

### Example Response

```json theme={null}
{
  "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.

<ParamField path="playerId" type="string" required>
  The ScoreSaber player ID
</ParamField>

<ParamField path="sort" type="'top' | 'recent'" required>
  Sort order: `top` for best scores or `recent` for most recent scores
</ParamField>

<ParamField path="page" type="number" required>
  Page number for pagination (starts at 1)
</ParamField>

<ParamField query="search" type="string">
  Search query to filter scores by song name
</ParamField>

<ParamField query="comparisonPlayerId" type="string">
  Another player's ID to compare scores against
</ParamField>

<ResponseField name="scores" type="array">
  Array of player scores from ScoreSaber
</ResponseField>

<ResponseField name="metadata" type="object">
  Pagination metadata
</ResponseField>

### Example Request

```bash theme={null}
curl "https://api.scoresaber.com/scores/player/scoresaber/76561198059961776/top/1?search=reality"
```

### Example Response

```json theme={null}
{
  "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.

<ParamField path="mode" type="'ssr' | 'medals'" required>
  Scoring mode: `ssr` for SSR scores or `medals` for medal-based filtering
</ParamField>

<ParamField path="playerId" type="string" required>
  The ScoreSaber player ID
</ParamField>

<ParamField path="field" type="'pp' | 'medals' | 'misses' | 'acc' | 'score' | 'maxcombo' | 'date'" required>
  Field to sort by
</ParamField>

<ParamField path="direction" type="'asc' | 'desc'" required>
  Sort direction: `asc` for ascending or `desc` for descending
</ParamField>

<ParamField path="page" type="number" required>
  Page number for pagination (starts at 1)
</ParamField>

<ParamField query="search" type="string">
  Search query to filter scores by song name
</ParamField>

<ParamField query="hmd" type="string">
  Filter by headset type (e.g., `Quest 3`, `Valve Index`, `Vive Pro 2`). See full list of supported HMDs in the HMD schema.
</ParamField>

<ParamField query="includePlayers" type="string | string[]">
  Comma-separated player IDs or array of player IDs to include in results
</ParamField>

<ResponseField name="scores" type="array">
  Array of filtered and sorted scores
</ResponseField>

<ResponseField name="metadata" type="object">
  Pagination and filter metadata
</ResponseField>

### Example Request

```bash theme={null}
curl "https://api.scoresaber.com/scores/player/ssr/76561198059961776/pp/desc/1?hmd=Quest%203"
```

### Example Response

```json theme={null}
{
  "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.

<ParamField path="playerId" type="string" required>
  The ScoreSaber player ID
</ParamField>

<ParamField path="leaderboardId" type="number" required>
  The leaderboard ID
</ParamField>

<ResponseField name="history" type="array">
  Array of score history data points for graphing
</ResponseField>

### Example Request

```bash theme={null}
curl https://api.scoresaber.com/scores/history-graph/76561198059961776/123456
```

### Example Response

```json theme={null}
{
  "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.

<ParamField path="leaderboardId" type="number" required>
  The leaderboard ID
</ParamField>

<ParamField path="page" type="number" required>
  Page number for pagination (starts at 1)
</ParamField>

<ParamField query="country" type="string">
  Two-letter country code to filter scores (e.g., `US`, `GB`, `JP`)
</ParamField>

<ResponseField name="scores" type="array">
  Array of scores on the leaderboard
</ResponseField>

<ResponseField name="metadata" type="object">
  Pagination metadata
</ResponseField>

### Example Request

```bash theme={null}
curl https://api.scoresaber.com/scores/leaderboard/123456/1?country=US
```

### Example Response

```json theme={null}
{
  "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.

<ParamField path="leaderboardId" type="number" required>
  The leaderboard ID
</ParamField>

<ParamField path="page" type="number" required>
  Page number for pagination (starts at 1)
</ParamField>

<ParamField body="friendIds" type="string[]" required>
  Array of friend player IDs (minimum 1, maximum 16 including yourself)
</ParamField>

<ResponseField name="scores" type="array">
  Array of friend scores on the leaderboard
</ResponseField>

<ResponseField name="metadata" type="object">
  Pagination metadata
</ResponseField>

### Example Request

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

### Example Response

```json theme={null}
{
  "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.

<ParamField path="page" type="number" required>
  Page number for pagination (starts at 1)
</ParamField>

<ResponseField name="scores" type="array">
  Array of top scores
</ResponseField>

<ResponseField name="metadata" type="object">
  Pagination metadata
</ResponseField>

### Example Request

```bash theme={null}
curl https://api.scoresaber.com/scores/top/1
```

### Example Response

```json theme={null}
{
  "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
  }
}
```