Leaderboards

List leaderboard snapshots

Every complete version of a leaderboard ever recorded.

GET/v1/leaderboards/{board}/snapshots

A new snapshot of each DonutSMP leaderboard is recorded every 6 hours and kept forever. This lists them newest first. Read one in full with get a snapshot.

Use from and to to find the snapshot closest to a date, for example the baltop on the first of the month.

Authentication

API key with the read scope

Cached for

1 min

Data updates

A new snapshot every 6 hours.

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

Response200OK

{
  "limit": 3,
  "next": "MTc5MjY3MjMyODIzOC40NTA",
  "entries": [
    {
      "id": 468,
      "board": "money",
      "day": "2026-10-23",
      "startedAt": 1792726320587,
      "finishedAt": 1792726740051,
      "entries": 89952
    },
    {
      "id": 456,
      "board": "money",
      "day": "2026-10-22",
      "startedAt": 1792693913119,
      "finishedAt": 1792694462533,
      "entries": 89727
    },
    {
      "id": 450,
      "board": "money",
      "day": "2026-10-22",
      "startedAt": 1792672313164,
      "finishedAt": 1792672328238,
      "entries": 3015
    }
  ]
}

Try itCounts towards your plan

Path parameters

boardstringrequired
Which board. Only DonutSMP boards have snapshots.
moneydeathsplaytimeplacedBlocksbrokenBlocksmobsKilled

Query parameters

fromtimestampoptional
Only entries at or after this time, in Unix milliseconds.
totimestampoptional
Only entries before this time, in Unix milliseconds.
limitintegeroptionaldefault 100
Entries per page.
1 to 500
cursorstringoptional
The next value from the previous response. Leave it out for the first page. See cursors.

Response

A feed of snapshots, newest first. Filters apply to finishedAt.

limitinteger
Entries per page.
nextstring | null
Pass this as cursor to get the next page. null on the last page.
entriesSnapshot[]
The entries on this page, newest first.
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.

Status codes

Status	When
400Bad Request	Unknown board, or a malformed `cursor`.