API Reference

Enums

class ProfilePage

BEATMAPS: str = "beatmaps"

HISTORICAL: str = "historical"

KUDOSU: str = "kudosu"

ME: str = "me"

MEDALS: str = "medals"

RECENT_ACTIVITY: str = "recent_activity"

TOP_RANKS: str = "top_ranks"

class GameMode

CATCH: str = "fruits"

MANIA: str = "mania"

OSU: str = "osu"

TAIKO: str = "taiko"

class PlayStyles

KEYBOARD: int = 2

MOUSE: int = 1

TABLET: int = 4

TOUCH: int = 8

class RankStatus

APPROVED: int = 2

GRAVEYARD: int = -2

LOVED: int = 4

PENDING: int = 0

QUALIFIED: int = 3

RANKED: int = 1

WIP: int = -1

class UserAccountHistoryType

NOTE: str = "note"

RESTRICTION: str = "restriction"

SILENCE: str = "silence"

TOURNAMENT_BAN: str = "tournament_ban"

class MessageType

HYPE: str = "hype"

MAPPER_NOTE: str = "mapper_note"

PRAISE: str = "praise"

PROBLEM: str = "problem"

REVIEW: str = "review"

SUGGESTION: str = "suggestion"

class BeatmapsetEventType

APPROVE: str = "approve"

BEATMAP_OWNER_CHANGE: str = "beatmap_owner_change"

DISCUSSION_DELETE: str = "discussion_delete"

DISCUSSION_LOCK: str = "discussion_lock"

DISCUSSION_POST_DELETE: str = "discussion_post_delete"

DISCUSSION_POST_RESTORE: str = "discussion_post_restore"

DISCUSSION_RESTORE: str = "discussion_restore"

DISCUSSION_UNLOCK: str = "discussion_unlock"

DISQUALIFY: str = "disqualify"

DISQUALIFY_LEGACY: str = "disqualify_legacy"

GENRE_EDIT: str = "genre_edit"

ISSUE_REOPEN: str = "issue_reopen"

ISSUE_RESOLVE: str = "issue_resolve"

KUDOSU_ALLOW: str = "kudosu_allow"

KUDOSU_DENY: str = "kudosu_deny"

KUDOSU_GAIN: str = "kudosu_gain"

KUDOSU_LOST: str = "kudosu_lost"

KUDOSU_RECALCULATE: str = "kudosu_recalculate"

LANGUAGE_EDIT: str = "language_edit"

LOVE: str = "love"

NOMINATE: str = "nominate"

NOMINATE_MODES: str = "nominate_modes"

NOMINATION_RESET: str = "nomination_reset"

NOMINATION_RESET_RECEIVED: str = "nomination_reset_received"

NSFW_TOGGLE: str = "nsfw_toggle"

QUALIFY: str = "qualify"

RANK: str = "rank"

REMOVE_FROM_LOVED: str = "remove_from_loved"

class BeatmapsetDownload

ALL: str = "all"

DIRECT: str = "direct"

NO_VIDEO: str = "no_video"

class UserListFilters

ALL: str = "all"

OFFLINE: str = "offline"

ONLINE: str = "online"

class UserListSorts

LAST_VISIT: str = "last_visit"

RANK: str = "rank"

USERNAME: str = "username"

class UserListViews

BRICK: str = "brick"

CARD: str = "card"

LIST: str = "list"

class KudosuAction

GIVE: str = "vote.give"

RESET: str = "vote.reset"

REVOKE: str = "vote.revoke"

class EventType

ACHIEVEMENT: str = "achievement"

BEATMAPSET_APPROVE: str = "beatmapsetApprove"

BEATMAPSET_DELETE: str = "beatmapsetDelete"

BEATMAPSET_REVIVE: str = "beatmapsetRevive"

BEATMAPSET_UPDATE: str = "beatmapsetUpdate"

BEATMAPSET_UPLOAD: str = "beatmapsetUpload"

BEATMAP_PLAYCOUNT: str = "beatmapPlaycount"

RANK: str = "rank"

RANK_LOST: str = "rankLost"

USERNAME_CHANGE: str = "usernameChange"

USER_SUPPORT_AGAIN: str = "userSupportAgain"

USER_SUPPORT_FIRST: str = "userSupportFirst"

USER_SUPPORT_GIFT: str = "userSupportGift"

class BeatmapsetApproval

APPROVED: str = "approved"

LOVED: str = "loved"

QUALIFIED: str = "qualified"

RANKED: str = "ranked"

class ForumTopicType

ANNOUNCEMENT: str = "announcement"

NORMAL: str = "normal"

STICKY: str = "sticky"

class ChangelogMessageFormat

HTML: str = "html"

MARKDOWN: str = "markdown"

class UserRelationType

BLOCK: str = "block"

FRIEND: str = "friend"

class Grade

A: str = "A"

B: str = "B"

C: str = "C"

D: str = "D"

F: str = "F"

S: str = "S"

SH: str = "SH"

SS: str = "X"

SSH: str = "XH"

class RoomType

HEAD_TO_HEAD: str = "head_to_head"

PLAYLISTS: str = "playlists"

TEAM_VERSUS: str = "team_versus"

class RoomCategory

FEATURED_ARTIST: str = "featured_artist"

NORMAL: str = "normal"

SPOTLIGHT: str = "spotlight"

class MatchEventType

HOST_CHANGED: str = "host-changed"

MATCH_CREATED: str = "match-created"

MATCH_DISBANDED: str = "match-disbanded"

OTHER: str = "other"

PLAYER_JOINED: str = "player-joined"

PLAYER_KICKED: str = "player-kicked"

PLAYER_LEFT: str = "player-left"

class ScoringType

ACCURACY: str = "accuracy"

COMBO: str = "combo"

SCORE: str = "score"

SCORE_V2: str = "scorev2"

class TeamType

HEAD_TO_HEAD: str = "head-to-head"

TAG_COOP: str = "tag-coop"

TAG_TEAM_VS: str = "tag-team-vs"

TEAM_VS: str = "team-vs"

class Variant

KEY_4: str = "4k"

KEY_7: str = "7k"

class ScoreType

