Rank customers by one score, one period at a time.
A leaderboard ranks an environment's customers by a single score: an event you aggregate, or points earned in the period. Run it once, or on a repeating day, week or month that settles itself and starts the race over.
Two sources only: one event, or points earned in the period.
An event source aggregates one declared event's occurrences in the period: count, sum, average, minimum, maximum or distinct values, the same vocabulary the rules engine uses elsewhere. A points source ranks points granted in the period, not the running balance.
- Not a balance. That's a stock, not a flow, and the points screen already shows it.
- Not a streak. Its longest run already has its own screen.
- Score as a team, optionally. Name an attribute, such as country, and everyone sharing it scores together, added up. Only count and sum fold that way.
- Gate it like anything else. An eligibility condition decides, once, whether a player is scored.
A rank and a score. Never another customer's identifier.
One call answers whichever of these a screen needs. Every entry carries a rank, a score and an attribute you choose to display, such as a name, never an id.
| Section | What it returns | Cap |
|---|---|---|
| Top | The best entries on the board right now | up to 100 |
| Around | The customers ranked just above and below the one asking | 25 each side |
| Named | A list of friends the caller supplies, ranked among themselves | 100, caller included |
Ask for the period that just settled instead of the current one, and get final ranks plus any movement.
The reward is granted, then the webhook tells you it happened.
A rank band's reward is granted automatically the moment a period settles, into the same ledger missions and streaks already pay into. The webhook that follows carries which board, which period and how many customers: a trigger for anything physical, not a number to recompute.
{ "leaderboardKey": "weekly-spend", "periodId": "0198f4c2-91a7-7c40", "periodStartUtc": "2026-07-27T00:00:00Z", "periodEndUtc": "2026-08-03T00:00:00Z", "participants": 842, "cohorts": 9, "settledAtUtc": "2026-08-03T00:15:04Z" } // identifiers and counts only. the reward is already // granted; read the standings for who got what.
Every customer's week starts and ends on the same clock.
A period runs on the project's clock, not each customer's own. A week starting at everyone's own midnight would be a different week for each of them, and nobody's rank would be comparable.
Tell us what you want customers competing over.
Describe the score, individual or by team, and the rank rewards if you want them. We will build it in a test account and settle a period while you watch.