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.
Quickstart
Quickstart: rank users from metric events
Send metric events to update rankings automatically, then fetch the board or a user’s position. Segment rankings with user attributes when you need cohorts.
import { TrophyApiClient } from "@trophyso/node";
const trophy = new TrophyApiClient({ apiKey: process.env.TROPHY_API_KEY });
// 1. Track activity that powers the leaderboard
const eventResponse = await trophy.metrics.event("lessons", {
user: {
id: "user-123",
attributes: { city: "London" },
},
value: 1,
});
console.log("Leaderboard updates:", eventResponse.leaderboards);
// 2. Fetch the full board rankings
const board = await trophy.leaderboards.get("weekly-words");
for (const entry of board.rankings) {
console.log(entry.rank, entry.userName, entry.value);
}
// 3. Fetch one user's rank and history
const ranking = await trophy.users.leaderboards("user-123", "weekly-words");
console.log("Rank:", ranking.rank, "Value:", ranking.value);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.
Integration Time
Reliability
Scalability
Ongoing Maintenance
Feature Development
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.
Send a metric event to track user activity and power leaderboards.
Path Parameters
keystringrequiredUnique reference of the metric as set when created.
Request Body
userUserrequiredThe user that triggered the event (must include id).
valuenumberrequiredThe value to add to the user's current total for the given metric.
Response
eventIdstringUnique identifier for the created event.
totalnumberThe user's new total for this metric.
leaderboardsLeaderboard[]Changes to leaderboard rankings.
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 a specific leaderboard and rankings. 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.
userIdstringThe ID of the user to center the rankings around.
rundateSpecific run date (YYYY-MM-DD) to fetch rankings for.
Response
rankingsRanking[]Ranked list of users with scores.
runUnitstringTime unit for recurring leaderboards (e.g., "day").
runIntervalnumberNumber of runUnits per leaderboard period.
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) to fetch rankings for.
Response
ranknumberUser's current position on the leaderboard.
valuenumberUser's current score/value.
historyHistoryEntry[]Rank and value changes over time.
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 platform 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}
/>
));
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.
- 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.
- Uptime SLA
- 99.99%
- p95 API Latency
- 200ms
- Monthly API Requests
- 150M
- Users Tracked
- 1M+
FAQ
Frequently asked questions
Have a different question and can’t find the answer you’re looking for? Send us an email.
Get started