BEST: str = "best"

FIRSTS: str = "firsts"

RECENT: str = "recent"

class RankingFilter

ALL: str = "all"

FRIENDS: str = "friends"

class RankingType

CHARTS: str = "charts"

COUNTRY: str = "country"

PERFORMANCE: str = "performance"

SCORE: str = "score"

class UserLookupKey

ID: str = "id"

USERNAME: str = "username"

class UserBeatmapType

FAVOURITE: str = "favourite"

GRAVEYARD: str = "graveyard"

GUEST: str = "guest"

LOVED: str = "loved"

MOST_PLAYED: str = "most_played"

NOMINATED: str = "nominated"

PENDING: str = "pending"

RANKED: str = "ranked"

class BeatmapDiscussionPostSort

NEW: str = "id_desc"

OLD: str = "id_asc"

class BeatmapsetStatus

ALL: str = "all"

DISQUALIFIED: str = "disqualified"

NEVER_QUALIFIED: str = "never_qualified"

QUALIFIED: str = "qualified"

RANKED: str = "ranked"

class ChannelType

ANNOUNCE: str = "ANNOUNCE"

GROUP: str = "GROUP"

MULTIPLAYER: str = "MULTIPLAYER"

PM: str = "PM"

PRIVATE: str = "PRIVATE"

PUBLIC: str = "PUBLIC"

SPECTATOR: str = "SPECTATOR"

TEMPORARY: str = "TEMPORARY"

class CommentableType

BEATMAPSET: str = "beatmapset"

CHANGELOG: str = "build"

NEWS_POST: str = "news_post"

class CommentSort

NEW: str = "new"

OLD: str = "old"

TOP: str = "top"

class ForumTopicSort

NEW: str = "id_desc"

OLD: str = "id_asc"

class SearchMode

ALL: str = "all"

USERS: str = "user"

WIKI: str = "wiki_page"

class MultiplayerScoresSort

NEW: str = "score_desc"

OLD: str = "score_asc"

class BeatmapsetDiscussionVote

DOWNVOTE: int = -1

UPVOTE: int = 1

class BeatmapsetDiscussionVoteSort

NEW: str = "id_desc"

OLD: str = "id_asc"

class BeatmapsetSearchCategory

ANY: str = "any"

FAVOURITES: str = "favourites"

GRAVEYARD: str = "graveyard"

HAS_LEADERBOARD: str = "leaderboard"

LOVED: str = "loved"

MY_MAPS: str = "mine"

PENDING: str = "pending"

QUALIFIED: str = "qualified"

RANKED: str = "ranked"

WIP: str = "wip"

class BeatmapsetSearchMode

ANY: int = -1

CATCH: int = 2

MANIA: int = 3

OSU: int = 0

TAIKO: int = 1

class BeatmapsetSearchExplicitContent

HIDE: str = "hide"

SHOW: str = "show"

class BeatmapsetSearchGenre

ANIME: int = 3

ANY: int = 0

CLASSICAL: int = 12

ELECTRONIC: int = 10

FOLK: int = 13

HIP_HOP: int = 9

JAZZ: int = 14

METAL: int = 11

NOVELTY: int = 7

OTHER: int = 6

POP: int = 5

ROCK: int = 4

UNSPECIFIED: int = 1

VIDEO_GAME: int = 2

class BeatmapsetSearchLanguage

ANY: int = 0

CHINESE: int = 4

ENGLISH: int = 2

FRENCH: int = 7

GERMAN: int = 8

INSTRUMENTAL: int = 5

ITALIAN: int = 11

JAPANESE: int = 3

KOREAN: int = 6

OTHER: int = 14

POLISH: int = 13

RUSSIAN: int = 12

SPANISH: int = 10

SWEDISH: int = 9

UNSPECIFIED: int = 1

class BeatmapsetSearchSort

ARTIST_ASCENDING: str = "artist_asc"

ARTIST_DESCENDING: str = "artist_desc"

DIFFICULTY_ASCENDING: str = "difficulty_asc"

DIFFICULTY_DESCENDING: str = "difficulty_desc"

FAVORITES_ASCENDING: str = "favourites_asc"

FAVORITES_DESCENDING: str = "favourites_desc"

PLAYS_ASCENDING: str = "plays_asc"

PLAYS_DESCENDING: str = "plays_desc"

RANKED_ASCENDING: str = "ranked_asc"

RANKED_DESCENDING: str = "ranked_desc"

RATING_ASCENDING: str = "rating_asc"

RATING_DESCENDING: str = "rating_desc"

TITLE_ASCENDING: str = "title_asc"

TITLE_DESCENDING: str = "title_desc"

class NewsPostKey

ID: str = "id"

SLUG: str = "slug"

class RoomSearchMode

ACTIVE: str = "active"

ALL: str = "all"

ENDED: str = "ended"

OWNED: str = "owned"

PARTICIPATED: str = "participated"

class EventsSort

NEW: str = "id_desc"

OLD: str = "id_asc"

class BeatmapPackType

ARTIST: str = "artist"

CHART: str = "chart"

FEATURED: str = "featured"

LOVED: str = "loved"

STANDARD: str = "standard"

THEME: str = "theme"

TOURNAMENT: str = "tournament"

class Failtimes

exit: list[int] | None

fail: list[int] | None

class Ranking

active_users: int

performance: int

play_count: int

ranked_score: int

class Country

code: str

display: int | None

name: str

ranking: Ranking | None

class Cover

custom_url: str | None

id: str | None

url: str

class ProfileBanner

id: int

image: str

image_2x: str

Note

image_2x is returned in the osu! api as image@2x.

tournament_id: int

class UserAccountHistory

description: str | None

id: int

length: int

permanent: bool

timestamp: datetime

type: UserAccountHistoryType

class UserBadge

awarded_at: datetime

description: str

image_2x_url: str

Note

image_2x_url is returned in the osu! api as image@2x_url.

image_url: str

url: str

class GroupDescription

html: str

markdown: str

class UserGroup

colour: str | None

description: GroupDescription | None

has_listing: bool

has_playmodes: bool

id: int

identifier: str

is_probationary: bool

name: str

