Gamification primitive · feature guide

The leaderboard backend service.

What is a leaderboard api? A leaderboard API is a backend service that maintains ranked standings — by XP, streak length, or any custom event count — so your app reads ranks instead of computing them. Amba adds leagues on top: small weekly cohorts with automatic promotion and relegation at the week boundary, the competitive loop behind Duolingo-style retention.

Get an API key →All featuresupdated June 12, 2026
the agent path:

A leaderboard is a ranking query that starts cheap and gets expensive: scores update constantly, ranks are global, and the naive ORDER BY becomes a hot path the moment the board appears on the home screen. Amba ships leaderboards as definitions — a metric (XP, streak length, or a custom event count), a period (daily, weekly, monthly, all-time), and an entry cap — with standings recomputed on a schedule into a projection your app reads in one call. Leagues are the second layer: instead of one global list where rank #48,201 motivates nobody, users compete in cohorts of roughly 30 for a week, and the top and bottom of each cohort promote and relegate at the weekly rollover. Both are provisioned by tool call and read by SDK.

How are leaderboards ranked and refreshed?

A leaderboard definition names its metric — xp (total XP), streak (longest streak), or custom (count of a named event) — and a period: all_time, daily, weekly, or monthly, with a configurable entry cap (default 100). Standings are recomputed on a schedule, every 15 minutes, into a read-optimized projection: your app fetches ranked entries with display names and avatars, plus the calling user’s own rank, without any score math client-side. The definition’s key (equal to its name) is the handle the SDK reads by.

How do leagues (promotion and relegation) work?

Leagues are tiers — Bronze, Silver, Gold, each created with a tier_order — where users compete in weekly cohorts of about 30 (cohort_size, configurable). Scoring is XP earned during the week. At the weekly rollover, Monday 00:00 UTC, each cohort’s top performers promote one tier (promote_count, default 5) and its bottom performers relegate one tier (demote_count, default 5); everyone else stays. The rollover also emits league_promoted and league_demoted events, so push campaigns and segments can react to movement. New users enter at the lowest tier; a freshly created league has no cohorts until the first rollover runs.

When do I want a leaderboard, and when a league?

A leaderboard answers "who is best" — one ranked list, good for all-time prestige and short-window competitions. A league answers "am I keeping up with people like me" — small cohorts where mid-pack users can realistically win a promotion this week. Retention-driven consumer apps usually want both: an all-time or weekly board for the top 1%, and leagues to give the other 99% a stake. The table below contrasts the two as shipped.

Leaderboards vs leagues — as shipped
DimensionLeaderboardLeague
ShapeOne ranked list per definitionTiers (Bronze/Silver/Gold) of weekly cohorts, ~30 users each
Metricxp, streak, or custom event countXP earned during the week
Periodall_time, daily, weekly, or monthlyWeekly, ISO week boundary
RefreshRecomputed on a schedule, every 15 minutesLive within the week; promote/demote at Monday 00:00 UTC rollover
MovementRank changes with scoreTop N promote a tier, bottom N relegate (defaults: 5 and 5)
SDK readgetEntries(key), getMyRank(key)leagues.me(), leagues.cohort()

Defaults and cadences verified against the live tool registry and the shipped schedule, June 2026.

how it works

How do I create a leaderboard and leagues with the API?

Board + league ladder — three tool calls (tiers come pre-seeded)

1. amba_leaderboards_create
   { "project_id": "...", "name": "weekly_xp",
     "metric": "xp", "period": "weekly",
     "max_entries": 100, "pat": "..." }
   → key equals name; the SDK reads by it

2. amba_leagues_list  { "project_id": "...", "pat": "..." }
   → every project starts with Bronze / Silver / Gold
     (tier_order 0 / 1 / 2) already seeded

3. amba_leagues_update — tune a seeded tier
   { "project_id": "...", "league_id": "<Bronze id>",
     "promote_count": 5, "demote_count": 5,
     "cohort_size": 30, "pat": "..." }

   Need a fourth tier? amba_leagues_create with
   tier_order: 3+ (0-2 are taken by the seeded ladder).

Inspect this week's cohorts:
   amba_leagues_list_cohorts
   { "project_id": "...", "league_id": "<from step 2>", "pat": "..." }
   → cohorts appear after the first weekly rollover

For a custom metric, pass "metric": "custom" plus "custom_event": "<event_name>" — the board then ranks by that event’s count.

