Players

Get a player's rank history

Every rank a player has held on every leaderboard.

GET/v1/players/{username}/ranks

Returns one point per leaderboard snapshot the player appeared in: their rank and value at that moment. Use it to chart how a player climbed the baltop, or when they dropped off a board.

Points are grouped by board, oldest first. Boards the player never appeared on are left out.

Authentication

API key with the read scope

Cached for

1 min

Data updates

A point is added with every leaderboard snapshot.

curl "https://api.donutstats.io/v1/players/Abuodee/ranks?board=money&days=30" \
  -H "x-api-key: $DONUTSTATS_API_KEY"

Response200OK

{
  "username": "Abuodee",
  "days": 30,
  "ranks": {
    "money": [
      {
        "t": 1791506522612,
        "day": "2026-10-09",
        "rank": 1,
        "value": 4000000000000
      },
      {
        "t": 1791517009834,
        "day": "2026-10-09",
        "rank": 1,
        "value": 4000000000000
      }
    ]
  }
}

Try itCounts towards your plan

Path parameters

usernamestringrequired
Minecraft username, case insensitive. 1 to 16 letters, digits or underscores, with an optional leading dot for Bedrock players.

Query parameters

boardstringoptional
Only this board. Leave it out to get all six.
moneydeathsplaytimeplacedBlocksbrokenBlocksmobsKilled
daysintegeroptionaldefault 365
How many days back to go.
1 to 3,650

Response

Rank history keyed by board.

usernamestring
The username you asked for.
daysinteger
The window you asked for.
ranksobject
One array per board, oldest first.
ShowHide4 child fields
- ttimestamp
  When the snapshot was complete.
- daystring
  UTC date of the snapshot.
- rankinteger
  Rank on the board, starting at 1.
- valuenumber
  The ranked value.

Status codes

Status	When
400Bad Request	Invalid username, board or days.
404Not Found	The player is not on record.