Leaderboard API - Real-Time User Rankings & Competition
Build engaging competition features with our comprehensive Leaderboard API. Track user rankings, display top performers, and create competitive experiences that drive engagement. Our gamification leaderboard API supports both monthly resets and rolling time windows (7d, 30d, 365d) for flexible competition structures.
Whether you're building a loyalty program leaderboard, gaming leaderboard system, or employee engagement platform, our REST API provides real-time rankings, personalized views, and scalable performance.
The leaderboard system allows you to track and display user rankings based on their accumulated points. There are two types of leaderboards available:
Leaderboard Types
1. Monthly Leaderboards
Monthly leaderboards reset at the beginning of each month (1st day, 00:00 UTC). These are ideal for:
- Monthly competitions and challenges
- Time-bound campaigns
- Seasonal events
- Creating fresh competition cycles
Example: Users compete for the highest points in November 2025. On December 1st, all points reset to 0.
2. Floating Leaderboards
Floating leaderboards use rolling time windows and never reset. They continuously track points within specific timeframes:
- 7 days (7d): Last 7 days of activity
- 30 days (30d): Last 30 days of activity
- 365 days (365d): Last 365 days of activity
These are ideal for:
- Ongoing engagement tracking
- Long-term user activity monitoring
- Identifying consistently active users
Example: On November 6th, the 7d leaderboard shows points from October 30 to November 6. On November 7th, it shows October 31 to November 7.
Available Endpoints
1. Get Complete Leaderboard
GET /project/{projectId}/leaderboard
Retrieves the entire leaderboard for a user group. Use this when you need to display:
- Full rankings for a project
- Complete user standings
- Leaderboard tables with all participants
Supports: Both monthly and floating leaderboards
2. Get User Rank
GET /user/{userId}/rank
Retrieves a specific user's rank and points across all three floating timeframes simultaneously. Use this when you need to:
- Show a user's current standings
- Display rank badges or indicators
- Track user performance over different time periods
Supports: Floating leaderboards only (7d, 30d, 365d)
3. Get User Leaderboard View
GET /user/{userId}/leaderboard
Retrieves a personalized leaderboard view with the top 3 users and rankings around the specified user. Use this when you need to:
- Show personalized leaderboard screens
- Display "You are here" type views
- Provide context about nearby competitors
- Show both top performers and local competition
Supports: Both monthly and floating leaderboards
Quick Comparison
| Feature | Complete Leaderboard | User Rank | User Leaderboard View |
|---|---|---|---|
| Returns full rankings | ✅ Yes | ❌ No | ❌ No (Top 3 + surrounding) |
| User-specific data | ❌ No | ✅ Yes | ✅ Yes |
| Shows top performers | ✅ Yes | ❌ No | ✅ Yes (Top 3) |
| Monthly support | ✅ Yes | ❌ No | ✅ Yes |
| Floating support | ✅ Yes | ✅ Yes (all timeframes) | ✅ Yes |
| Best for | Full leaderboard UI | Profile/dashboard stats | Personalized ranking view |
Common Use Cases
Displaying a Leaderboard Screen
Use Get Complete Leaderboard for the full list or Get User Leaderboard View for a personalized view with the user's position highlighted.
User Profile Statistics
Use Get User Rank to show the user's performance across different timeframes (7d, 30d, 365d).
Competition Dashboard
Combine Get User Leaderboard View (for personalized context) with Get Complete Leaderboard (for full standings).
Monthly Events
Use the month parameter with Get Complete Leaderboard or Get User Leaderboard View to track monthly competitions.