Overview
Build leaderboard systems that drive engagement through:- Real-time user rankings via loyalty points
- Paginated leaderboard data with cursor-based pagination
- Sprint-specific leaderboards for competitions
- Space-level ranking analytics
Basic Leaderboard Query
Get Leaderboard Rankings
Sprint-Specific Leaderboards
Get Sprint Rankings
When you have a sprint ID, get sprint-specific rankings:Sprint Management: Sprint information must come from external sources as sprint management is not available through this API.
Pagination Patterns
Cursor-Based Navigation
Loading Next Page
- Use
pageInfo.endCursorfrom previous response - Set as
cursorAfterparameter for next request - Continue until
pageInfo.hasNextPageisfalse
User Position Lookup
Search Strategy
Since there’s no direct user lookup, implement efficient search:- Limited Search: Search first 10-20 pages for UI responsiveness
- Background Search: Comprehensive search for analytics
- Caching: Store user positions to reduce future searches
Basic Implementation
Common Integration Patterns
Top N Rankings
Sprint vs Overall Comparison
Best Practices
- Pagination: Use cursor-based pagination (
cursorAfter/cursorBefore) - Rate Limiting: Add 200-500ms delays between pagination requests
- Caching: Cache leaderboard data for 30-60 seconds
- Search Limits: Limit user searches to reasonable page counts (20-50 pages)
- Error Handling: Handle cases where users are not found in rankings
- Sprint Context: Use
sprintIdfor time-limited competitions
Pagination Parameters
Current (Recommended)
cursorAfter: Get items after this cursorcursorBefore: Get items before this cursorsprintId: Optional sprint ID for sprint-specific rankings
Deprecated (Avoid)
first: Use cursor-based pagination insteadafter: Use cursor-based pagination instead
Limitations & Workarounds
Current Limitations
- No Direct User Lookup: Must search through pages
- No Sprint Management: Sprint IDs from external sources
- Search Performance: Finding users requires multiple API calls
Recommended Workarounds
- Efficient Search: Limit search scope for UI responsiveness
- Caching Strategy: Cache user positions for short periods
- User Communication: Set expectations about search time
- Fallback UI: Show leaderboard context even when user isn’t found
Usage Examples
Basic Leaderboard Display
User Position Check
Next Steps
- Space API Reference - Complete API documentation
- Loyalty Program Guide - Points and rewards system
- Authentication - Access token setup