Welcome to osu.py’s documentation!
Easy to use API wrapper for osu!api v2 written in Python.
Getting started
If you’re new to osu.py, consider checking out this guide on how to get started!
Looking for something specific
Visit the examples page or join the discord and feel free to ping me (@sheppsu) or just dm me directly.
There are some examples on the github here that might help you find what you’re looking for. Otherwise here are some common uses for the api that you might be looking for.
Get a list of the top player’s by score, spotlight, or pp (here’s an example)
Get a user by their id or username, Get multiple with one request (ids only), or Get the user of the authorization code grant being used
Get a user’s score on a beatmap or Get all their scores for a beatmap
Get beatmapset discussion posts, beatmapset discussion votes, or beatmapset discussions
Documentation tree
- License
- Installing osu.py
- Getting started with osu.py
- Advanced usage of osu.py
- Examples
- API Reference
- Core Classes
- Clients
ClientClient.from_credentials()Client.from_client_credentials()Client.set_api_version()Client.set_domain()Client.lookup_beatmap()Client.get_user_beatmap_score()Client.get_user_beatmap_scores()Client.get_beatmap_scores()Client.get_beatmap()Client.get_beatmaps()Client.get_beatmap_attributes()Client.get_beatmapset()Client.get_beatmapset_discussion_posts()Client.get_beatmapset_discussion_votes()Client.get_beatmapset_discussions()Client.get_changelog_build()Client.get_changelog_listing()Client.lookup_changelog_build()Client.get_comments()Client.get_comment()Client.reply_topic()Client.create_topic()Client.get_topic_and_posts()Client.edit_topic()Client.edit_post()Client.search()Client.get_scores()Client.get_news_listing()Client.get_news_post()Client.revoke_current_token()Client.get_ranking()Client.get_spotlights()Client.get_own_data()Client.get_user_kudosu()Client.get_user_scores()Client.get_user_beatmaps()Client.get_user_recent_activity()Client.get_user()Client.get_users()Client.lookup_users()Client.get_wiki_page()Client.get_beatmapset_events()Client.get_matches()Client.get_match()Client.get_rooms()Client.get_seasonal_backgrounds()Client.get_room()Client.get_score_by_id()Client.get_score_by_id_only()Client.search_beatmapsets()Client.get_room_leaderboard()Client.get_replay_data()Client.get_replay_data_by_id_only()Client.get_friends()Client.chat_keepalive()Client.create_new_pm()Client.get_channel_messages()Client.send_message_to_channel()Client.join_channel()Client.leave_channel()Client.mark_channel_as_read()Client.get_channel_list()Client.create_pm_channel()Client.create_announcement_channel()Client.get_channel()Client.get_all_scores()Client.get_forums()Client.get_forum()Client.get_forum_topics()
AsynchronousClientHTTPHandlerAsynchronousHTTPHandlerPathBaseHTTPHandler
- Authentication
- Clients
- Endpoint results
BeatmapsetDiscussionPostsResultBeatmapsetDiscussionVotesResultBeatmapsetDiscussionsResultBeatmapsetSearchResultChangelogListingResultChangelogListingSearchCreateNewPmResultCreateTopicResultGetAllScoresResultGetBeatmapsetEventsResultGetChannelResultGetForumResultGetForumTopicsResultGetForumsResultGetMatchesResultGetNewsListingResultGetRoomLeaderboardResultGetTopicAndPostsResultNewsSidebarReviewsConfigSearchInfoSearchResult
- Objects
AchievementAchievementEventBaseNominationsBeatmapBeatmap.accuracyBeatmap.arBeatmap.beatmapsetBeatmap.bpmBeatmap.convertBeatmap.count_circlesBeatmap.count_slidersBeatmap.count_spinnersBeatmap.csBeatmap.deleted_atBeatmap.drainBeatmap.hit_lengthBeatmap.is_scoreableBeatmap.last_updatedBeatmap.mode_intBeatmap.passcountBeatmap.playcountBeatmap.rankedBeatmap.url
BeatmapCompactBeatmapCompact.beatmapset_idBeatmapCompact.difficulty_ratingBeatmapCompact.idBeatmapCompact.modeBeatmapCompact.statusBeatmapCompact.total_lengthBeatmapCompact.user_idBeatmapCompact.versionBeatmapCompact.beatmapsetBeatmapCompact.checksumBeatmapCompact.failtimesBeatmapCompact.max_comboBeatmapCompact.owners
BeatmapDifficultyAttributesBeatmapOwnerChangeDetailsBeatmapPlaycountBeatmapPlaycountEventBeatmapScoresBeatmapUserScoreBeatmapsetBeatmapset.availabilityBeatmapset.beatmapsBeatmapset.bpmBeatmapset.can_be_hypedBeatmapset.deleted_atBeatmapset.discussion_enabledBeatmapset.discussion_lockedBeatmapset.is_scoreableBeatmapset.last_updatedBeatmapset.legacy_thread_urlBeatmapset.nominations_summaryBeatmapset.rankedBeatmapset.ranked_dateBeatmapset.storyboardBeatmapset.submitted_dateBeatmapset.tags
BeatmapsetApproveEventBeatmapsetAvailabilityBeatmapsetCompactBeatmapsetCompact.artistBeatmapsetCompact.artist_unicodeBeatmapsetCompact.background_urlBeatmapsetCompact.coversBeatmapsetCompact.creatorBeatmapsetCompact.favourite_countBeatmapsetCompact.hypeBeatmapsetCompact.idBeatmapsetCompact.nsfwBeatmapsetCompact.offsetBeatmapsetCompact.play_countBeatmapsetCompact.preview_urlBeatmapsetCompact.sourceBeatmapsetCompact.spotlightBeatmapsetCompact.statusBeatmapsetCompact.titleBeatmapsetCompact.title_unicodeBeatmapsetCompact.track_idBeatmapsetCompact.user_idBeatmapsetCompact.videoBeatmapsetCompact.availabilityBeatmapsetCompact.beatmapsBeatmapsetCompact.convertsBeatmapsetCompact.current_nominationsBeatmapsetCompact.current_user_attributesBeatmapsetCompact.descriptionBeatmapsetCompact.description_bbcodeBeatmapsetCompact.discussionsBeatmapsetCompact.eventsBeatmapsetCompact.genreBeatmapsetCompact.has_favouritedBeatmapsetCompact.languageBeatmapsetCompact.nominationsBeatmapsetCompact.pack_tagsBeatmapsetCompact.ratingsBeatmapsetCompact.recent_favouritesBeatmapsetCompact.related_usersBeatmapsetCompact.userBeatmapsetCompact.version_count
BeatmapsetDeleteEventBeatmapsetDiscussionBeatmapsetDiscussion.beatmap_idBeatmapsetDiscussion.beatmapset_idBeatmapsetDiscussion.can_be_resolvedBeatmapsetDiscussion.can_grant_kudosuBeatmapsetDiscussion.created_atBeatmapsetDiscussion.deleted_atBeatmapsetDiscussion.deleted_by_idBeatmapsetDiscussion.idBeatmapsetDiscussion.kudosu_deniedBeatmapsetDiscussion.last_post_atBeatmapsetDiscussion.message_typeBeatmapsetDiscussion.parent_idBeatmapsetDiscussion.resolvedBeatmapsetDiscussion.timestampBeatmapsetDiscussion.updated_atBeatmapsetDiscussion.user_idBeatmapsetDiscussion.beatmapBeatmapsetDiscussion.beatmapsetBeatmapsetDiscussion.current_user_attributesBeatmapsetDiscussion.postsBeatmapsetDiscussion.starting_postBeatmapsetDiscussion.votes
BeatmapsetDiscussionLockDetailsBeatmapsetDiscussionPermissionsBeatmapsetDiscussionPostBeatmapsetDiscussionPost.beatmapset_discussion_idBeatmapsetDiscussionPost.created_atBeatmapsetDiscussionPost.deleted_atBeatmapsetDiscussionPost.deleted_by_idBeatmapsetDiscussionPost.idBeatmapsetDiscussionPost.last_editor_idBeatmapsetDiscussionPost.updated_atBeatmapsetDiscussionPost.user_idBeatmapsetDiscussionPost.messageBeatmapsetDiscussionPost.systemBeatmapsetDiscussionPost.beatmap_discussion
BeatmapsetDiscussionPostNewDetailsBeatmapsetDiscussionPostNotificationDetailsBeatmapsetDiscussionPostNotificationDetails.contentBeatmapsetDiscussionPostNotificationDetails.titleBeatmapsetDiscussionPostNotificationDetails.title_unicodeBeatmapsetDiscussionPostNotificationDetails.post_idBeatmapsetDiscussionPostNotificationDetails.discussion_idBeatmapsetDiscussionPostNotificationDetails.beatmap_idBeatmapsetDiscussionPostNotificationDetails.cover_url
BeatmapsetDiscussionQualifiedProblemDetailsBeatmapsetDiscussionReviewNewDetailsBeatmapsetDiscussionReviewNewDetails.titleBeatmapsetDiscussionReviewNewDetails.title_unicodeBeatmapsetDiscussionReviewNewDetails.post_idBeatmapsetDiscussionReviewNewDetails.discussion_idBeatmapsetDiscussionReviewNewDetails.beatmap_idBeatmapsetDiscussionReviewNewDetails.cover_urlBeatmapsetDiscussionReviewNewDetails.embeds
BeatmapsetDiscussionUnlockDetailsBeatmapsetDiscussionVoteBeatmapsetDisqualifyDetailsBeatmapsetEventBeatmapsetEventBeatmapOwnerChangeBeatmapsetEventCommentBeatmapsetEventDiscussionLockBeatmapsetEventDisqualifyBeatmapsetEventEditBeatmapsetEventGenreEditBeatmapsetEventKudosuChangeBeatmapsetEventKudosuGainBeatmapsetEventKudosuLostBeatmapsetEventKudosuRecalculateBeatmapsetEventLanguageEditBeatmapsetEventNominateBeatmapsetEventNominationResetBeatmapsetEventNominationResetReceivedBeatmapsetEventNsfwToggleBeatmapsetEventOffsetEditBeatmapsetEventRemoveFromLovedBeatmapsetEventVoteBeatmapsetLoveDetailsBeatmapsetNominateDetailsBeatmapsetNotificationDetailsBeatmapsetPermissionsBeatmapsetPermissions.can_beatmap_update_ownerBeatmapsetPermissions.can_deleteBeatmapsetPermissions.can_edit_metadataBeatmapsetPermissions.can_edit_offsetBeatmapsetPermissions.can_edit_tagsBeatmapsetPermissions.can_hypeBeatmapsetPermissions.can_hype_reasonBeatmapsetPermissions.can_loveBeatmapsetPermissions.can_remove_from_lovedBeatmapsetPermissions.is_watchingBeatmapsetPermissions.new_hype_timeBeatmapsetPermissions.nomination_modesBeatmapsetPermissions.remaining_hype
BeatmapsetQualifyDetailsBeatmapsetRankDetailsBeatmapsetRemoveFromLovedDetailsBeatmapsetRequiredNominationsBeatmapsetRequirementBeatmapsetResetNominationsDetailsBeatmapsetReviveEventBeatmapsetUpdateEventBeatmapsetUploadEventBuildChangelogEntryChangelogEntry.categoryChangelogEntry.created_atChangelogEntry.github_pull_request_idChangelogEntry.github_urlChangelogEntry.idChangelogEntry.majorChangelogEntry.repositoryChangelogEntry.titleChangelogEntry.typeChangelogEntry.urlChangelogEntry.github_userChangelogEntry.messageChangelogEntry.message_html
ChannelAnnouncementDetailsChannelMessageDetailsChatChannelChatChannelUserAttributesChatMessageCommentComment.commentable_idComment.commentable_typeComment.created_atComment.deleted_atComment.deleted_by_idComment.edited_atComment.edited_by_idComment.idComment.legacy_nameComment.messageComment.message_htmlComment.parent_idComment.pinnedComment.replies_countComment.updated_atComment.userComment.user_idComment.votes_countComment.url
CommentBundleCommentBundle.commentable_metaCommentBundle.commentsCommentBundle.has_moreCommentBundle.has_more_idCommentBundle.included_commentsCommentBundle.pinned_commentsCommentBundle.sortCommentBundle.cursorCommentBundle.top_level_countCommentBundle.totalCommentBundle.user_followCommentBundle.user_votesCommentBundle.users
CommentNewDetailsCommentableMetaCommentableMetaAttributesCountryCountryStatisticsCoversCurrentNominationCurrentUserPinDailyChallengeUserStatsDailyChallengeUserStats.daily_streak_bestDailyChallengeUserStats.daily_streak_currentDailyChallengeUserStats.last_updateDailyChallengeUserStats.last_weekly_streakDailyChallengeUserStats.playcountDailyChallengeUserStats.top_10p_placementsDailyChallengeUserStats.top_50p_placementsDailyChallengeUserStats.user_idDailyChallengeUserStats.weekly_streak_bestDailyChallengeUserStats.weekly_streak_current
EventEventBeatmapEventBeatmapsetEventUserFailtimesForumForumPostForumTopicForumTopicReplyDetailsGithubUserGroupKudosuGiverKudosuHistoryKudosuPostLazerModLegacyNominationsLegacyScoreLegacyScore.idLegacyScore.best_idLegacyScore.user_idLegacyScore.accuracyLegacyScore.modsLegacyScore.scoreLegacyScore.max_comboLegacyScore.perfectLegacyScore.statisticsLegacyScore.passeLegacyScore.ppLegacyScore.rankLegacyScore.created_atLegacyScore.modeLegacyScore.mode_intLegacyScore.has_replayLegacyScore.beatmapLegacyScore.beatmapsetLegacyScore.rank_countryLegacyScore.rank_globalLegacyScore.weightLegacyScore.userLegacyScore.matchLegacyScore.current_user_attributes
MatchMatchEventMatchExtendedMatchGameMatchGameScoreInfoMetadataAttributeMultiplayerScoreMultiplayerScore.idMultiplayerScore.user_idMultiplayerScore.room_idMultiplayerScore.playlist_item_idMultiplayerScore.beatmap_idMultiplayerScore.rankMultiplayerScore.total_scoreMultiplayerScore.accuracyMultiplayerScore.max_comboMultiplayerScore.modsMultiplayerScore.statisticsMultiplayerScore.passedMultiplayerScore.positionMultiplayerScore.scores_aroundMultiplayerScore.user
MultiplayerScoresMultiplayerScoresAroundNavigationNewsPostNominationsNotificationNotification.idNotification.nameNotification.created_atNotification.object_typeNotification.object_idNotification.source_user_idNotification.is_readNotification.detailsNotification.beatmapset_discussion_locNotification.beatmapset_discussion_post_neNotification.beatmapset_discussion_unlocNotification.beatmapset_disqualifNotification.beatmapset_lovNotification.beatmapset_nominatNotification.beatmapset_qualifNotification.beatmapset_remove_from_loveNotification.beatmapset_reset_nominationNotification.channel_messagNotification.forum_topic_repl
NotificationsDetailsBaseOsuBeatmapDifficultyAttributesOsuBeatmapDifficultyAttributes.aim_difficultyOsuBeatmapDifficultyAttributes.aim_difficult_slider_countOsuBeatmapDifficultyAttributes.speed_difficultyOsuBeatmapDifficultyAttributes.speed_note_countOsuBeatmapDifficultyAttributes.slider_factorOsuBeatmapDifficultyAttributes.aim_difficult_strain_countOsuBeatmapDifficultyAttributes.speed_difficult_strain_count
PlaylistItemPlaylistItemStatsPollPollOptionPpWeightProfileBannerRankEventRankHighestRankHistoryRankLostEventRankingsReadNotificationReviewReviewStatsRoomRoom.idRoom.nameRoom.categoryRoom.statusRoom.typeRoom.realtime_typeRoom.user_idRoom.starts_atRoom.ends_atRoom.max_attemptsRoom.participant_countRoom.channel_idRoom.activeRoom.has_passwordRoom.queue_modeRoom.current_playlist_itemRoom.current_user_scoreRoom.difficulty_rangeRoom.hostRoom.playlistRoom.playlist_item_statsRoom.recent_participantsRoom.scores
ScoreDataStatisticsScoreDataStatistics.okScoreDataStatistics.mehScoreDataStatistics.goodScoreDataStatistics.missScoreDataStatistics.noneScoreDataStatistics.greatScoreDataStatistics.perfectScoreDataStatistics.ignore_hitScoreDataStatistics.ignore_missScoreDataStatistics.large_bonusScoreDataStatistics.small_bonusScoreDataStatistics.large_tick_hitScoreDataStatistics.small_tick_hitScoreDataStatistics.large_tick_missScoreDataStatistics.small_tick_missScoreDataStatistics.slider_tail_hitScoreDataStatistics.combo_breakScoreDataStatistics.legacy_combo_increase
ScoreStatisticsScoreUserAttributesSearchResultsSeasonalBackgroundSeasonalBackgroundsSoloScoreSoloScore.accuracySoloScore.beatmap_idSoloScore.beatmapSoloScore.beatmapsetSoloScore.ended_atSoloScore.max_comboSoloScore.maximum_statisticsSoloScore.modsSoloScore.passedSoloScore.rankSoloScore.ruleset_idSoloScore.statisticsSoloScore.total_scoreSoloScore.user_idSoloScore.best_idSoloScore.idSoloScore.legacy_perfectSoloScore.ppSoloScore.replaySoloScore.typeSoloScore.userSoloScore.build_idSoloScore.legacy_score_idSoloScore.legacy_total_scoreSoloScore.started_atSoloScore.current_user_attributesSoloScore.weightSoloScore.match
SpotlightSpotlightRankingsSpotlightsSystemDiscussionPostMessageTaikoBeatmapDifficultyAttributesTextFormatUpdateStreamUserUserAccountHistoryUserAchievementUserAchievementUnlockDetailsUserBadgeUserBeatmapsetNewDetailsUserBeatmapsetReviveDetailsUserCompactUserCompact.avatar_urlUserCompact.country_codeUserCompact.default_groupUserCompact.idUserCompact.is_activeUserCompact.is_botUserCompact.is_deletedUserCompact.is_onlineUserCompact.is_supporterUserCompact.last_visitUserCompact.pm_friends_onlyUserCompact.profile_colourUserCompact.usernameUserCompact.account_historyUserCompact.active_tournament_bannerUserCompact.active_tournament_bannersUserCompact.badgesUserCompact.beatmap_playcounts_countUserCompact.blocksUserCompact.comments_countUserCompact.countryUserCompact.coverUserCompact.daily_challenge_user_statsUserCompact.favourite_beatmapset_countUserCompact.follow_user_mappingUserCompact.follower_countUserCompact.friendsUserCompact.global_rankUserCompact.graveyard_beatmapset_countUserCompact.groupsUserCompact.guest_beatmapset_countUserCompact.is_adminUserCompact.is_bngUserCompact.is_gmtUserCompact.is_limited_bnUserCompact.is_moderatorUserCompact.is_natUserCompact.is_restrictedUserCompact.is_silencedUserCompact.loved_beatmapset_countUserCompact.mapping_follower_countUserCompact.monthly_playcountsUserCompact.nominated_beatmapset_countUserCompact.pageUserCompact.pending_beatmapset_countUserCompact.previous_usernamesUserCompact.rank_highestUserCompact.rank_historyUserCompact.ranked_beatmapset_countUserCompact.replays_watched_countsUserCompact.scores_best_countUserCompact.scores_first_countUserCompact.scores_pinned_countUserCompact.scores_recent_countUserCompact.statisticsUserCompact.statistics_rulesetsUserCompact.support_levelUserCompact.teamUserCompact.unread_pm_countUserCompact.user_achievementsUserCompact.user_preferences
UserCoverUserGroupUserKudosuUserMonthlyPlaycountUserPreferencesUserRelationUserReplaysWatchedCountUserScoreAggregateUserSilenceUserStatisticVariantUserStatisticsUserStatistics.accuracyUserStatistics.count_300UserStatistics.count_100UserStatistics.count_50UserStatistics.count_missUserStatistics.country_rankUserStatistics.global_rankUserStatistics.global_rank_expUserStatistics.grade_countsUserStatistics.hit_accuracyUserStatistics.is_rankedUserStatistics.levelUserStatistics.maximum_comboUserStatistics.play_countUserStatistics.play_timeUserStatistics.ppUserStatistics.pp_expUserStatistics.rank_change_since_30_daysUserStatistics.recommended_difficultyUserStatistics.recommended_difficulty_expUserStatistics.ranked_scoreUserStatistics.replays_watched_by_othersUserStatistics.total_hitsUserStatistics.total_scoreUserStatistics.userUserStatistics.variants
UserStatisticsRulesetsUserSupportAgainEventUserSupportFirstEventUserSupportGiftEventUserTeamUserTeamStatisticsUsernameChangeEventVersionsVotersSummaryVotesSummaryWikiPage
- Utility
BeatmapsetSearchFilterBeatmapsetSearchFilter.filtersBeatmapsetSearchFilter.set_extra()BeatmapsetSearchFilter.set_generals()BeatmapsetSearchFilter.set_genre()BeatmapsetSearchFilter.set_language()BeatmapsetSearchFilter.set_mode()BeatmapsetSearchFilter.set_nsfw()BeatmapsetSearchFilter.set_played()BeatmapsetSearchFilter.set_query()BeatmapsetSearchFilter.set_ranked()BeatmapsetSearchFilter.set_sort()BeatmapsetSearchFilter.set_status()
IdentitiesUtilNotificationsUtilPlaylistItemUtil
- Enums
BeatmapsetEventSortBeatmapsetEventTypeBeatmapsetGenreBeatmapsetLanguageBeatmapsetSearchExtraBeatmapsetSearchGeneralBeatmapsetSearchPlayedBeatmapsetSearchSortBeatmapsetSearchStatusChatChannelTypeChatMessageTypeCommentSortForumTopicTypeGameModeIntGameModeStrKudosuActionMatchEventTypeMatchSortMessageTypeModModsMultiplayerScoresSortNotificationCategoryNotificationTypeObjectTypePlaylistQueueModeRankStatusRankingTypeRealTimeQueueModeRoomCategoryRoomFilterModeRoomSortRoomStatusRoomTypeScoreRankScoringTypeTeamTypeUserAccountHistoryTypeUserBeatmapTypeUserRelationTypeUserScoreTypeWikiSearchMode
- Core Classes