# Quaver Rhythm Game API
> Live player and ranking data from Quaver, the competitive vertical-scrolling rhythm game (VSRG, 4-key and 7-key), served from its public v2 API. The player endpoint resolves a user by id or username and returns the profile — country, clan, avatar, linked Twitch/Twitter and join date — together with the full per-mode competitive stats for both 4K and 7K: global and country rank, performance rating, overall accuracy, ranked and total score, play count and the grade distribution (SS/S/A/B/C/D). The search endpoint finds players by name. The leaderboard endpoint returns the global ranked ladder for a mode, with each player's rank, performance rating, accuracy and play count. This is a single-game competitive-community stats API — player profiles, ratings and ladders — distinct from the other rhythm-game and gaming-leaderboard APIs in the catalogue. Live, no key on the upstream, nothing stored.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/quaver-api/..."
```

## Pricing
- **Free** (Free) — 23,000 calls/Mo, 4 req/s
- **Starter** ($5/Mo) — 285,000 calls/Mo, 12 req/s
- **Pro** ($15/Mo) — 1,255,000 calls/Mo, 30 req/s
- **Scale** ($35/Mo) — 4,450,000 calls/Mo, 80 req/s

## Endpoints

### Players

#### `GET /v1/player` — Profile + 4K & 7K competitive stats

**Parameters:**
- `user` (query, required, string) — Quaver username or numeric id Example: `Swan`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/quaver-api/v1/player?user=Swan"
```

**Response:**
```json
{
    "data": {
        "id": 1,
        "modes": {
            "4k": {
                "grades": {
                    "a": 33,
                    "b": 7,
                    "c": 1,
                    "d": 0,
                    "s": 322,
                    "x": 1,
                    "ss": 73
                },
                "accuracy": 98.45,
                "max_combo": 3588,
                "fail_count": 335,
                "play_count": 1737,
                "rank_global": 2247,
                "total_score": 1369901500,
                "rank_country": 1,
                "ranked_score": 699831269,
                "performance_rating": 706.64
            },
            "7k": {
                "grades": {
                    "a": 22,
                    "b": 16,
                    "c": 0,
                    "d": 0,
                    "s": 51,
                    "x": 0,
                    "ss": 2
                },
                "accuracy": 93.56,
                "max_combo": 625,
                "fail_count": 15,
                "play_count": 163,
                "rank_global": 5829,
                "total_score": 113870577,
                "rank_country": 1,
                "ranked_score": 99903254,
                "performance_rating": 123.8
            }
        },
        "source": "Quaver",
        "twitch": null,
        "country": "UM",
        "twitter": "Swanuh",
        "clan_tag": "Swan",
        "username": "Swan",
        "avatar_url": "https://
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/search` — Find players by name

**Parameters:**
- `query` (query, required, string) — Name to search Example: `swan`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/quaver-api/v1/search?query=swan"
```

**Response:**
```json
{
    "data": {
        "count": 50,
        "query": "swan",
        "users": [
            {
                "id": 1,
                "country": "UM",
                "clan_tag": "Swan",
                "username": "Swan",
                "avatar_url": "https://avatars.steamstatic.com/3c4f2eaab9e5e41dfb1706d21d654a81e525972a_full.jpg"
            },
            {
                "id": 12808,
                "country": "IE",
                "clan_tag": null,
                "username": "swankity",
                "avatar_url": "https://steamcdn-a.akamaihd.net/steamcommunity/public/images/avatars/e7/e75e52f81abc9b17252e8c76d8bdc2dd33974f20_full.jpg"
            },
            {
                "id": 21717,
                "country": "NZ",
                "clan_tag": null,
                "username": "SwanM8",
                "avatar_url": "https://avatars.steamstatic.com/e315c2a6786f19483dd678dd5cc325dc20a7945e_full.jpg"
            },
            {
                "id": 22376,
                "country": "BE",
                "clan_tag": null,
                "username": "Swansbeertje",
                "avatar_url": "https://avatars.steamstatic.com/2e06d85c1c7f7066d547f488cbd321ac7c465e8e_full.jpg"
            },
            {
                "id": 75485,
                "country": "US",
                "clan_tag": null,
                "username": "Swanity",
                "avatar_url": "https://avatars.steamstatic.com/9852469a4e62241c95f3c441ae351521a29f53dd_full.jpg"
    
…(truncated, see openapi.json for full schema)
```

### Rankings

#### `GET /v1/leaderboard` — Global ranked ladder for a mode

**Parameters:**
- `mode` (query, optional, string) — Game mode: 4k or 7k Example: `4k`
- `page` (query, optional, string) — Page (50 per page) Example: `0`
- `limit` (query, optional, string) — Max rows (max 100) Example: `50`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/quaver-api/v1/leaderboard?mode=4k&page=0&limit=50"
```

**Response:**
```json
{
    "data": {
        "mode": "4k",
        "page": 0,
        "count": 50,
        "source": "Quaver",
        "players": [
            {
                "id": 388808,
                "country": "AR",
                "accuracy": 99.61,
                "clan_tag": null,
                "username": "saragi32",
                "play_count": 852,
                "rank_global": 1,
                "performance_rating": 1031.35
            },
            {
                "id": 248468,
                "country": "PH",
                "accuracy": 99.35,
                "clan_tag": "ARG",
                "username": "AstolfoFanboy",
                "play_count": 3574,
                "rank_global": 2,
                "performance_rating": 1031.17
            },
            {
                "id": 15441,
                "country": "US",
                "accuracy": 99.3,
                "clan_tag": null,
                "username": "Legendary Ace",
                "play_count": 1792,
                "rank_global": 3,
                "performance_rating": 1023.58
            },
            {
                "id": 4449,
                "country": "PH",
                "accuracy": 99.53,
                "clan_tag": "ARG",
                "username": "ARG jja",
                "play_count": 673,
                "rank_global": 4,
                "performance_rating": 1021.26
            },
            {
                "id": 772185,
                "country": "ES",
                "accura
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/quaver-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "note": "user is a Quaver username (resolved via search) or a numeric id. mode is 4k (4-key) or 7k (7-key). performance_rating is Quaver's overall rating; ranks are global and within the player's country.",
        "source": "Quaver public API (api.quavergame.com/v2, live)",
        "service": "quaver-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/player": "Profile + 4K & 7K competitive stats for a user (user=Swan or user=1).",
            "GET /v1/search": "Find players by name (query=swan).",
            "GET /v1/leaderboard": "Global ranked ladder for a mode (mode=4k, page=0, limit=50)."
        },
        "description": "Live player and ranking data from Quaver, the competitive vertical-scrolling rhythm game (4K/7K keys). player resolves a user by id or username and returns the profile plus the full per-mode competitive stats for 4-key and 7-key (global/country rank, performance rating, overall accuracy, ranked & total score, play count and grade distribution). search finds players by name; leaderboard returns the global ranked ladder for a mode. Live, no key, nothing stored. A single-game competitive-community stats API distinct from the other rhythm-game and gaming-leaderboard APIs.",
        "total_users": 885301,
        "upstream_status": "ok"
    },
    "meta": {
        "timestamp": "2026-06-12T01:41:40.921Z",
        "request_id": "d27c464c-56b0-4211-b568-cf479a009380"
    },
    "status": "o
…(truncated, see openapi.json for full schema)
```


---
Marketplace page: https://www.oanor.com/api/quaver-api
OpenAPI spec: https://www.oanor.com/api/quaver-api/openapi.json