Leaderboard API

The API for leaderboards

Add recurring, all-time, and segmented leaderboards to your app in under an hour. Trophy handles scaling high-frequency leaderboard infrastructure so you stay focused on user experience. Start for free, scale to millions of users.

Get API Key API Reference

SDKs for

Endpoints

Leaderboard API endpoints

Use Trophy's leaderboard API to fetch real-time rankings and user positions. Leaderboards populate automatically from the metric events you track — no additional ranking code needed.

POST/metrics/{key}/eventView Docs

Send a metric event to track user activity and power leaderboards.

Path Parameters

keystringrequired

Unique reference of the metric as set when created.

Request Body

userUserrequired

The user that triggered the event (must include id).

valuenumberrequired

The value to add to the user's current total for the given metric.

Response

eventIdstring

Unique identifier for the created event.

totalnumber

The user's new total for this metric.

leaderboardsLeaderboard[]

Changes to leaderboard rankings.

Example

import { TrophyApiClient } from '@trophyso/node';

const trophy = new TrophyApiClient({
  apiKey: 'YOUR_API_KEY'
});


// Track a user event
await trophy.metrics.event("lessons", {
    user: {
      id: "user-123",
      "attributes": {
        "city": "London" // Optional, segment rankings by user attributes
      }
    },
    value: 1
  }
);

// This single event:
// - Records user activity
// - Computes leaderboard rankings
// - Returns new leaderboard rankings

GET/leaderboards/{key}View Docs

Get a specific leaderboard and rankings. Supports pagination and filtering.

Path Parameters

keystringrequired

Unique key of the leaderboard as set when created.

Query Parameters

limitinteger

Maximum number of rankings to return (default: 10).

offsetinteger

Number of rankings to skip for pagination.

userIdstring

The ID of the user to center the rankings around.

rundate

Specific run date (YYYY-MM-DD) to fetch rankings for.

Response

rankingsRanking[]

Ranked list of users with scores.

runUnitstring

Time unit for recurring leaderboards (e.g., "day").

runIntervalnumber

Number of runUnits per leaderboard period.

Example

import { TrophyApiClient } from '@trophyso/node';

const trophy = new TrophyApiClient({
  apiKey: 'YOUR_API_KEY'
});

// Fetch leaderboard rankings
const board = await trophy.leaderboards.get("weekly-words");

// Response:
// {
//   rankings: [
//     { rank: 1, userId: "...", value: 5000, userName: "Sarah" },
//     { rank: 2, userId: "...", value: 4500, userName: "Alex" },
//     ...
//   ],
//   runUnit: "day",
//   runInterval: 7
// }

GET/users/{id}/leaderboards/{key}View Docs

Get a user's rank, value, and history for a specific leaderboard.

Path Parameters

idstringrequired

The user's ID in your database.

keystringrequired

Unique key of the leaderboard as set when created.

Query Parameters

rundate

Specific run date (YYYY-MM-DD) to fetch rankings for.

Response

ranknumber

User's current position on the leaderboard.

valuenumber

User's current score/value.

historyHistoryEntry[]

Rank and value changes over time.

Example

import { TrophyApiClient } from '@trophyso/node';

const trophy = new TrophyApiClient({
  apiKey: 'YOUR_API_KEY'
});

// Get a user's leaderboard data
const ranking = await trophy.users.leaderboards(
  "user-123", "weekly-words"
);

// Response:
// { rank: 2, value: 4500, history: [...] }

Lightning-Fast Integration

Simple APIs you'll Love

Use our pre-built gamification API to effortlessly build engaging user experiences. Get a team that's 100% focused on engagement.

Get Started API Reference

Type-safe SDKs.: We spend time worrying about abstractions and let you focus on what matters: building a great experience for your users.
Intuitive documentation.: Documentation built by developers for developers. Get started in minutes, not hours.
Effortless debugging.: Get to the root of the issue fast with detailed event logs and error messages.

// Fetch and render leaderboard

const board = await trophy.leaderboards
  .get("weekly-words");

// Render leaderboard rows
return board.rankings.map(entry => (
  <LeaderboardRow
    rank={entry.rank}
    name={entry.userName}
    score={entry.value}
  />
));

Gamification UI Library

Pixel-perfect leaderboards UI components

Use our open-source gamification UI components as the foundation for your design system. Customize as you see fit. Designed to work perfectly with the Trophy API.

Get Started UI Library

One-command install: Add any component to your project with a single CLI command. No extra dependencies to manage.
Fully customizable: Every component lives in your codebase. Tweak styles, layout, and behavior to match your brand.
Open-source.: MIT licensed and community-driven. Use in personal projects or production apps without restrictions.

Built for production workloads

Reliable infrastructure designed for performance at scale.

Historical Uptime: 99.99%
Avg Response Time: <50ms
Integration Time: < 1 hour
Users Tracked: 1M+

Buy vs. Build

Why use Trophy's leaderboard API?

Building a real-time leaderboard API from scratch is a classic distributed systems challenge. Ranking at scale requires more than a sorted query. Trophy's API handles the infrastructure so you can keep focused on the user experience.

