Leaderboards API
Add leaderboards to your app in minutes
Create competitive experiences with flexible leaderboards. Build perpetual all-time boards, weekly competitions, or custom time periods that drive engagement.
SDKs for
Endpoints
Leaderboard endpoints
Fetch rankings and user positions. Leaderboards are automatically populated based on metrics you track.
Get a specific leaderboard by its key. Supports pagination and filtering.
Path Parameters
keystringrequiredUnique key of the leaderboard as set when created.
Query Parameters
limitintegerMaximum number of rankings to return (default: 10).
offsetintegerNumber of rankings to skip for pagination.
rundateSpecific run date (YYYY-MM-DD). Defaults to current run.
Response
rankingsRanking[]Ranked list of users with scores.
runUnitstringTime unit for recurring leaderboards (e.g., "day").
runIntervalnumberNumber 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 a user's rank, value, and history for a specific leaderboard.
Path Parameters
idstringrequiredThe user's ID in your database.
keystringrequiredUnique key of the leaderboard as set when created.
Query Parameters
rundateSpecific run date (YYYY-MM-DD). Defaults to current run.
Response
ranknumberUser's current position on the leaderboard.
valuenumberUser'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.
- 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}
/>
));Built for production workloads
Reliable infrastructure designed for performance at scale.
- API Uptime
- 99.99%
- Avg Response Time
- <50ms
- Integration Time
- < 1 hour
- API Calls / Month
- 10M+
Buy vs. Build
Why use Trophy for leaderboards?
Real-time leaderboards are a classic distributed systems challenge. Ranking at scale requires more than a sorted query.
| Key Considerations | Build | Why does it matter? | |
|---|---|---|---|
| Integration Time | Leaderboards populate automatically from metrics. 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 handles real-time ranking across millions of users with sub-100ms response times. | Real-time leaderboards are a classic hot-key scaling problem. Every score update triggers a re-rank, and naive implementations hit database contention walls at scale. | Sorted set operations that work at 1K users break at 1M. Sharding leaderboards without sacrificing global consistency is one of the harder distributed systems problems. |
| Ongoing Maintenance | Create new leaderboards and time periods from the dashboard. No code changes needed. | 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 project. |
| 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 metrics. 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 handles real-time ranking across millions of users with sub-100ms response times.
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 at scale.
Why does it matter?
Sorted set operations that work at 1K users break at 1M. Sharding leaderboards without sacrificing global consistency is one of the harder distributed systems problems.
Ongoing Maintenance
Create new leaderboards and time periods from the dashboard. No code changes needed.
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 project.
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
Leaderboards & Rankings FAQ
Have a different question and can’t find the answer you’re looking for? Send us an email.
- What types of leaderboards and scoreboards can I create?
- Trophy supports perpetual (all-time) leaderboards and recurring leaderboards that reset on a schedule — daily, weekly, monthly, or any custom interval. You can create multiple leaderboards tracking different metrics.
- How are leaderboard rankings calculated?
- Rankings are automatically calculated from the metric events you send. When a user sends an event for a metric tied to a leaderboard, their score updates and their rank recalculates in real time.
- Can I build competitive features and competitions?
- Yes. Use recurring leaderboards to run time-bounded competitions (e.g., weekly writing challenges). The API returns rankings with user scores, making it easy to display standings, announce winners, and drive engagement.
- 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. Trophy's server-side SDKs (Node.js, Python, Go, Java, PHP, Ruby, .NET) 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.
