Leaderboards

Get a snapshot

One past version of a leaderboard, page by page.

GET/v1/leaderboards/{board}/snapshots/{id}

Returns the rows of one snapshot exactly as the board stood at that moment. Snapshots never change once they are complete, so responses are cached for 5 minutes and you can cache them forever on your side.

Authentication

API key with the read scope

Cached for

5 min

Data updates

Never changes.

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

Response200OK

{
  "snapshot": {
    "id": 468,
    "board": "money",
    "day": "2026-10-23",
    "startedAt": 1792726320587,
    "finishedAt": 1792726740051,
    "entries": 89952
  },
  "page": 1,
  "limit": 3,
  "total": 89952,
  "entries": [
    {
      "rank": 1,
      "username": "Abuodee",
      "uuid": "e9cbdbda-bc07-4cb5-8ad5-793a20b33dbd",
      "value": 4800000000000
    },
    {
      "rank": 2,
      "username": "Wampiptiii01",
      "uuid": "f6a98cc5-86ee-4f24-b980-600aa81bcff2",
      "value": 4000000000000
    },
    {
      "rank": 3,
      "username": "Ehxy",
      "uuid": "a7c8c10c-2bce-4c64-80c0-7ec20e93a471",
      "value": 2100000000000
    }
  ]
}

Try itCounts towards your plan

Path parameters

boardstringrequired
The board the snapshot belongs to.
moneydeathsplaytimeplacedBlocksbrokenBlocksmobsKilled
idintegerrequired
Snapshot id from list snapshots.

Query parameters

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

Response

The snapshot and one page of rows.

snapshotSnapshot
The snapshot you asked for.
ShowHide6 child fields
- idinteger
  Snapshot id. Use it with /v1/leaderboards/{board}/snapshots/{id}.
- boardstring
  Board id.
- daystring
  UTC date the snapshot belongs to, YYYY-MM-DD.
- startedAttimestamp
  When the snapshot started.
- finishedAttimestamp
  When the snapshot was complete.
- entriesinteger
  Players on the board at that time.
pageinteger
The page you asked for.
limitinteger
Rows per page.
totalinteger
Rows in the whole snapshot.
entriesobject[]
Rows, best first.
ShowHide4 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.

Status codes

Status	When
400Bad Request	Unknown board or a malformed id.
404Not Found	No complete snapshot with this id on this board.