playmodes: list[GameMode] | None

short_name: str

class Covers

card: str

card_2x: str

Note

card_2x is returned in the osu! api as card@2x.

cover: str

cover_2x: str

Note

cover_2x is returned in the osu! api as cover@2x.

list: str

list_2x: str

Note

list_2x is returned in the osu! api as list@2x.

slimcover: str

slimcover_2x: str

Note

slimcover_2x is returned in the osu! api as slimcover@2x.

class Statistics

count_100: int | None

count_300: int | None

count_50: int | None

count_geki: int | None

count_katu: int | None

count_miss: int | None

class Availability

download_disabled: bool

more_information: str | None

class Hype

current: int

required: int

class Nominations

current: int

required: int

class Nomination

beatmapset_id: int

reset: bool

rulesets: list[GameMode]

user_id: int

class Kudosu

available: int

total: int

class KudosuGiver

url: str

username: str

class KudosuPost

title: str

url: str | None

class KudosuVote

score: int

user: function

user_id: int

class EventUser

previousUsername: str | None

url: str

username: str

class EventBeatmap

title: str

url: str

class EventBeatmapset

title: str

url: str

class EventAchivement

description: str

grouping: str

icon_url: str

id: int

instructions: Any | None

mode: GameMode | None

name: str

ordering: int

slug: str

class GithubUser

display_name: str

github_url: str | None

github_username: str | None

id: int | None

osu_username: str | None

user: function

user_id: int | None

user_url: str | None

class ChangelogSearch

from_: str | None

Note

from_ is returned in the osu! api as from.

limit: int

max_id: int | None

stream: str | None

to: str | None

class NewsSearch

limit: int

sort: str

year: int | None

class ForumPostBody

html: str

raw: str

class ForumPollText

bbcode: str

html: str

class ForumPollTitle

bbcode: str

html: str

class ReviewsConfig

max_blocks: int

class RankHighest

rank: int

updated_at: datetime

class BeatmapPackUserCompletionData

beatmapset_ids: list[int]

completed: bool

class UserMonthlyPlaycount

count: int

start_date: datetime

class UserPage

html: str

raw: str

class UserLevel

current: int

progress: int

class UserGradeCounts

a: int

s: int

sh: int

ss: int

ssh: int

class UserReplaysWatchedCount

count: int

start_date: datetime

class UserAchievement

achieved_at: datetime

achievement_id: int

class UserProfileCustomization

audio_autoplay: bool | None

audio_muted: bool | None

audio_volume: int | None

beatmapset_download: BeatmapsetDownload | None

beatmapset_show_nsfw: bool | None

beatmapset_title_show_original: bool | None

comments_show_deleted: bool | None

forum_posts_show_deleted: bool

ranking_expanded: bool

user_list_filter: UserListFilters | None

user_list_sort: UserListSorts | None

user_list_view: UserListViews | None

class RankHistory

data: list[int]

mode: GameMode

class Weight

percentage: float

pp: float

Models

class Mod(value)

An ingame osu! mod.

Common combinations are available as HDDT, HDHR, and HDDTHR.

Parameters:

value (int or str or list) – A representation of the desired mod. This can either be its integer representation such as 64 for DT and 72 (64 + 8) for HDDT, or a string such as "DT" for DT and "HDDT" (or DTHD) for HDDT, or a list of strings such as ["HD", "DT"] for HDDT.
If used, the string must be composed of two-letter acronyms for mods, in any order.

Notes

The nightcore mod is never set by itself. When we see plays set with NC, we are really seeing a DT + NC play. NC by itself is 512, but what we expect to see is 576 (512 + 64; DT is 64). As such Mod.NC is defined to be the more intuitive version—DT + NC. We provide the true, technical version of the NC mod (512) as Mod._NC.

This same treatment and reasoning applies to Mod.PF, which we define as PF + SD. The technical version of PF is available as Mod._PF.

A full list of mods and their specification can be found at https://osu.ppy.sh/help/wiki/Game_Modifiers, or a more technical list at https://github.com/ppy/osu-api/wiki#mods.

Warning

The fact that this class subclasses ModCombination is slightly misleading. This is only done so that this class can be instantiated directly, backed by an internal ModCombination, instead of exposing ModCombination to users.

class Cursor

class UserCompact

account_history: list[UserAccountHistory] | None

active_tournament_banner: ProfileBanner | None

active_tournament_banners: list[ProfileBanner] | None

avatar_url: str

badges: list[UserBadge] | None

beatmap_playcounts_count: int | None

blocks: UserRelation | None

country: Country | None

country_code: str

cover: Cover | None

default_group: str | None

expand: function

favourite_beatmapset_count: int | None

follow_user_mapping: list[int] | None

follower_count: int | None

friends: list[UserRelation] | None

graveyard_beatmapset_count: int | None

groups: list[UserGroup] | None

guest_beatmapset_count: int | None

id: int

is_active: bool

is_bot: bool

is_deleted: bool

is_online: bool

is_restricted: bool | None

is_silenced: bool | None

is_supporter: bool

last_visit: datetime | None

loved_beatmapset_count: int | None

mapping_follower_count: int | None

monthly_playcounts: list[UserMonthlyPlaycount] | None

page: UserPage | None

pending_beatmapset_count: int | None

pm_friends_only: bool

previous_usernames: list[str] | None

profile_colour: str | None

rankHistory: RankHistory | None

rank_history: RankHistory | None

ranked_and_approved_beatmapset_count: int | None

ranked_beatmapset_count: int | None

replays_watched_counts: list[UserReplaysWatchedCount] | None

scores_best_count: int | None

scores_first_count: int | None

scores_recent_count: int | None

session_verified: bool | None

statistics: UserStatistics | None

statistics_rulesets: UserStatisticsRulesets | None

support_level: int | None

unranked_beatmapset_count: int | None

unread_pm_count: int | None

user_achievements: list[UserAchievement] | None

user_preferences: UserProfileCustomization | None

username: str

class User

account_history: list[UserAccountHistory] | None

active_tournament_banner: ProfileBanner | None

active_tournament_banners: list[ProfileBanner] | None

avatar_url: str

