v2.scores.list_v3

GET /v2/beatmaps/{beatmap}/scores

GET /v2/beatmaps/{beatmap}/scores/users/{user}

GET /v2/beatmaps/{beatmap}/scores/users/{user}/all

GET /v2/beatmaps/{beatmap}/solo-scores

async Retrieves a list of scores by given parameters.

Usage example

const { auth, v2 } = require('osu-api-extended');

async function main() {
  try {
    await auth.login({
      type: 'v2',
      client_id: CLIENT_ID,
      client_secret: CLIENT_SECRET,
      cachedTokenPath: './test.json' // path to the file your auth token will be saved (to prevent osu!api spam)
    });

    const result = await v2.scores.list({
      type: 'user_beatmap_all',
      // or
      type: 'user_beatmap_best',
      beatmap_id: 1141858,
      user_id: 7562902
    });
    // or
    const result = await v2.scores.list({
      type: 'leaderboard',
      beatmap_id: 1141858
    });
    // or
    const result = await v2.scores.list({
      type: 'user_best',
      // or
      type: 'user_firsts',
      // or
      type: 'user_pinned',
      // or
      type: 'user_recent',
      user_id: 7562902,
    });
    if (result.error != null) {
      console.log(result.error);
      return;
    };

    console.log(result);
  } catch (error) {
    console.log(error);
  };
};

main();

Parameter	Type	Description
params.type	'leaderboard' or 'solo_scores' or 'user_beatmap_best' or 'user_beatmap_all' or 'user_best' or 'user_firsts' or 'user_recent' or 'user_pinned'
params.mode?	Modes_names
params.leaderboard_type?	'global'	'country'
params.beatmap_id?	number
params.mods?	string[]
params.user_id?	number
params.include_fails?	boolean
params.offset?	number
params.limit?	number
addons.legacy_only?	boolean
addons.apiVersion?	'20240130'	'99999999'
addons.authKey?	string
addons.timeout_ms?	number
addons.ignoreSessionRefresh?	boolean

Parameter	Type	Description
r	any
index	number

Parameter	Type	Description
r	any
index	number

Response

Types for type: leaderboard

import { Mod } from "../mods"

export interface ScoresListLeaderboardResponse {
 ranked: boolean
 preserve: boolean
 processed: boolean
 maximum_statistics: MaximumStatistics
 mods: Mod[]
 statistics: Statistics
 beatmap_id: number
 best_id: any
 id: number
 rank: string
 type: string
 user_id: number
 accuracy: number
 build_id?: number
 ended_at: string
 has_replay: boolean
 is_perfect_combo: boolean
 legacy_perfect: boolean
 legacy_score_id?: number
 legacy_total_score: number
 max_combo: number
 passed: boolean
 pp?: number
 ruleset_id: number
 started_at?: string
 total_score: number
 replay: boolean
 current_user_attributes: CurrentUserAttributes
 user: User
 index: number
}

export interface MaximumStatistics {
 great: number
 legacy_combo_increase?: number
 ignore_hit?: number
 slider_tail_hit?: number
}


export interface Statistics {
 perfect?: number
 good?: number
 ok?: number
 great?: number
 meh?: number
 miss?: number
 ignore_hit?: number
 ignore_miss?: number
 slider_tail_hit?: number
}

export interface CurrentUserAttributes {
 pin: any
}

export interface User {
 avatar_url: string
 country_code: string
 default_group: string
 id: number
 is_active: boolean
 is_bot: boolean
 is_deleted: boolean
 is_online: boolean
 is_supporter: boolean
 last_visit?: string
 pm_friends_only: boolean
 profile_colour: any
 username: string
 country: Country
 cover: Cover
}

export interface Country {
 code: string
 name: string
}

export interface Cover {
 custom_url?: string
 url: string
 id?: string
}

Types for type: solo_scores

import { Mod } from "../mods"

export interface ScoresListSoloScoresResponse {
 ranked: boolean
 preserve: boolean
 processed: boolean
 maximum_statistics: MaximumStatistics
 mods: Mod[]
 statistics: Statistics
 beatmap_id: number
 best_id: any
 id: number
 rank: string
 type: string
 user_id: number
 accuracy: number
 build_id?: number
 ended_at: string
 has_replay: boolean
 is_perfect_combo: boolean
 legacy_perfect: boolean
 legacy_score_id?: number
 legacy_total_score: number
 max_combo: number
 passed: boolean
 pp?: number
 ruleset_id: number
 started_at?: string
 total_score: number
 replay: boolean
 current_user_attributes: CurrentUserAttributes
 user: User
 index: number
}

export interface MaximumStatistics {
 great?: number
 ignore_hit?: number
 slider_tail_hit?: number
 legacy_combo_increase?: number
 perfect?: number
}

