Osu! API - rocks.rive.wtf API

Every API key is tied to one IP. To apply for a key, DM southctrl on Discord.

Use the endpoint path below, replace the required params, and send Authorization: Bearer YOUR_API_KEY.

Most Used Endpoints

User

Look up an osu! player

Recent Plays

Get the latest plays

Best Plays

Fetch top performance scores

Beatmaps

Search for beatmaps

Start with user, then add recent plays or best plays depending on what show.

Get User

Get detailed information about an Osu! player.

Endpoint

GET /api/osu/user

Query Parameters

username

string

osu! username. Use username or user_id.

user_id

integer

osu! user ID. Use username or user_id.

mode

string

default:"osu"

Mode: osu, taiko, fruits, or mania.

Example Request

curl -X GET "https://rocks.rive.wtf/api/osu/user?username=peppy&mode=osu" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "id": 2,
  "username": "peppy",
  "join_date": "2007-08-28T03:09:12+00:00",
  "country_code": "AU",
  "avatar_url": "https://a.ppy.sh/2?1657169614.png",
  "cover_url": "https://assets.ppy.sh/user-profile-covers/2/baba245ef60834b769694178f8f6d4f6166c5188c740de084656ad2b80f1eea7.jpeg",
  "is_online": false,
  "is_supporter": true,
  "mode": "osu",
  "badges": [],
  "statistics": {
    "level": 67,
    "level_progress": 51,
    "pp": 1188.72,
    "global_rank": 751674,
    "country_rank": 15440,
    "ranked_score": 464614954,
    "accuracy": 96.7969,
    "play_count": 7761,
    "play_time": 744444,
    "total_score": 2029450214,
    "total_hits": 839285,
    "max_combo": 746,
    "replays_watched": 16673,
    "grade_counts": {
      "ss": 15,
      "ssh": 0,
      "s": 67,
      "sh": 0,
      "a": 178
    }
  }
}

Response Fields

number

Unique user ID

username

string

Player username

join_date

string

Account creation date (ISO 8601 format)

country_code

string

Two-letter country code

avatar_url

string

URL to player’s avatar image

cover_url

string

URL to player’s profile cover image

is_online

boolean

Whether the player is currently online

is_supporter

boolean

Whether the player has supporter status

mode

string

Current game mode

badges

array

Array of badge objects earned by the player

statistics

object

Player statistics

Show Statistics fields

level

number

Player level

level_progress

number

Progress to next level (0-100)

number

Performance points (PP)

global_rank

number

Global ranking position

country_rank

number

Country ranking position

ranked_score

number

Total ranked score

accuracy

number

Overall accuracy percentage

play_count

number

Total number of plays

play_time

number

Total play time in seconds

total_score

number

Total score across all plays

total_hits

number

Total number of hits

max_combo

number

Maximum combo achieved

replays_watched

number

Number of replays watched by others

grade_counts

object

Count of grades achieved

Show Grade counts

ss - SS rank count
ssh - Silver SS rank count
s - S rank count
sh - Silver S rank count
a - A rank count

Get Recent Plays

Get a player’s recent plays.

Endpoint

GET /api/osu/user/recent

Query Parameters

username

string

required

Player username.

mode

string

default:"osu"

Mode: osu, taiko, fruits, or mania.

limit

integer

default:"10"

Number of recent plays (max 50).

Example Request

curl -X GET "https://rocks.rive.wtf/api/osu/user/recent?username=peppy&mode=osu&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "count": 0,
  "scores": []
}

If the player has no recent plays, the scores array will be empty.

Get Best Plays

Get a player’s top/best plays.

Endpoint

GET /api/osu/user/best

Query Parameters

username

string

required

Player username.

mode

string

default:"osu"

Mode: osu, taiko, fruits, or mania.

limit

integer

default:"10"

Number of best plays (max 100).

Example Request

curl -X GET "https://rocks.rive.wtf/api/osu/user/best?username=peppy&mode=osu&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "count": 10,
  "scores": [
    {
      "id": 1720541511,
      "accuracy": 1,
      "created_at": "2014-03-25T03:58:04Z",
      "max_combo": 450,
      "mods": ["PF"],
      "pp": 73.2294,
      "rank": "X",
      "score": 2669868,
      "beatmap": {
        "id": 22423,
        "difficulty_rating": 3.58485,
        "version": "Hard"
      },
      "beatmapset": {
        "id": 3720,
        "title": "Tori no Uta -Ethereal House Mix-",
        "artist": "Lix",
        "creator": "James",
        "cover_url": "https://assets.ppy.sh/beatmaps/3720/covers/cover.jpg?1622021201"
      }
    }
  ]
}

Response Fields

count

number

Total number of scores returned

scores

array

Array of score objects

Show Score object fields

number