badges: list[UserBadge] | None

beatmap_playcounts_count: int | None

blocks: UserRelation | None

comments_count: int

country: Country | None

country_code: str

cover: Cover | None

cover_url: str

default_group: str | None

discord: str | None

expand: function

favourite_beatmapset_count: int | None

follow_user_mapping: list[int] | None

follower_count: int | None

friends: list[UserRelation] | None

graveyard_beatmapset_count: int | None

groups: list[UserGroup] | None

guest_beatmapset_count: int | None

has_supported: bool

id: int

interests: str | None

is_active: bool

is_bot: bool

is_deleted: bool

is_online: bool

is_restricted: bool | None

is_silenced: bool | None

is_supporter: bool

join_date: datetime

kudosu: Kudosu

last_visit: datetime | None

location: str | None

loved_beatmapset_count: int | None

mapping_follower_count: int | None

max_blocks: int

max_friends: int

monthly_playcounts: list[UserMonthlyPlaycount] | None

nominated_beatmapset_count: int

occupation: str | None

page: UserPage | None

pending_beatmapset_count: int | None

playmode: str

playstyle: PlayStyles | None

pm_friends_only: bool

post_count: int

previous_usernames: list[str] | None

profile_colour: str | None

profile_order: list[ProfilePage]

rankHistory: RankHistory | None

rank_highest: RankHighest | None

rank_history: RankHistory | None

ranked_and_approved_beatmapset_count: int | None

ranked_beatmapset_count: int | None

replays_watched_counts: list[UserReplaysWatchedCount] | None

scores_best_count: int | None

scores_first_count: int | None

scores_pinned_count: int

scores_recent_count: int | None

session_verified: bool | None

statistics: UserStatistics | None

statistics_rulesets: UserStatisticsRulesets | None

support_level: int | None

title: str | None

title_url: str | None

twitter: str | None

unranked_beatmapset_count: int | None

unread_pm_count: int | None

user_achievements: list[UserAchievement] | None

user_preferences: UserProfileCustomization | None

username: str

website: str | None

class BeatmapCompact

beatmapset: function

beatmapset_id: int

checksum: str | None

difficulty_rating: float

expand: function

failtimes: Failtimes | None

id: int

max_combo: int | None

mode: GameMode

status: RankStatus

total_length: int

user: function

user_id: int

version: str

class Beatmap

accuracy: float

ar: float

beatmapset: function

beatmapset_id: int

bpm: float | None

checksum: str | None

convert: bool

count_circles: int

count_sliders: int

count_spinners: int

cs: float

deleted_at: datetime | None

difficulty_rating: float

drain: float

expand: function

failtimes: Failtimes | None

hit_length: int

id: int

is_scoreable: bool

last_updated: datetime

max_combo: int | None

mode: GameMode

mode_int: int

owner: UserCompact | None

Note

owner is returned in the osu! api as user.

passcount: int

playcount: int

ranked: RankStatus

status: RankStatus

total_length: int

url: str

user: function

user_id: int

version: str

class BeatmapsetCompact

artist: str

artist_unicode: str

beatmaps: list[Beatmap] | None

converts: Any | None

covers: Covers

creator: str

current_nominations: list[Nomination] | None

current_user_attributes: Any | None

description: Any | None

discussions: Any | None

events: Any | None

expand: function

favourite_count: int

genre: Any | None

has_favourited: bool | None

hype: Hype | None

id: int

language: Any | None

nominations: Any | None

nsfw: bool

offset: int

pack_tags: list[str] | None

play_count: int

preview_url: str

ratings: Any | None

recent_favourites: Any | None

related_users: Any | None

source: str

spotlight: bool

status: RankStatus

title: str

title_unicode: str

track_id: int | None

user: function

user_id: int

video: bool

class Beatmapset

artist: str

artist_unicode: str

availability: Availability

beatmaps: list[Beatmap] | None

bpm: float

can_be_hyped: bool

converts: Any | None

covers: Covers

creator: str

current_nominations: list[Nomination] | None

current_user_attributes: Any | None

deleted_at: datetime | None

description: Any | None

discussion_enabled: bool

discussion_locked: bool

discussions: Any | None

events: Any | None

expand: function

favourite_count: int

genre: Any | None

has_favourited: bool | None

hype: Hype | None

id: int

is_scoreable: bool

language: Any | None

last_updated: datetime

legacy_thread_url: str | None

nominations: Any | None

nominations_summary: Nominations

nsfw: bool

offset: int

pack_tags: list[str] | None

play_count: int

preview_url: str

ranked: RankStatus

ranked_date: datetime | None

ratings: Any | None

recent_favourites: Any | None

related_users: Any | None

source: str

spotlight: bool

status: RankStatus

storyboard: bool

submitted_date: datetime | None

tags: str

title: str

title_unicode: str

track_id: int | None

user: function

user_id: int

video: bool

class ScoreMatchInfo

pass_: bool

Note

pass_ is returned in the osu! api as pass.

slot: int

team: str

class Score

accuracy: float

beatmap: Beatmap | None

beatmapset: BeatmapsetCompact | None

best_id: int | None

created_at: datetime

current_user_attributes: Any

download: function

id: int | None

match: ScoreMatchInfo | None

max_combo: int

mode: GameMode

mode_int: int

mods: Mod

passed: bool

perfect: bool

pp: float | None

rank: Grade

rank_country: int | None

rank_global: int | None

replay: bool

score: int

statistics: Statistics

type: str

user: function

user_id: int

weight: Weight | None

class BeatmapUserScore

position: int

score: Score

class _NonLegacyBeatmapUserScore

position: int

score: _NonLegacyScore

class BeatmapUserScores

scores: list[Score]

class BeatmapScores

scores: list[Score]

user_score: BeatmapUserScore | None

Note

user_score is returned in the osu! api as userScore.

class CommentableMeta

current_user_attributes: CommentableMetaCurrentUserAttributes | None

id: int | None

owner_id: int | None

owner_title: str | None

title: str

type: str | None

url: str | None

class CommentableMetaCurrentUserAttributes

can_new_comment_reason: str | None

class Comment

commentable_id: int | None