export interface Statistics {
 perfect?: number
 good?: number
 ok?: number
 great?: number
 meh?: number
 miss?: number
 ignore_hit?: number
 slider_tail_hit?: number
 ignore_miss?: number
}

export interface CurrentUserAttributes {
 pin: any
}

export interface User {
 avatar_url: string
 country_code: string
 default_group: string
 id: number
 is_active: boolean
 is_bot: boolean
 is_deleted: boolean
 is_online: boolean
 is_supporter: boolean
 last_visit?: string
 pm_friends_only: boolean
 profile_colour?: string
 username: string
 country: Country
 cover: Cover
}

export interface Country {
 code: string
 name: string
}

export interface Cover {
 custom_url?: string
 url: string
 id?: string
}

Types for type: user_beatmap_best

import { Mod } from "../mods"

export interface ScoresListBeatmapBestResponse {
 position: number
 score: Score
}

export interface Score {
 ranked: boolean
 preserve: boolean
 processed: boolean
 maximum_statistics: MaximumStatistics
 mods: Mod[]
 statistics: Statistics
 beatmap_id: number
 best_id: any
 id: number
 rank: string
 type: string
 user_id: number
 accuracy: number
 build_id: any
 ended_at: string
 has_replay: boolean
 is_perfect_combo: boolean
 legacy_perfect: boolean
 legacy_score_id: number
 legacy_total_score: number
 max_combo: number
 passed: boolean
 pp: number
 ruleset_id: number
 started_at: any
 total_score: number
 replay: boolean
 current_user_attributes: CurrentUserAttributes
 beatmap: Beatmap
 user: User
}

export interface MaximumStatistics {
 great: number
 legacy_combo_increase: number
}

export interface Statistics {
 perfect?: number
 good?: number
 ok?: number
 great?: number
 meh?: number
 miss?: number
}

export interface CurrentUserAttributes {
 pin: any
}

export interface Beatmap {
 beatmapset_id: number
 difficulty_rating: number
 id: number
 mode: string
 status: string
 total_length: number
 user_id: number
 version: string
 accuracy: number
 ar: number
 bpm: number
 convert: boolean
 count_circles: number
 count_sliders: number
 count_spinners: number
 cs: number
 deleted_at: any
 drain: number
 hit_length: number
 is_scoreable: boolean
 last_updated: string
 mode_int: number
 passcount: number
 playcount: number
 ranked: number
 url: string
 checksum: string
}

export interface User {
 avatar_url: string
 country_code: string
 default_group: string
 id: number
 is_active: boolean
 is_bot: boolean
 is_deleted: boolean
 is_online: boolean
 is_supporter: boolean
 last_visit: string
 pm_friends_only: boolean
 profile_colour: any
 username: string
 country: Country
 cover: Cover
}

export interface Country {
 code: string
 name: string
}

export interface Cover {
 custom_url: string
 url: string
 id: any
}

Types for type: user_beatmap_all

import { Mod } from "../mods"

export interface ScoresListBeatmapAllResponse {
 ranked: boolean
 preserve: boolean
 processed: boolean
 maximum_statistics: MaximumStatistics
 mods: Mod[]
 statistics: Statistics
 beatmap_id: number
 best_id: any
 id: number
 rank: string
 type: string
 user_id: number
 accuracy: number
 build_id: any
 ended_at: string
 has_replay: boolean
 is_perfect_combo: boolean
 legacy_perfect: boolean
 legacy_score_id: number
 legacy_total_score: number
 max_combo: number
 passed: boolean
 pp: number
 ruleset_id: number
 started_at: any
 total_score: number
 replay: boolean
 current_user_attributes: CurrentUserAttributes
 index: number
}

export interface MaximumStatistics {
 great: number
 legacy_combo_increase: number
}


export interface Statistics {
 perfect?: number
 good?: number
 ok?: number
 great?: number
 meh?: number
 miss?: number
}

export interface CurrentUserAttributes {
 pin: any
}

Types for type: user_best

import { Mod } from "../mods"

export interface ScoresListUserBestResponse {
 ranked: boolean
 preserve: boolean
 processed: boolean
 maximum_statistics: MaximumStatistics
 mods: Mod[]
 statistics: Statistics
 beatmap_id: number
 best_id: any
 id: number
 rank: string
 type: string
 user_id: number
 accuracy: number
 build_id?: number
 ended_at: string
 has_replay: boolean
 is_perfect_combo: boolean
 legacy_perfect: boolean
 legacy_score_id?: number
 legacy_total_score: number
 max_combo: number
 passed: boolean
 pp: number
 ruleset_id: number
 started_at?: string
 total_score: number
 replay: boolean
 current_user_attributes: CurrentUserAttributes
 beatmap: Beatmap
 beatmapset: Beatmapset
 user: User
 weight: Weight
 index: number
}

