Players

Get a player

A full profile, refreshed live when it is stale.

GET/v1/players/{username}

Returns everything DonutStats knows about a player: every stat, their place on each leaderboard, presence, bounty and what they are selling.

By default the API makes sure the stats are fresh. If they are more than 30 seconds old, they are refreshed live and the response waits up to 15 seconds for the new numbers. Read live lookups before you call this in a loop.

Authentication

API key with the read scope

Cached for

15 s

Data updates

Live with lookup=auto or force. With none, as fresh as the last lookup.

curl "https://api.donutstats.io/v1/players/Abuodee?lookup=none" \
  -H "x-api-key: $DONUTSTATS_API_KEY"

Response200OK

{
  "player": {
    "username": "Abuodee",
    "uuid": "e9cbdbda-bc07-4cb5-8ad5-793a20b33dbd",
    "firstSeenAt": 1791505885469,
    "lastSeenAt": 1792723646257,
    "lastChatAt": 1792347373296,
    "stats": {
      "money": 4800000000000,
      "shards": 128000,
      "kills": 8000,
      "deaths": 1400,
      "playtime": 14745600,
      "placedBlocks": 496000,
      "brokenBlocks": 217000,
      "mobsKilled": 51900
    },
    "statsUpdatedAt": 1792722587957,
    "valuesUpdatedAt": 1792722587957,
    "ranks": {
      "money": {
        "rank": 1,
        "value": 4800000000000,
        "updatedAt": 1792694462533
      },
      "playtime": {
        "rank": 396,
        "value": 14745600,
        "updatedAt": 1792722208596
      }
    },
    "views30d": 954,
    "viewsTotal": 954,
    "presence": {
      "online": false,
      "pingMs": null,
      "checkedAt": 1792722587957,
      "lastOnlineAt": 1792694335419
    },
    "bounty": {
      "amount": 400000,
      "since": 1792649935472
    },
    "listings": {
      "open": 5,
      "value": 40067000000,
      "checkedAt": 1792722589688
    }
  },
  "lookup": {
    "status": "skipped",
    "checkedAt": 1792722587957
  }
}

Try itCounts towards your plan

202 Accepted

When the player is new to DonutStats and the refresh has not finished within 15 seconds, you get status 202 with player: null and lookup.status: pending. Ask again in a few seconds and the stats will be there.

Lookups have their own budget

Live refreshes are expensive, so each key can start a limited number per minute on top of its request limit. Past that, you get stored data with lookup.status: rate_limited. Use lookup=none for bulk reads.

Path parameters

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

Query parameters

lookupstringoptionaldefault auto
auto: refresh stats older than 30 seconds. force: always refresh, needs the force scope. none: return stored data only, never wait.
autoforcenone

Response

The player and what the lookup did.

playerPlayer | null
The profile. null only with status 202.
ShowHide14 child fields
- usernamestring
  Username with its current capitalization.
- uuidstring | null
  Minecraft UUID, once known.
- firstSeenAttimestamp
  When the player first appeared in DonutStats.
- lastSeenAttimestamp
  When the player last showed up anywhere: chat, a leaderboard, a listing or a lookup.
- lastChatAttimestamp | null
  When the player last chatted in public chat.
- statsobject
  Every stat we know. A stat is left out until we have it.
  ShowHide8 child fields
  - moneynumber
    Balance in DonutSMP dollars.
  - shardsinteger
    Shards held.
  - killsinteger
    Player kills.
  - deathsinteger
    Deaths.
  - playtimeinteger
    Playtime in seconds.
  - placedBlocksinteger
    Blocks placed.
  - brokenBlocksinteger
    Blocks broken.
  - mobsKilledinteger
    Mobs killed.
- statsUpdatedAttimestamp | null
  When the player's full stats were last refreshed.
- valuesUpdatedAttimestamp | null
  When any single stat last changed, including from a leaderboard.
- ranksobject
  The player's place on each leaderboard they appear on, keyed by board id (money, deaths, playtime, placedBlocks, brokenBlocks, mobsKilled).
  ShowHide3 child fields
  - rankinteger
    Position on the leaderboard, starting at 1.
  - valuenumber
    The ranked value.
  - updatedAttimestamp
    When that leaderboard snapshot was complete.
- views30dinteger
  Profile views on DonutStats in the last 30 days.
- viewsTotalinteger
  Profile views on DonutStats, all time.
- listingsobject
  What the player is selling on the auction house.
  ShowHide3 child fields
  - openinteger
    Open listings by this player.
  - valuenumber
    Total asking price of those listings.
  - checkedAttimestamp | null
    When the player's listings were last refreshed. null if never.
- presenceobject
  Whether the player is online, as of the last refresh.
  ShowHide4 child fields
  - onlineboolean | null
    true when they were online at checkedAt.
  - pingMsinteger | null
    Their ping in milliseconds, when online.
  - checkedAttimestamp | null
    When presence was checked.
  - lastOnlineAttimestamp | null
    The last time they were seen online.
- bountyobject | null
  The open bounty on this player, or null.
  ShowHide2 child fields
  - amountnumber
    Bounty in DonutSMP dollars.
  - sincetimestamp
    When the bounty first appeared.
lookupLookup
What the live lookup did.
ShowHide2 child fields
- statusstring
  One of fresh, updated, not_found, pending, rate_limited, unavailable or skipped. See live lookups.
- checkedAttimestamp | null
  When the stats you got were last refreshed.

Status codes

Status	When
202Accepted	The player is not stored yet and the lookup is still running. Retry shortly.
400Bad Request	The username is not a valid Minecraft username.
403Forbidden	You sent `lookup=force` with a key that lacks the `force` scope.
404Not Found	No such player on DonutSMP, or not stored and `lookup=none`.
429Too Many Requests	The lookup budget is used up and there is no stored data to fall back on.