commentable_type: str | None

created_at: datetime

deleted_at: datetime | None

edited_at: datetime | None

edited_by: function

edited_by_id: int | None

id: int

legacy_name: str | None

message: str | None

message_html: str | None

parent_id: int | None

pinned: bool

replies_count: int

updated_at: datetime

user: function

user_id: int | None

votes_count: int

class CommentBundle

commentable_meta: list[CommentableMeta]

comments: list[Comment]

cursor: Cursor | None

has_more: bool

has_more_id: int | None

included_comments: list[Comment]

pinned_comments: list[Comment] | None

sort: str

top_level_count: int | None

total: int | None

user_follow: bool

user_votes: list[int]

users: list[UserCompact]

class ForumPost

body: ForumPostBody

created_at: datetime

deleted_at: datetime | None

edited_at: datetime | None

edited_by: function

edited_by_id: int | None

forum_id: int

id: int

topic_id: int

user: function

user_id: int

class ForumTopic

created_at: datetime

deleted_at: datetime | None

first_post_id: int

forum_id: int

id: int

is_locked: bool

last_post_id: int

poll: ForumPollModel | None

post_count: int

title: str

type: ForumTopicType

updated_at: datetime

user: function

user_id: int

class ForumPollModel

allow_vote_change: bool

ended_at: datetime | None

hide_incomplete_results: bool

last_vote_at: datetime | None

max_votes: int

options: list[ForumPollOption]

started_at: datetime

title: ForumPollTitle

total_vote_count: int

class ForumPollOption

id: int

text: ForumPollText

vote_count: int | None

class ForumTopicAndPosts

cursor: Cursor | None

cursor_string: str | None

posts: list[ForumPost]

search: ForumTopicSearch

topic: ForumTopic

class CreateForumTopicResponse

post: ForumPost

topic: ForumTopic

class ForumTopicSearch

end: int | None

limit: int | None

sort: ForumTopicSort | None

start: int | None

class SearchResult

data: list[T]

total: int

class WikiPage

available_locales: list[str]

layout: str

locale: str

markdown: str

path: str

subtitle: str | None

tags: list[str]

title: str

class Search

users: ossapi.models.SearchResult[ossapi.models.UserCompact] | None

Note

users is returned in the osu! api as user.

wiki_pages: ossapi.models.SearchResult[ossapi.models.WikiPage] | None

Note

wiki_pages is returned in the osu! api as wiki_page.

class Spotlight

end_date: datetime

id: int

mode_specific: bool

name: str

participant_count: int | None

start_date: datetime

type: str

class Spotlights

spotlights: list[Spotlight]

class Users

users: list[UserCompact]

class Beatmaps

beatmaps: list[Beatmap]

class BeatmapPacks

beatmap_packs: list[BeatmapPack]

cursor: Cursor | None

cursor_string: str | None

class Rankings

beatmapsets: list[Beatmapset] | None

cursor: Cursor | None

ranking: list[UserStatistics] | list[CountryStatistics] | None

spotlight: Spotlight | None

total: int

class BeatmapsetDiscussionPost

beatmapset_discussion_id: int

created_at: datetime

deleted_at: datetime | None

deleted_by: function

deleted_by_id: int | None

id: int

last_editor: function

last_editor_id: int | None

message: str

system: bool

updated_at: datetime

user: function

user_id: int

class BeatmapsetDiscussion

beatmap: function

beatmap_id: int | None

beatmapset: function

beatmapset_id: int

can_be_resolved: bool

can_grant_kudosu: bool

created_at: datetime

current_user_attributes: Any

deleted_at: datetime | None

deleted_by: function

deleted_by_id: int | None

id: int

kudosu_denied: bool

last_post_at: datetime

message_type: MessageType

parent_id: int | None

posts: list[BeatmapsetDiscussionPost] | None

resolved: bool

starting_post: BeatmapsetDiscussionPost | None

timestamp: int | None

updated_at: datetime

user: function

user_id: int

class BeatmapsetDiscussionVote

beatmapset_discussion_id: int

created_at: datetime

cursor_string: str | None

id: int

score: int

updated_at: datetime

user: function

user_id: int

class KudosuHistory

action: KudosuAction

amount: int

created_at: datetime

details: Any

giver: KudosuGiver | None

id: int

model: str

post: KudosuPost

class BeatmapPlaycount

beatmap: function

beatmap_id: int

beatmapset: BeatmapsetCompact | None

count: int

class Event

createdAt: datetime

created_at: datetime

id: int

type: EventType

class AchievementEvent

achievement: EventAchivement

createdAt: datetime

created_at: datetime

id: int

type: EventType

user: EventUser

class BeatmapPlaycountEvent

beatmap: EventBeatmap

count: int

createdAt: datetime

created_at: datetime

id: int

type: EventType

class BeatmapsetApproveEvent

approval: BeatmapsetApproval

beatmapset: EventBeatmapset

createdAt: datetime

created_at: datetime

id: int

type: EventType

user: EventUser

class BeatmapsetDeleteEvent

beatmapset: EventBeatmapset

createdAt: datetime

created_at: datetime

id: int

type: EventType

class BeatmapsetReviveEvent

beatmapset: EventBeatmapset

createdAt: datetime

created_at: datetime

id: int

type: EventType

user: EventUser

class BeatmapsetUpdateEvent

beatmapset: EventBeatmapset

createdAt: datetime

created_at: datetime

id: int

type: EventType

user: EventUser

class BeatmapsetUploadEvent

beatmapset: EventBeatmapset

createdAt: datetime

created_at: datetime

id: int

type: EventType

user: EventUser

class RankEvent

beatmap: EventBeatmap

createdAt: datetime

created_at: datetime

id: int

mode: GameMode

rank: int

scoreRank: str

type: EventType

user: EventUser

class RankLostEvent

beatmap: EventBeatmap

createdAt: datetime

created_at: datetime

id: int

mode: GameMode

type: EventType

user: EventUser

class UserSupportFirstEvent

createdAt: datetime

created_at: datetime

id: int

type: EventType

user: EventUser

class UserSupportAgainEvent

createdAt: datetime

created_at: datetime