export interface MaximumStatistics {
 great: number
 legacy_combo_increase?: number
 ignore_hit?: number
 large_bonus?: number
 small_bonus?: number
 large_tick_hit?: number
 slider_tail_hit?: number
}

export interface Statistics {
 perfect?: number
 good?: number
 ok?: number
 great?: number
 meh?: number
 miss?: number
 ignore_hit?: number
 ignore_miss?: number
 small_bonus?: number
 large_tick_hit?: number
 slider_tail_hit?: number
}

export interface CurrentUserAttributes {
 pin: any
}

export interface Beatmap {
 beatmapset_id: number
 difficulty_rating: number
 id: number
 mode: string
 status: string
 total_length: number
 user_id: number
 version: string
 accuracy: number
 ar: number
 bpm: number
 convert: boolean
 count_circles: number
 count_sliders: number
 count_spinners: number
 cs: number
 deleted_at: any
 drain: number
 hit_length: number
 is_scoreable: boolean
 last_updated: string
 mode_int: number
 passcount: number
 playcount: number
 ranked: number
 url: string
 checksum: string
}

export interface Beatmapset {
 artist: string
 artist_unicode: string
 covers: Covers
 creator: string
 favourite_count: number
 hype: any
 id: number
 nsfw: boolean
 offset: number
 play_count: number
 preview_url: string
 source: string
 spotlight: boolean
 status: string
 title: string
 title_unicode: string
 track_id?: number
 user_id: number
 video: boolean
}

export interface Covers {
 cover: string
 "cover@2x": string
 card: string
 "card@2x": string
 list: string
 "list@2x": string
 slimcover: string
 "slimcover@2x": string
}

export interface User {
 avatar_url: string
 country_code: string
 default_group: string
 id: number
 is_active: boolean
 is_bot: boolean
 is_deleted: boolean
 is_online: boolean
 is_supporter: boolean
 last_visit: any
 pm_friends_only: boolean
 profile_colour: any
 username: string
}

export interface Weight {
 percentage: number
 pp: number
}

Types for type: user_firsts

import { Mod } from "../mods"

export interface ScoresListUserFirstsResponse {
 ranked: boolean
 preserve: boolean
 processed: boolean
 maximum_statistics: MaximumStatistics
 mods: Mod[]
 statistics: Statistics
 beatmap_id: number
 best_id: any
 id: number
 rank: string
 type: string
 user_id: number
 accuracy: number
 build_id: any
 ended_at: string
 has_replay: boolean
 is_perfect_combo: boolean
 legacy_perfect: boolean
 legacy_score_id: number
 legacy_total_score: number
 max_combo: number
 passed: boolean
 pp?: number
 ruleset_id: number
 started_at: any
 total_score: number
 replay: boolean
 current_user_attributes: CurrentUserAttributes
 beatmap: Beatmap
 beatmapset: Beatmapset
 user: User
 index: number
}

export interface MaximumStatistics {
 great: number
 legacy_combo_increase: number
}

export interface Statistics {
 perfect?: number
 good?: number
 ok?: number
 great?: number
 meh?: number
 miss?: number
}

export interface CurrentUserAttributes {
 pin: any
}

export interface Beatmap {
 beatmapset_id: number
 difficulty_rating: number
 id: number
 mode: string
 status: string
 total_length: number
 user_id: number
 version: string
 accuracy: number
 ar: number
 bpm: number
 convert: boolean
 count_circles: number
 count_sliders: number
 count_spinners: number
 cs: number
 deleted_at: any
 drain: number
 hit_length: number
 is_scoreable: boolean
 last_updated: string
 mode_int: number
 passcount: number
 playcount: number
 ranked: number
 url: string
 checksum: string
}

export interface Beatmapset {
 artist: string
 artist_unicode: string
 covers: Covers
 creator: string
 favourite_count: number
 hype: any
 id: number
 nsfw: boolean
 offset: number
 play_count: number
 preview_url: string
 source: string
 spotlight: boolean
 status: string
 title: string
 title_unicode: string
 track_id?: number
 user_id: number
 video: boolean
}

export interface Covers {
 cover: string
 "cover@2x": string
 card: string
 "card@2x": string
 list: string
 "list@2x": string
 slimcover: string
 "slimcover@2x": string
}

export interface User {
 avatar_url: string
 country_code: string
 default_group: string
 id: number
 is_active: boolean
 is_bot: boolean
 is_deleted: boolean
 is_online: boolean
 is_supporter: boolean
 last_visit: string
 pm_friends_only: boolean
 profile_colour: any
 username: string
}

Types for type: user_recent

import { Mod } from "../mods"

