Leaderboards

Get a leaderboard

One page of a leaderboard, with yesterday's rank for every row.

GET/v1/leaderboards/{board}

DonutSMP boards are served from complete snapshots only, so you never get a half finished board. Each row carries its rank and value from the previous day's snapshot, so you can show who climbed and who fell.

The money board is the whole baltop, roughly 90,000 players. Page through it with limit=500. For older versions of a board, use snapshots.

Authentication

API key with the read scope

Cached for

1 min

Data updates

DonutSMP boards every 6 hours. Kills and shards with every lookup. Bounties every 15 minutes.

curl "https://api.donutstats.io/v1/leaderboards/money?limit=3" \
  -H "x-api-key: $DONUTSTATS_API_KEY"

Response200OK

{
  "board": {
    "id": "money",
    "label": "Money",
    "stat": "money",
    "source": "leaderboard",
    "updatedAt": 1792694462533,
    "entries": 89727
  },
  "page": 1,
  "limit": 3,
  "total": 89727,
  "entries": [
    {
      "rank": 1,
      "username": "Abuodee",
      "uuid": "e9cbdbda-bc07-4cb5-8ad5-793a20b33dbd",
      "value": 4800000000000,
      "previousRank": 1,
      "previousValue": 4400000000000
    },
    {
      "rank": 2,
      "username": "Wampiptiii01",
      "uuid": "f6a98cc5-86ee-4f24-b980-600aa81bcff2",
      "value": 3900000000000,
      "previousRank": 2,
      "previousValue": 3600000000000
    }
  ]
}

Try itCounts towards your plan

Path parameters

boardstringrequired
Which board.
moneydeathsplaytimeplacedBlocksbrokenBlocksmobsKilledkillsshardsbounties

Query parameters

pageintegeroptionaldefault 1
Page to return, starting at 1.
1 to 100,000
limitintegeroptionaldefault 100
Entries per page.
1 to 500

Response

The board and one page of rows.

boardBoard
The board you asked for.
ShowHide6 child fields
- idstring
  Board id: money, deaths, playtime, placedBlocks, brokenBlocks, mobsKilled, kills, shards or bounties.
- labelstring
  Human readable name, for example Blocks Placed.
- statstring
  The stat the board ranks, or bounty.
- sourcestring
  leaderboard for DonutSMP's own leaderboards, tracked for boards DonutStats ranks itself (kills and shards, which DonutSMP has no leaderboard for), bounty for the bounty board.
- updatedAttimestamp | null
  When the board last changed.
- entriesinteger
  Players on the board.
pageinteger
The page you asked for.
limitinteger
Rows per page.
totalinteger
Rows on the whole board.
entriesBoardEntry[]
Rows, best first.
ShowHide6 child fields
- rankinteger
  Position, starting at 1.
- usernamestring
  The player.
- uuidstring | null
  Minecraft UUID, once known.
- valuenumber
  The ranked value: money, a count, seconds of playtime or a bounty.
- previousRankinteger | null
  Rank in the previous day's snapshot. null for new entries and for tracked and bounty boards.
- previousValuenumber | null
  Value in the previous day's snapshot.

Status codes

Status	When
400Bad Request	Unknown board id.