id: int

type: EventType

user: EventUser

class UserSupportGiftEvent

createdAt: datetime

created_at: datetime

id: int

type: EventType

user: EventUser

class UsernameChangeEvent

createdAt: datetime

created_at: datetime

id: int

type: EventType

user: EventUser

class Build

changelog_entries: list[ChangelogEntry] | None

created_at: datetime

display_version: str

id: int

update_stream: UpdateStream | None

users: int

version: str | None

versions: Versions | None

youtube_id: str | None

class Versions

next: Build | None

previous: Build | None

class UpdateStream

display_name: str | None

id: int

is_featured: bool

latest_build: Build | None

name: str

user_count: int | None

class ChangelogEntry

category: str

created_at: datetime | None

github_pull_request_id: int | None

github_url: str | None

github_user: GithubUser

id: int | None

major: bool

message: str | None

message_html: str | None

repository: str | None

title: str | None

type: str

url: str | None

class ChangelogListing

builds: list[Build]

search: ChangelogSearch

streams: list[UpdateStream]

class MultiplayerScores

cursor_string: str | None

params: str

scores: list[MultiplayerScore]

total: int | None

user_score: MultiplayerScore | None

class MultiplayerScore

beatmap: function

beatmap_id: int

id: int

max_combo: int

mods: list[Mod]

passed: bool

playlist_item_id: int

position: int | None

rank: int

room_id: int

scores_around: MultiplayerScoresAround | None

statistics: Statistics

total_score: int

user: User

user_id: int

class MultiplayerScoresAround

higher: list[MultiplayerScore]

lower: list[MultiplayerScore]

class NewsListing

cursor: Cursor | None

cursor_string: str | None

news_posts: list[NewsPost]

news_sidebar: NewsSidebar

search: NewsSearch

class NewsPost

author: str

content: str | None

edit_url: str

first_image: str | None

id: int

navigation: NewsNavigation | None

preview: str | None

published_at: datetime

slug: str

title: str

updated_at: datetime

class NewsNavigation

newer: NewsPost | None

older: NewsPost | None

class NewsSidebar

current_year: int

news_posts: list[NewsPost]

years: list[int]

class SeasonalBackgrounds

backgrounds: list[SeasonalBackground]

ends_at: datetime

class SeasonalBackground

url: str

user: UserCompact

class DifficultyAttributes

attributes: BeatmapDifficultyAttributes

class BeatmapDifficultyAttributes

aim_difficulty: float | None

approach_rate: float | None

colour_difficulty: float | None

flashlight_difficulty: float | None

great_hit_window: float | None

max_combo: int

overall_difficulty: float | None

rhythm_difficulty: float | None

score_multiplier: float | None

slider_factor: float | None

speed_difficulty: float | None

speed_note_count: float | None

stamina_difficulty: float | None

star_rating: float

class Events

cursor: Cursor | None

cursor_string: str | None

events: list[Event]

class BeatmapPack

author: str

beatmapsets: list[Beatmapset] | None

date: datetime

name: str

no_diff_reduction: bool

ruleset_id: int | None

tag: str

url: str

user_completion_data: BeatmapPackUserCompletionData | None

class ForumPoll

hide_results: bool

length_days: int

max_options: int

vote_change: bool

class BeatmapsetSearchResult

beatmapsets: list[Beatmapset]

cursor: Cursor | None

cursor_string: str | None

error: str | None

recommended_difficulty: float | None

search: Any

total: int

class BeatmapsetDiscussions

beatmaps: list[Beatmap]

beatmapsets: list[Beatmapset]

cursor: Cursor | None

cursor_string: str | None

discussions: list[BeatmapsetDiscussion]

included_discussions: list[BeatmapsetDiscussion]

reviews_config: ReviewsConfig

users: list[UserCompact]

class BeatmapsetDiscussionReview

max_blocks: int

class BeatmapsetDiscussionPosts

beatmapsets: list[BeatmapsetCompact]

cursor: Cursor | None

cursor_string: str | None

discussions: list[BeatmapsetDiscussion]

posts: list[BeatmapsetDiscussionPost]

users: list[UserCompact]

class BeatmapsetDiscussionVotes

cursor: Cursor | None

cursor_string: str | None

discussions: list[BeatmapsetDiscussion]

users: list[UserCompact]

votes: list[BeatmapsetDiscussionVote]

class BeatmapsetEventComment

beatmap_discussion_id: int

beatmap_discussion_post_id: int

class BeatmapsetEventCommentNoPost

beatmap_discussion_id: int

beatmap_discussion_post_id: None

class BeatmapsetEventCommentNone

beatmap_discussion_id: None

beatmap_discussion_post_id: None

class BeatmapsetEventCommentChange

beatmap_discussion_id: None

beatmap_discussion_post_id: None

new: S

old: S

class BeatmapsetEventCommentLovedRemoval

beatmap_discussion_id: None

beatmap_discussion_post_id: None

reason: str

class BeatmapsetEventCommentKudosuChange

beatmap_discussion_id: int

beatmap_discussion_post_id: None

new_vote: KudosuVote

votes: list[KudosuVote]

class BeatmapsetEventCommentKudosuRecalculate

beatmap_discussion_id: int

beatmap_discussion_post_id: None

new_vote: KudosuVote | None

class BeatmapsetEventCommentOwnerChange

beatmap_discussion_id: None

beatmap_discussion_post_id: None

beatmap_id: int

beatmap_version: str

new_user_id: int

new_user_username: str

class BeatmapsetEventCommentNominate

modes: list[GameMode]

class BeatmapsetEventCommentWithNominators

beatmap_discussion_id: int

beatmap_discussion_post_id: None

nominator_ids: list[int] | None

class BeatmapsetEventCommentWithSourceUser

beatmap_discussion_id: int

beatmap_discussion_post_id: None

source_user_id: int

source_user_username: str

class BeatmapsetEvent

beatmapset: BeatmapsetCompact | None

comment: str

created_at: datetime

discussion: BeatmapsetDiscussion | None

id: int

type: BeatmapsetEventType

user: function

user_id: int | None

class ChatChannel

channel_id: int

description: str | None

