Get Complete Leaderboard - Full Rankings API Endpoint

Retrieve complete user rankings and leaderboard data via our REST API. This leaderboard endpoint returns all participants ranked by points, perfect for displaying full leaderboard tables, competition standings, and user rankings in your application.

Supports both monthly leaderboards (reset-based competitions) and floating leaderboards (rolling time windows: 7d, 30d, 365d). Ideal for loyalty programs, gaming applications, fitness apps, and any platform requiring user ranking systems.

This endpoint supports both monthly (resets each month) and floating (7d, 30d, 365d rolling windows) leaderboard types.

Use Cases

Display full leaderboard tables in your application
Show all participants in a monthly competition
Export complete ranking data for analysis
Power leaderboard screens with pagination

Endpoint

GET /project/{projectId}/leaderboard

Path Parameters

Parameter	Type	Required	Description
`projectId`	string	Yes	The unique identifier of the project

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 an array of users ranked by their points for the specified timeframe (monthly or floating).

Response Schema

{
  "users": [
    {
      "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
    },
    {
      "userId": "tuv890wxy123zab456cde789fgh012",
      "username": "username_tuv012",
      "points": 167,
      "rank": 4
    },
    {
      "userId": "ijk345lmn678opq901rst234uvw567",
      "username": "username_ijk567",
      "points": 164,
      "rank": 5
    },
    {
      "userId": "xyz890abc123def456ghi789jkl012",
      "username": "username_xyz012",
      "points": 160,
      "rank": 6
    },
    {
      "userId": "mno345pqr678stu901vwx234yza567",
      "username": "username_mno567",
      "points": 157,
      "rank": 7
    },
    {
      "userId": "bcd890efg123hij456klm789nop012",
      "username": "username_bcd012",
      "points": 149,
      "rank": 8
    },
    {
      "userId": "qrs345tuv678wxy901zab234cde567",
      "username": "username_qrs567",
      "points": 130,
      "rank": 9
    },
    {
      "userId": "fgh890ijk123lmn456opq789rst012",
      "username": "username_fgh012",
      "points": 120,
      "rank": 10
    },
    {
      "userId": "uvw345xyz678abc901def234ghi567",
      "username": "username_uvw567",
      "points": 116,
      "rank": 11
    },
    {
      "userId": "jkl890mno123pqr456stu789vwx012",
      "username": "username_jkl012",
      "points": 108,
      "rank": 12
    }
  ]
}

Field Descriptions

User Object

Field	Type	Description
`userId`	string	Unique identifier of the user
`username`	string	Display name of the user
`points`	number	Total points accumulated by the user within the specified timeframe (month or floating period)
`rank`	number	User's position in the leaderboard (1 = first place)

Example Request

Get monthly leaderboard for November 2025

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

Get 7-day floating leaderboard

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

Get 30-day floating leaderboard

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

Get 365-day floating leaderboard

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

Status Codes

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

🏆 Leaderboards Get User Rank