Unique score ID

accuracy

number

Play accuracy (0-1, where 1 = 100%)

created_at

string

When the score was set (ISO 8601 format)

max_combo

number

Maximum combo achieved

mods

array

Array of mod abbreviations used (e.g., [“HD”, “DT”])

number

Performance points awarded

rank

string

Grade achieved (X, S, A, B, C, D)

score

number

Total score

beatmap

object

Beatmap information

Show Beatmap fields

id - Beatmap ID
difficulty_rating - Star rating
version - Difficulty name

beatmapset

object

Beatmap set information

Show Beatmap set fields

id - Beatmap set ID
title - Song title
artist - Song artist
creator - Map creator username
cover_url - Cover image URL

Search Beatmaps

Search for beatmaps by query.

Endpoint

GET /api/osu/beatmaps/search

Query Parameters

query

string

required

Search query (song name, artist, mapper, etc.).

mode

string

Filter by game mode. Options: osu, taiko, fruits, mania.

Example Request

curl -X GET "https://rocks.rive.wtf/api/osu/beatmaps/search?query=freedom%20dive&mode=osu" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "beatmapsets": [
    {
      "id": 2370527,
      "title": "Vector to the Heavens (Xion) (Cityyy Remix)",
      "artist": "Yoko Shimomura",
      "creator": "Cityyy",
      "cover_url": "https://assets.ppy.sh/beatmaps/2370527/covers/cover.jpg?1769392934",
      "status": "RANKED",
      "play_count": 1880,
      "favourite_count": 49,
      "beatmaps": [
        {
          "id": 5115566,
          "version": "In the Ethereal Silence Between Passion & Serenity, We Shatter",
          "difficulty_rating": 7.54478,
          "mode": "STANDARD"
        }
      ]
    }
  ],
  "total": 50
}

Response Fields

beatmapsets

array

Array of beatmap set objects

Show Beatmap set fields

number

Beatmap set ID

title

string

Song title

artist

string

Song artist

creator

string

Map creator username

cover_url

string

Cover image URL

status

string

Ranked status (RANKED, QUALIFIED, LOVED, etc.)

play_count

number

Total number of plays

favourite_count

number

Number of favorites

beatmaps

array

Array of individual beatmap difficulties

Show Beatmap difficulty fields

id - Beatmap ID
version - Difficulty name
difficulty_rating - Star rating
mode - Game mode (STANDARD, TAIKO, CTB, MANIA)

total

number

Total number of results found (limited to 50)

Game Modes

Mode	String Value	Description
osu! (Standard)	`osu`	Original click-the-circles mode
Taiko	`taiko`	Drum rhythm mode
Catch the Beat	`fruits`	Catch falling fruits mode
osu!mania	`mania`	Piano/rhythm game mode

Grade Ranks

Rank	Description
X (SS)	100% accuracy
XH (SSH)	100% accuracy with HD/FL
S	>95% accuracy
SH	>95% accuracy with HD/FL
A	>90% accuracy
B	>80% accuracy
C	>70% accuracy
D	>70% accuracy

Common Mods

Mod	Name	Effect
NF	No Fail	Cannot fail
EZ	Easy	Easier gameplay
HD	Hidden	Circles fade out
HR	Hard Rock	Harder gameplay
DT	Double Time	1.5x speed
HT	Half Time	0.75x speed
NC	Nightcore	DT with pitch shift
FL	Flashlight	Limited vision
SO	Spun Out	Auto-spin
PF	Perfect	SS or retry

Play time is returned in seconds. Convert to hours with play_time / 3600.

Accuracy is returned as a decimal (0-1). Multiply by 100 for percentage display.

Getting Started

Social Media

Developer

Gaming

Sports

Entertainment

Profiles & Lookup

Crypto & Finance

Utilities

Documentation Index

​Most Used Endpoints

User

Recent Plays

Best Plays

Beatmaps

​Get User

​Endpoint

​Query Parameters

​Example Request

​Example Response

​Response Fields

​Get Recent Plays

​Endpoint

​Query Parameters

​Example Request

​Example Response

​Get Best Plays

​Endpoint

​Query Parameters

​Example Request

​Example Response

​Response Fields

​Search Beatmaps

​Endpoint

​Query Parameters

​Example Request

​Example Response

​Response Fields

​Game Modes

​Grade Ranks

​Common Mods

Most Used Endpoints

Get User

Endpoint

Query Parameters

Example Request

Example Response

Response Fields

Get Recent Plays

Endpoint

Query Parameters

Example Request

Example Response

Get Best Plays

Endpoint

Query Parameters

Example Request

Example Response

Response Fields

Search Beatmaps

Endpoint

Query Parameters

Example Request

Example Response

Response Fields

Game Modes

Grade Ranks

Common Mods