icon: str | None

last_message_id: int | None

last_read_id: int | None

message_length_limit: int

moderated: bool | None

name: str

recent_messages: list[ChatMessage] | None

type: ChannelType

users: list[int] | None

uuid: str | None

class ChatMessage

channel_id: int

content: str

is_action: bool

message_id: int

sender: UserCompact

sender_id: int

timestamp: datetime

type: str

class CountryStatistics

active_users: int

code: str

country: Country

performance: int

play_count: int

ranked_score: int

class CreatePMResponse

channel: ChatChannel

message: ChatMessage

new_channel_id: int

presence: list[ChatChannel] | None

class ModdingHistoryEventsBundle

events: list[BeatmapsetEvent]

reviewsConfig: BeatmapsetDiscussionReview

users: list[UserCompact]

class UserRelation

mutual: bool

relation_type: UserRelationType

target: UserCompact | None

target_id: int

class StatisticsVariant

country_rank: int | None

global_rank: int | None

mode: GameMode

pp: float

variant: Variant

class UserStatistics

count_100: int

count_300: int

count_50: int

count_miss: int

country_rank: int | None

global_rank: int | None

global_rank_exp: float | None

grade_counts: UserGradeCounts

hit_accuracy: float

is_ranked: bool

level: UserLevel

maximum_combo: int

play_count: int

play_time: int

pp: float

pp_exp: float

rank: Any | None

ranked_score: int

replays_watched_by_others: int

total_hits: int

total_score: int

user: UserCompact | None

variants: list[StatisticsVariant] | None

class UserStatisticsRulesets

fruits: UserStatistics | None

mania: UserStatistics | None

osu: UserStatistics | None

taiko: UserStatistics | None

class RoomPlaylistItemMod

acronym: str

settings: Dict[str, Any]

class RoomPlaylistItem

allowed_mods: list[RoomPlaylistItemMod]

beatmap: BeatmapCompact

beatmap_id: int

expired: bool

id: int

owner_id: int

played_at: datetime | None

playlist_order: int | None

required_mods: list[RoomPlaylistItemMod]

room_id: int

ruleset_id: int

class Room

active: bool

auto_skip: bool

category: RoomCategory

channel_id: int

ends_at: datetime

has_password: bool

host: UserCompact

id: int

max_attempts: int | None

name: str

participant_count: int

playlist: list[RoomPlaylistItem]

queue_mode: str

recent_participants: list[UserCompact]

starts_at: datetime

type: RoomType

user_id: int

class RoomLeaderboardScore

accuracy: float

attempts: int

completed: int

pp: float

room_id: int

total_score: int

user: UserCompact

user_id: int

class RoomLeaderboardUserScore

accuracy: float

attempts: int

completed: int

position: int

pp: float

room_id: int

total_score: int

user: UserCompact

user_id: int

class RoomLeaderboard

leaderboard: list[RoomLeaderboardScore]

user_score: RoomLeaderboardUserScore

class Match

end_time: datetime | None

id: int

name: str

start_time: datetime

class Matches

cursor: Cursor | None

cursor_string: str | None

matches: list[Match]

params: Any

class MatchGame

beatmap: BeatmapCompact | None

beatmap_id: int

end_time: datetime | None

id: int

mode: GameMode

mode_int: int

mods: list[Mod]

scores: list[Score]

scoring_type: ScoringType

start_time: datetime

team_type: TeamType

class MatchEventDetail

text: str | None

type: MatchEventType

class MatchEvent

detail: MatchEventDetail

game: MatchGame | None

id: int

timestamp: datetime

user_id: int | None

class MatchResponse

current_game_id: int | None

events: list[MatchEvent]

first_event_id: int

latest_event_id: int

match: Match

users: list[UserCompact]

class _NonLegacyBeatmapScores

scores: list[_NonLegacyScore]

user_score: _NonLegacyBeatmapUserScore | None

Note

user_score is returned in the osu! api as userScore.

class _NonLegacyMod

class _NonLegacyStatistics

combo_break: int | None

good: int | None

great: int | None

ignore_hit: int | None

ignore_miss: int | None

large_bonus: int | None

large_tick_hit: int | None

large_tick_miss: int | None

legacy_combo_increase: int | None

meh: int | None

miss: int | None

ok: int | None

perfect: int | None

slider_tail_hit: int | None

small_bonus: int | None

small_tick_hit: int | None

small_tick_miss: int | None

class _NonLegacyScore

accuracy: float

beatmap_id: int

beatmapset: BeatmapsetCompact | None

best_id: int | None

build_id: int | None

current_user_attributes: Any

ended_at: datetime

has_replay: bool

id: int | None

is_perfect_combo: bool

legacy_perfect: bool

legacy_score_id: int

legacy_total_score: int

match: ScoreMatchInfo | None

max_combo: int

maximum_statistics: Any

mods: _NonLegacyMod

passed: bool

pp: float | None

preserve: bool

rank: Grade

rank_country: int | None

rank_global: int | None

ranked: bool

replay: bool

ruleset_id: int

started_at: datetime | None

statistics: _NonLegacyStatistics

total_score: int

type: str

user: function

user_id: int

weight: Weight | None

Ossapi

class Ossapi(client_id, client_secret, redirect_uri=None, scopes=[<Scope.PUBLIC: 'public'>], *, grant=None, strict=False, token_directory=None, token_key=None, access_token=None, refresh_token=None, domain=Domain.OSU)

A wrapper around osu! api v2. The main entry point for ossapi.

Parameters:

• client_id (int) – The id of the client to authenticate with.

• client_secret (str) – The secret of the client to authenticate with.

• redirect_uri (str) – The redirect uri for the client. Must be passed if using the authorization code grant. This must exactly match the redirect uri on the client’s settings page. Additionally, in order for ossapi to receive authentication from this redirect uri, it must be a port on localhost, e.g. “http://localhost:3914/”. You can change your client’s redirect uri from its settings page.

• scopes (List[str]) – What scopes to request when authenticating.

