Skip to main content

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

Variables:
Response:

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

  1. Use pageInfo.endCursor from previous response
  2. Set as cursorAfter parameter for next request
  3. Continue until pageInfo.hasNextPage is false

User Position Lookup

No Direct User Lookup: To find a specific user’s rank, you must paginate through the leaderboard.

Search Strategy

Since there’s no direct user lookup, implement efficient search:
  1. Limited Search: Search first 10-20 pages for UI responsiveness
  2. Background Search: Comprehensive search for analytics
  3. Caching: Store user positions to reduce future searches

Basic Implementation

Common Integration Patterns

Top N Rankings

Sprint vs Overall Comparison

Best Practices

  1. Pagination: Use cursor-based pagination (cursorAfter/cursorBefore)
  2. Rate Limiting: Add 200-500ms delays between pagination requests
  3. Caching: Cache leaderboard data for 30-60 seconds
  4. Search Limits: Limit user searches to reasonable page counts (20-50 pages)
  5. Error Handling: Handle cases where users are not found in rankings
  6. Sprint Context: Use sprintId for time-limited competitions

Pagination Parameters

  • cursorAfter: Get items after this cursor
  • cursorBefore: Get items before this cursor
  • sprintId: Optional sprint ID for sprint-specific rankings

Deprecated (Avoid)

  • first: Use cursor-based pagination instead
  • after: Use cursor-based pagination instead

Limitations & Workarounds

Current Limitations

  1. No Direct User Lookup: Must search through pages
  2. No Sprint Management: Sprint IDs from external sources
  3. Search Performance: Finding users requires multiple API calls
  1. Efficient Search: Limit search scope for UI responsiveness
  2. Caching Strategy: Cache user positions for short periods
  3. User Communication: Set expectations about search time
  4. Fallback UI: Show leaderboard context even when user isn’t found

Usage Examples

Basic Leaderboard Display

User Position Check

Next Steps