Get User Leaderboard View - Personalized Rankings API

Build engaging "Your Ranking" screens with our personalized leaderboard API. This endpoint returns top performers plus users ranked around a specific player, creating competitive context without loading entire leaderboards.

Optimized for mobile apps, gaming interfaces, and user engagement features. Shows the top 3 competitors plus nearby rivals, perfect for gamification, fitness leaderboards, sales competitions, and loyalty program rankings.

Retrieve a personalized leaderboard view for a specific user, including the top 3 players and users ranked around the current user.

Use Cases

Show personalized "Your Ranking" screens
Display top performers alongside the user's position
Create competitive UI elements showing nearby rivals
Mobile apps with limited screen space (shows relevant subset)

Endpoint

GET /user/{userId}/leaderboard

Path Parameters

Parameter	Type	Required	Description
`userId`	string	Yes	The unique identifier of the user

Query Parameters

Parameter	Type	Required	Description
`month`	string	No*	The month in YYYY-MM format (e.g., `2025-11`). Required for monthly leaderboards
`groupId`	string	Yes	The user group identifier (e.g., `default` for the default group)
`timeframe`	string	No*	Time window for floating leaderboards: `7d`, `30d`, or `365d`. Required for floating leaderboards

Note: Use either month (for monthly leaderboards) OR timeframe (for floating leaderboards), not both.

Response

Returns an object containing the top 3 users and users ranked around the current user.

Response Schema

{
  "topUsers": [
    {
      "userId": "abc123def456ghi789jkl012mno345",
      "username": "username_abc345",
      "points": 244,
      "rank": 1
    },
    {
      "userId": "pqr678stu901vwx234yza567bcd890",
      "username": "username_pqr890",
      "points": 198,
      "rank": 2
    },
    {
      "userId": "efg345hij678klm901nop234qrs567",
      "username": "username_efg567",
      "points": 168,
      "rank": 3
    }
  ],
  "usersBefore": [
    {
      "userId": "tuv890wxy123zab456cde789fgh012",
      "username": "username_tuv012",
      "points": 95,
      "rank": 8
    },
    {
      "userId": "ijk345lmn678opq901rst234uvw567",
      "username": "username_ijk567",
      "points": 92,
      "rank": 9
    }
  ],
  "currentUser": {
    "userId": "xyz890abc123def456ghi789jkl012",
    "username": "username_xyz012",
    "points": 88,
    "rank": 10
  },
  "usersAfter": [
    {
      "userId": "mno345pqr678stu901vwx234yza567",
      "username": "username_mno567",
      "points": 85,
      "rank": 11
    },
    {
      "userId": "bcd890efg123hij456klm789nop012",
      "username": "username_bcd012",
      "points": 82,
      "rank": 12
    }
  ]
}

Field Descriptions

Leaderboard Entry Object

Field	Type	Description
`userId`	string \| null	Unique identifier of the user (can be null for anonymized users)
`username`	string	Display name of the user
`points`	number	Total points accumulated by the user
`rank`	number	User's position in the leaderboard (1 = first place)

Response Structure

Field	Type	Description
`topUsers`	array	Array of the top 3 users on the leaderboard
`usersBefore`	array	Users ranked immediately before the current user
`currentUser`	object	The current user's leaderboard entry
`usersAfter`	array	Users ranked immediately after the current user

Example Request

Get monthly leaderboard view for November 2025

curl -X GET "https://api.lynesapp.de/user/xyz890abc123def456ghi789jkl012/leaderboard?month=2025-11&groupId=default" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Get 7-day floating leaderboard view

curl -X GET "https://api.lynesapp.de/user/xyz890abc123def456ghi789jkl012/leaderboard?timeframe=7d&groupId=default" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Get 30-day floating leaderboard view

curl -X GET "https://api.lynesapp.de/user/xyz890abc123def456ghi789jkl012/leaderboard?timeframe=30d&groupId=default" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Get 365-day floating leaderboard view

curl -X GET "https://api.lynesapp.de/user/xyz890abc123def456ghi789jkl012/leaderboard?timeframe=365d&groupId=default" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Status Codes

Status Code	Description
`200`	Successfully retrieved leaderboard view
`400`	Bad request - Invalid month/timeframe or missing parameters
`401`	Unauthorized - Invalid or missing authentication token
`404`	User or group not found
`500`	Internal server error

Notes

The usersBefore and usersAfter arrays typically contain 2-3 users each, providing context around the current user's position
If the current user is in the top 3, they will appear in both topUsers and currentUser
userId can be null in the response for anonymized or privacy-protected users

Get User Rank 🔥 Streaks