# Leaderboard

> Rank-based competition, scoped by time window and audience.

Source: https://docs.hatched.live/docs/concepts/leaderboard

A leaderboard ranks buddies by a scoring function over a window. It's
optional — not every product benefits from ranking, and ranking can be
stressful. When it fits, though, it's a strong pull.

## What defines a leaderboard

- **Metric** — coins earned, skills-leveled, streaks completed, a custom sum.
- **Window** — all-time, monthly, weekly, custom cohort.
- **Scope** — global (across all buddies of the customer), per-audience, or
  per-group (classroom, team, etc.).
- **Visibility** — public to all, visible only to the buddy's own rank ±3
  entries, or admin-only.

## Example

> **Weekly coin leaderboard, scoped to the `students` audience.** Resets
> every Monday. Each student sees their own rank plus the five nearest
> neighbours; admins see the full list.

## How it computes

Leaderboards are snapshotted periodically (default every 10 minutes) and
cached. Reads from the widget or API hit the snapshot, not the live
aggregate — this keeps performance stable regardless of scale.

A refresh fires `leaderboard.snapshot.ready` if you want to react on your
backend.

## Gotchas

- Leaderboards can demotivate the bottom ranks. Consider scoping visibility
  to "within ±N of me" rather than the whole list.
- Per-group leaderboards require you to pass a `groupId` on events; without
  it, the event doesn't count toward group ranking.
- Weekly/monthly windows reset in UTC. Cross-timezone products may see a
  sudden "reset" mid-day for some users.

## Related

- [Audiences](/docs/concepts/audiences) — scope a leaderboard to one user group.
- [Streaks](/docs/concepts/streaks) — a common leaderboard metric.
- [Leaderboard widget](/docs/reference/widgets/leaderboard) — rendering it in your product.