export interface ScoresListUserRecentResponse {
 ranked: boolean
 preserve: boolean
 processed: boolean
 maximum_statistics: MaximumStatistics
 mods: Mod[]
 statistics: Statistics
 beatmap_id: number
 best_id: any
 id: number
 rank: string
 type: string
 user_id: number
 accuracy: number
 build_id: any
 ended_at: string
 has_replay: boolean
 is_perfect_combo: boolean
 legacy_perfect: boolean
 legacy_score_id: number
 legacy_total_score: number
 max_combo: number
 passed: boolean
 pp?: number
 ruleset_id: number
 started_at: any
 total_score: number
 replay: boolean
 current_user_attributes: CurrentUserAttributes
 beatmap: Beatmap
 beatmapset: Beatmapset
 user: User
 index: number
}

export interface MaximumStatistics {
 great: number
 legacy_combo_increase: number
}


export interface Statistics {
 perfect?: number
 good?: number
 ok?: number
 great?: number
 meh?: number
 miss?: number
}

export interface CurrentUserAttributes {
 pin: any
}

export interface Beatmap {
 beatmapset_id: number
 difficulty_rating: number
 id: number
 mode: string
 status: string
 total_length: number
 user_id: number
 version: string
 accuracy: number
 ar: number
 bpm: number
 convert: boolean
 count_circles: number
 count_sliders: number
 count_spinners: number
 cs: number
 deleted_at: any
 drain: number
 hit_length: number
 is_scoreable: boolean
 last_updated: string
 mode_int: number
 passcount: number
 playcount: number
 ranked: number
 url: string
 checksum: string
}

export interface Beatmapset {
 artist: string
 artist_unicode: string
 covers: Covers
 creator: string
 favourite_count: number
 hype: any
 id: number
 nsfw: boolean
 offset: number
 play_count: number
 preview_url: string
 source: string
 spotlight: boolean
 status: string
 title: string
 title_unicode: string
 track_id?: number
 user_id: number
 video: boolean
}

export interface Covers {
 cover: string
 "cover@2x": string
 card: string
 "card@2x": string
 list: string
 "list@2x": string
 slimcover: string
 "slimcover@2x": string
}

export interface User {
 avatar_url: string
 country_code: string
 default_group: string
 id: number
 is_active: boolean
 is_bot: boolean
 is_deleted: boolean
 is_online: boolean
 is_supporter: boolean
 last_visit: string
 pm_friends_only: boolean
 profile_colour: any
 username: string
}

Types for type: user_pinned

import { Mod } from "../mods"

export interface ScoresListUserPinnedResponse {
 ranked: boolean
 preserve: boolean
 processed: boolean
 maximum_statistics: MaximumStatistics
 mods: Mod[]
 statistics: Statistics
 beatmap_id: number
 best_id: any
 id: number
 rank: string
 type: string
 user_id: number
 accuracy: number
 build_id: any
 ended_at: string
 has_replay: boolean
 is_perfect_combo: boolean
 legacy_perfect: boolean
 legacy_score_id: number
 legacy_total_score: number
 max_combo: number
 passed: boolean
 pp: number
 ruleset_id: number
 started_at: any
 total_score: number
 replay: boolean
 current_user_attributes: CurrentUserAttributes
 beatmap: Beatmap
 beatmapset: Beatmapset
 user: User
 index: number
}

export interface MaximumStatistics {
 great: number
 legacy_combo_increase: number
}


export interface Statistics {
 perfect?: number
 good?: number
 ok?: number
 great?: number
 meh?: number
 miss?: number
}

export interface CurrentUserAttributes {
 pin: any
}

export interface Beatmap {
 beatmapset_id: number
 difficulty_rating: number
 id: number
 mode: string
 status: string
 total_length: number
 user_id: number
 version: string
 accuracy: number
 ar: number
 bpm: number
 convert: boolean
 count_circles: number
 count_sliders: number
 count_spinners: number
 cs: number
 deleted_at: any
 drain: number
 hit_length: number
 is_scoreable: boolean
 last_updated: string
 mode_int: number
 passcount: number
 playcount: number
 ranked: number
 url: string
 checksum: string
}

export interface Beatmapset {
 artist: string
 artist_unicode: string
 covers: Covers
 creator: string
 favourite_count: number
 hype: any
 id: number
 nsfw: boolean
 offset: number
 play_count: number
 preview_url: string
 source: string
 spotlight: boolean
 status: string
 title: string
 title_unicode: string
 track_id: any
 user_id: number
 video: boolean
}

export interface Covers {
 cover: string
 "cover@2x": string
 card: string
 "card@2x": string
 list: string
 "list@2x": string
 slimcover: string
 "slimcover@2x": string
}

export interface User {
 avatar_url: string
 country_code: string
 default_group: string
 id: number
 is_active: boolean
 is_bot: boolean
 is_deleted: boolean
 is_online: boolean
 is_supporter: boolean
 last_visit: string
 pm_friends_only: boolean
 profile_colour: any
 username: string
}