Key Considerations		Build	Why does it matter?
Integration Time	Leaderboards populate automatically from user activity events. Fetch ranked results with one API call.	Build ranking engine, score aggregation, pagination, time-windowed boards, and tie-breaking logic. Expect 4-8 weeks.	Leaderboards are more than a sorted list. Time-windowed boards, pagination, tie-breaking, and real-time position updates require careful design.
Reliability	Consistent rankings with atomic score updates and real-time position accuracy.	Concurrent score updates can cause ranking inconsistencies. Ensuring globally consistent ordering under write contention requires distributed locking or conflict resolution.	Users notice immediately if their leaderboard position is wrong. Ranking bugs erode trust and undermine the competitive motivation leaderboards are meant to create.
Scalability	Trophy's Redis-based infrastructure processes millions of synchronous leaderboard updates every day, handling edge cases like tie-breaks, concurrent updates, automated reset mechanics and more.	Real-time leaderboards are a classic hot-key scaling problem. Every score update triggers a re-rank, and naive implementations hit database contention walls even at modest scale.	Sorted set operations that work at 1K users break at 100K. Sharding leaderboards without sacrificing global consistency is one of the harder distributed systems problems.
Ongoing Maintenance	Use the Trophy dashboard to configure ranking logic, repetition and segmentation settings in minutes.	Adding recurring leaderboards (weekly, monthly), archiving historical results, and managing time-window transitions requires ongoing engineering.	Product teams will want to experiment with different leaderboard formats — weekly sprints, seasonal competitions, team boards. Each should be a config change, not a backlog item.
Feature Development	Recurring boards, user position lookups, surrounding-user context, and historical archives ship regularly.	Each new feature — relative positioning, group boards, recurring resets — adds complexity to your ranking and aggregation infrastructure.	Leaderboards evolve from simple all-time lists to recurring competitions with surrounding-user context. Building each iteration in-house adds up quickly.

Integration Time

Leaderboards populate automatically from user activity events. Fetch ranked results with one API call.

Build

Build ranking engine, score aggregation, pagination, time-windowed boards, and tie-breaking logic. Expect 4-8 weeks.

Why does it matter?

Leaderboards are more than a sorted list. Time-windowed boards, pagination, tie-breaking, and real-time position updates require careful design.

Reliability

Consistent rankings with atomic score updates and real-time position accuracy.

Build

Concurrent score updates can cause ranking inconsistencies. Ensuring globally consistent ordering under write contention requires distributed locking or conflict resolution.

Why does it matter?

Users notice immediately if their leaderboard position is wrong. Ranking bugs erode trust and undermine the competitive motivation leaderboards are meant to create.

Scalability

Trophy's Redis-based infrastructure processes millions of synchronous leaderboard updates every day, handling edge cases like tie-breaks, concurrent updates, automated reset mechanics and more.

Build

Real-time leaderboards are a classic hot-key scaling problem. Every score update triggers a re-rank, and naive implementations hit database contention walls even at modest scale.

Why does it matter?

Sorted set operations that work at 1K users break at 100K. Sharding leaderboards without sacrificing global consistency is one of the harder distributed systems problems.

Ongoing Maintenance

Use the Trophy dashboard to configure ranking logic, repetition and segmentation settings in minutes.

Build

Adding recurring leaderboards (weekly, monthly), archiving historical results, and managing time-window transitions requires ongoing engineering.

Why does it matter?

Product teams will want to experiment with different leaderboard formats — weekly sprints, seasonal competitions, team boards. Each should be a config change, not a backlog item.

Feature Development

Recurring boards, user position lookups, surrounding-user context, and historical archives ship regularly.

Build

Each new feature — relative positioning, group boards, recurring resets — adds complexity to your ranking and aggregation infrastructure.

Why does it matter?

Leaderboards evolve from simple all-time lists to recurring competitions with surrounding-user context. Building each iteration in-house adds up quickly.

FAQ

Frequently asked questions

Have a different question and can’t find the answer you’re looking for?

What types of leaderboards and scoreboards can I create?: Trophy's leaderboard API supports perpetual (all-time) rankings and recurring leaderboards that reset on a schedule — daily, weekly, monthly, or any custom interval. You can run multiple leaderboards tracking different metrics simultaneously.
How are leaderboard rankings calculated?: Leaderboard rankings are automatically calculated from the metric events you send. When a user sends an event for a metric tied to a real-time leaderboard, their score updates and their rank recalculates immediately.
Can I build competitive features and competitions?: Yes. Trophy's recurring leaderboard API lets you run time-bounded competitions — weekly writing challenges, monthly contests, or custom periods. The API returns rankings with user scores, making it easy to display standings, announce winners, and drive re-engagement. Across Trophy's platform, apps using social leaderboard features average 34% longer user streaks (5.69 days versus 4.25 without).
How do I get a specific user's rank and position?: Use the get user leaderboard endpoint to fetch a user's rank, score, and rank history for any leaderboard. This is useful for showing users their personal standing and progress over time.
Does the leaderboard API support pagination?: Yes. The get leaderboard endpoint supports limit and offset parameters for paginating through rankings. This lets you load leaderboards incrementally and build infinite-scroll or paginated UIs.
Can I show leaderboards in React, React Native, or mobile apps?: Yes. Adding a mobile app leaderboard with Trophy uses server-side SDKs (Node.js, Python, Go, Java, PHP, Ruby, and .NET) to handle ranking logic on your backend. The API returns ranked entries with scores and user data that you can render in any frontend — React, React Native, Next.js, Swift, Kotlin, Flutter, or any other framework.

Gamification infrastructure that retains users

Boost retention and customer lifetime value. Try for free up to 100 MAUs.

Get Started Read Docs