Leaderboards

Rank users by XP, streak length, or custom metrics with all-time, daily, weekly, and monthly periods.

Leaderboards rank users by a metric over a time period. Great for adding competitive elements to your app.

How it works

Admin defines a leaderboard with a metric (XP, streak, or custom event count) and period
Entries are updated automatically as users earn XP, maintain streaks, or track events
The client SDK fetches ranked entries and the current user's position

SDK usage

Leaderboards are addressed by their key (the slug you set when creating one), not an opaque id.

Get a leaderboard

const board = await Amba.leaderboards.get('weekly_xp');
// { key, name, metric, period, max_entries, ... }

Get leaderboard entries

// Returns up to 100 ranked entries by default. Pass `limit` to cap.
const entries = await Amba.leaderboards.getEntries('weekly_xp');
const top10 = await Amba.leaderboards.getEntries('weekly_xp', 10);
// Returns ranked entries with user display names and avatars.

getEntries(key, limit?) takes the leaderboard key and an optional numeric limit. There is no offset/pagination — entries are always returned from rank 1.

Get my rank

const myRank = await Amba.leaderboards.getMyRank('weekly_xp');
// { rank: 12, score: 1500, app_user_id: "..." }

Metrics

Metric	Description
`xp`	Total XP earned (within period)
`streak`	Longest streak (within period)
`custom`	Count of a specific event

Periods

Period	Description
`all_time`	Cumulative, never resets
`daily`	Resets every day at midnight UTC
`weekly`	Resets every Monday at midnight UTC
`monthly`	Resets on the 1st of each month

Admin API reference

Method	Path	Description
`POST`	`/admin/leaderboards`	Create leaderboard
`GET`	`/admin/leaderboards`	List leaderboards
`GET`	`/admin/leaderboards/:id/entries`	Get ranked entries

Client API reference

Method	Path	Description
`GET`	`/client/leaderboards`	List active leaderboards
`GET`	`/client/leaderboards/:id`	Get entries (paginated, ranked)
`GET`	`/client/leaderboards/:id/me`	Get current user's rank

MCP tools

Tool	Description
`amba_leaderboards_create`	Create a leaderboard with metric, period, and max entries
`amba_leaderboards_get`	Get leaderboard entries with user details

Example

Agent: "Create weekly and all-time XP leaderboards"

amba_leaderboards_create({
  project_id: "proj_xxx",
  name: "Weekly Top Earners",
  metric: "xp",
  period: "weekly",
  max_entries: 100
})

amba_leaderboards_create({
  project_id: "proj_xxx",
  name: "All-Time XP Leaders",
  metric: "xp",
  period: "all_time",
  max_entries: 100
})

On this page