Leaderboards
Read daily, weekly and all-time mission-XP rankings for players and teams, computed in UTC with deterministic ranks.
A leaderboard ranks the XP your players earned from completing missions over a period. It is computed from your tenant's own completions only; two organizers with the same player identifiers see entirely separate boards.
| Route | Scope | Rate class |
|---|---|---|
GET /v1/gamification/leaderboards/:period/:entityType | gamification-progress:read | read |
Periods and entity types
period | Covers |
|---|---|
daily | The current UTC day |
weekly | The current UTC week, from Monday 00:00 UTC up to and including today |
alltime | Every completion since the player started |
entityType | Ranks |
|---|---|
player | Each player by the XP of the missions they completed |
team | Each team by the XP of completions attributed to it |
Any other value is 422 LEADERBOARD_PERIOD_UNSUPPORTED or 422 LEADERBOARD_ENTITY_UNSUPPORTED,
with a message naming the supported values.
Boundaries are always UTC, whatever your players' time zones. At 00:00 UTC the daily board starts
empty, and on Monday at 00:00 UTC so does the weekly board.
What counts
- Each mission completion contributes the XP of that mission's
xprewards and counts as one completed mission. XP from chest drops or battle-pass tier rewards does not count. - A mission contributes at most once per player per UTC day.
- A completion counts toward a team only if the event that completed it carried a
teamIdin its payload (see Event ingestion). Completions without a team never appear on the team board; they are not grouped under an empty team.
Read a board
This reads the weekly player board; swap in any period and entity type. The response below is for
weekly and team.
curl "$GAMIFICATION_API_URL/v1/gamification/leaderboards/weekly/player?page=1&limit=20" \
-H "Authorization: Bearer $TANITAR_API_KEY"{
"period": "weekly",
"entityType": "team",
"periodKey": "2026-09-28",
"page": 1,
"limit": 20,
"entries": [
{ "rank": 1, "entityId": "team-orange", "totalXp": 1450, "missionsCompleted": 11 },
{ "rank": 2, "entityId": "team-blue", "totalXp": 1450, "missionsCompleted": 9 },
{ "rank": 3, "entityId": "team-green", "totalXp": 900, "missionsCompleted": 7 }
]
}| Field | Meaning |
|---|---|
periodKey | The UTC date for daily, the UTC Monday for weekly, all for alltime |
entries[].entityId | Your player id or team id, as you sent it |
entries[].totalXp | Mission XP in the period |
entries[].missionsCompleted | Completions in the period |
entries[].rank | Position on the board |
Pagination
The board uses page and limit query parameters: page starts at 1 (default 1), limit is 1 to
100 (default 20). Pages are cut from the top 100 entries, so a board shows at most 100 entities.
The response carries no total count; an entries list shorter than limit is the last page. See
Pagination.
Ranks and ties
Ranks are positional (1, 2, 3) with no shared ranks. Entities with equal totalXp are ordered by
entityId ascending, so the same history always produces the same board in the same order. In the
example above, team-orange ranks ahead of team-blue because its id sorts first.
Freshness
A board may be served from a cache for up to five minutes, so a completion can take that long to appear. If the cache is unavailable, the board is computed on each read instead; a read never fails because of the cache.
What your players see
Players read the same boards from the hosted experience, through the Player plane
(GET /player/v1/gamification/leaderboards/:period/:entityType) with the same periods, entity types and paging. They
always see the board of the organizer they signed in with, and only the entity identifiers and
totals shown above.