• grant (Grant or str) – Which oauth grant (aka flow) to use when authenticating with the api. The osu api offers the client credentials (pass “client” for this parameter) and authorization code (pass “authorization” for this parameter) grants.
  The authorization code grant requires user interaction to authenticate the first time, but grants full access to the api. In contrast, the client credentials grant does not require user interaction to authenticate, but only grants guest user access to the api. This means you will not be able to do things like download replays on the client credentials grant.
  If not passed, the grant will be automatically inferred as follows: if redirect_uri is passed, use the authorization code grant. If redirect_uri is not passed, use the client credentials grant.

• strict (bool) – Whether to run in “strict” mode. In strict mode, ossapi will raise an exception if the api returns an attribute in a response which we didn’t expect to be there. This is useful for developers which want to catch new attributes as they get added. More checks may be added in the future for things which developers may want to be aware of, but normal users do not want to have an exception raised for.
  If you are not a developer, you are very unlikely to want to use this parameter.

• token_directory (str) – If passed, the given directory will be used to store and retrieve token files instead of locally wherever ossapi is installed. Useful if you want more control over token files.

• token_key (str) – If passed, the given key will be used to name the token file instead of an automatically generated one. Note that if you pass this, you are taking responsibility for making sure it is unique / unused, and also for remembering the key you passed if you wish to eg remove the token in the future, which requires the key.

• access_token (str) – Access token from the osu! api. Allows instantiating Ossapi after manually authenticating with the osu! api.

• refresh_token (str) – Refresh token from the osu! api. Allows instantiating Ossapi after manually authenticating with the osu! api. Optional if using Grant.CLIENT_CREDENTIALS.

• domain (Domain or str) – The domain to retrieve information from. This defaults to Domain.OSU, which corresponds to osu.ppy.sh, the main website.
  To retrieve information from dev.ppy.sh, specify Domain.DEV.
  See Domains for more about domains.

OssapiAsync

class OssapiAsync(client_id, client_secret, redirect_uri=None, scopes=[<Scope.PUBLIC: 'public'>], *, grant=None, strict=False, token_directory=None, token_key=None, access_token=None, refresh_token=None, domain=Domain.OSU)

Async equivalent of Ossapi. Main (async) entry point into osu! api v2.

Parameters:

• client_id (int) – The id of the client to authenticate with.

• client_secret (str) – The secret of the client to authenticate with.

• redirect_uri (str) – The redirect uri for the client. Must be passed if using the authorization code grant. This must exactly match the redirect uri on the client’s settings page. Additionally, in order for ossapi to receive authentication from this redirect uri, it must be a port on localhost, e.g. “http://localhost:3914/”. You can change your client’s redirect uri from its settings page.

• scopes (List[str]) – What scopes to request when authenticating.

• grant (Grant or str) – Which oauth grant (aka flow) to use when authenticating with the api. The osu api offers the client credentials (pass “client” for this parameter) and authorization code (pass “authorization” for this parameter) grants.
  The authorization code grant requires user interaction to authenticate the first time, but grants full access to the api. In contrast, the client credentials grant does not require user interaction to authenticate, but only grants guest user access to the api. This means you will not be able to do things like download replays on the client credentials grant.
  If not passed, the grant will be automatically inferred as follows: if redirect_uri is passed, use the authorization code grant. If redirect_uri is not passed, use the client credentials grant.

• strict (bool) – Whether to run in “strict” mode. In strict mode, ossapi will raise an exception if the api returns an attribute in a response which we didn’t expect to be there. This is useful for developers which want to catch new attributes as they get added. More checks may be added in the future for things which developers may want to be aware of, but normal users do not want to have an exception raised for.
  If you are not a developer, you are very unlikely to want to use this parameter.

• token_directory (str) – If passed, the given directory will be used to store and retrieve token files instead of locally wherever ossapi is installed. Useful if you want more control over token files.

• token_key (str) – If passed, the given key will be used to name the token file instead of an automatically generated one. Note that if you pass this, you are taking responsibility for making sure it is unique / unused, and also for remembering the key you passed if you wish to eg remove the token in the future, which requires the key.

• access_token (str) – Access token from the osu! api. Allows instantiating Ossapi after manually authenticating with the osu! api.

• refresh_token (str) – Refresh token from the osu! api. Allows instantiating Ossapi after manually authenticating with the osu! api. Optional if using Grant.CLIENT_CREDENTIALS.

• domain (Domain or str) – The domain to retrieve information from. This defaults to Domain.OSU, which corresponds to osu.ppy.sh, the main website.
  To retrieve information from dev.ppy.sh, specify Domain.DEV.
  See Domains for more about domains.

Scope

class Scope(value)

The OAuth scopes used by the api.

CHAT_WRITE = 'chat.write'

CHAT_WRITE_MANAGE = 'chat.write_manage'

CHAT_READ = 'chat.read'

DELEGATE = 'delegate'

FORUM_WRITE = 'forum.write'

FRIENDS_READ = 'friends.read'

IDENTIFY = 'identify'

PUBLIC = 'public'

Domain

class Domain(value)

Different possible api domains. These correspond to different deployments of the osu server, such as osu.ppy.sh or dev.ppy.sh.

The default domain, and the one the vast majority of users want, is Domain.OSU, and corresponds to the main website.

OSU = 'osu'

DEV = 'dev'

Grant

class Grant(value)

The grant types used by the api.

CLIENT_CREDENTIALS = 'client'

AUTHORIZATION_CODE = 'authorization'

Replay

class Replay(replay, api)

A replay played by a player.

Notes

This is a thin wrapper around an osrparse.replay.Replay instance. It converts some attributes to more appropriate types and adds user() and beatmap() to retrieve api-related objects.

property beatmap: Beatmap

The beatmap this replay was played on.

Warning

Accessing this property for the first time will result in a web request to retrieve the beatmap from the api. We cache the return value, so further accesses are free.

property user: User

The user that played this replay.

Warning

Accessing this property for the first time will result in a web request to retrieve the user from the api. We cache the return value, so further accesses are free.

pack(*, dict_size=None, mode=None)

Returns the text representing this Replay, in .osr format. The text returned by this method is suitable for writing to a file as a valid .osr file.

Returns:

The text representing this Replay, in .osr format.

Return type:

str