in the app

How does the app read ranks and cohorts?

Top entries, own rank, and the weekly cohort

import { Amba } from '@layers/amba-web';

// Top 10 + the caller's own rank — no score math in the app.
const top = await Amba.leaderboards.getEntries('weekly_xp', 10);
// per entry: rank, display_name, avatar_url, score
const me = await Amba.leaderboards.getMyRank('weekly_xp');

// Leagues: current tier, live rank, and the cohort roster.
const standing = await Amba.leagues.me();
// standing.league, standing.rank, standing.score, standing.member_count
const cohort = await Amba.leagues.cohort();
// cohort.members — anonymised standings (no user ids exposed)

Verified against the published SDK surface, June 2026 — same shape on every platform SDK.

the tools

Which MCP tools cover this surface?

toolwhat it does
amba_leaderboards_createDefine a board: metric (xp | streak | custom), period, entry cap
amba_leaderboards_get_definitionInspect one definition’s metric, period, and config
amba_leaderboards_updatePatch a definition; only supplied fields change
amba_leaderboards_getFetch ranked entries with names and avatars
amba_leagues_createCreate a league tier with promote/demote counts and cohort size
amba_leagues_list_cohortsList this week’s active cohorts with member counts
the honest part

When is this not the right call?

PlayFab is deeper for tournament-grade game economies
If you are running tournaments, matchmaking, and a LiveOps virtual economy at game-studio scale, PlayFab’s games heritage runs deeper than Amba’s leaderboard surface as of mid-2026. The honest comparison, including where Amba wins for consumer mobile apps, is at /compare/playfab.
Standings refresh on a schedule, not per score event
Rank projections recompute every 15 minutes. That is well inside the staleness window a retention leaderboard needs, but it is not a frame-accurate live race UI — if scores must visibly reorder within seconds of every event, you need a purpose-built realtime ranking layer for that screen.
Promotion math is fixed-count, not percentage-based
Movement at the rollover is top promote_count up, bottom demote_count down per cohort — fixed counts, not percentile bands or Elo-style ratings. For most consumer league designs that is exactly the Duolingo-shaped behavior wanted; for skill-rating systems it is the wrong primitive.
the agent path

Can an AI agent set this up end to end?

Yes. Amba’s hosted MCP server at https://mcp.amba.dev/mcp (Streamable HTTP) exposes the whole backend as tool calls. amba_developer_signup mints a developer token and a provisioned project — client key and server key included — with no browser, and the project goes active in about ten seconds. An agent can stand up the full competitive layer in three tool calls — create the weekly XP board, list the pre-seeded Bronze/Silver/Gold ladder, tune its counts — then write the two SDK reads into the leaderboard screen.

questions

Leaderboard API — FAQ

What is a leaderboard API?

A backend service that maintains ranked user standings so your app reads ranks instead of computing them. You define the metric (XP, streak length, or a custom event count) and period (daily, weekly, monthly, all-time); the service recomputes standings on a schedule and serves ranked entries plus the calling user’s own rank.

How often do leaderboard rankings update?

Standings are recomputed on a schedule every 15 minutes into a read-optimized projection. Within-week league scores accumulate continuously from XP events; league movement (promotion and relegation) happens once per week at the Monday 00:00 UTC rollover.

Does Amba support promotion and relegation leagues?

Yes — leagues are first-class. Each tier is created with a tier_order, a weekly cohort size (default 30), and promote/demote counts (default 5 each). At the weekly rollover the top of each cohort moves up a tier and the bottom moves down, emitting league_promoted and league_demoted events your campaigns can target.

Can I rank users by something other than XP?

Yes. A leaderboard’s metric can be xp (total XP), streak (longest streak), or custom — the count of any named event you track, set via custom_event. Leagues specifically score XP earned during the week, which is what makes their weekly competition meaningful.

How do I show the user’s own rank without fetching the whole board?

Amba.leaderboards.getMyRank(key) returns just the calling user’s entry — rank and score — in one call. For leagues, Amba.leagues.me() returns the user’s tier, live cohort rank, score, and cohort size; Amba.leagues.cohort() returns the full anonymised roster for rendering the weekly screen.

sources

Sources for this guide

keep reading
Amba vs PlayFabAmba vs FirebaseLanguage learning & edtech appsFitness appsMobile games
start in 30 seconds

Hand the docs to your agent.
Ship by lunch.

Read the docs