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

List leaderboards

const leaderboards = await client.leaderboards.getAll();

Get leaderboard entries

const entries = await client.leaderboards.getEntries('lb_xxx', {
  limit: 50,
  offset: 0,
});
// Returns ranked entries with user display names and avatars

Get my rank

const myRank = await client.leaderboards.getMyRank('lb_xxx');
// Returns: { 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_create_leaderboard`	Create a leaderboard with metric, period, and max entries
`amba_get_leaderboard`	Get leaderboard entries with user details

Example

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

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

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

Database tables

Table	Purpose
`leaderboard_definitions`	Leaderboard config with metric, period, max entries
`leaderboard_entries`	Ranked entries with score, user ID, and rank

On this page