Get a single leaderboard by ID

Reads one leaderboard for the API-key's community by leaderboard ID and returns the leaderboard document.

Use this to load a leaderboard configuration before editing it, validating UI access, or checking stored duration and permission allow-lists.

Authentication:

Bearer API key in Authorization header

Required permission: leaderboard

Community is resolved from the API key token; do not pass communityID

Returns 401 if missing, invalid, or insufficient

Rate limits:

Standard API rate limits apply

Constraints:

leaderboardID must identify a leaderboard in the API-key's community

fields is a projection; leaderboard item properties are optional in the response schema because omitted fields are valid

duration is optional on response rows because pre-duration legacy rows may omit it until repaired through the update API

Returns 404 when the leaderboard does not exist or is not in the resolved community

Example — read:

GET /leaderboards/507f1f77bcf86cd799439012?fields=name,slug,duration,rankedUserRoles,viewPermissionUserRoles

Related endpoints:

GET /leaderboards — list leaderboards

POST /leaderboards — create a leaderboard

PATCH /leaderboards/{leaderboardID} — update a leaderboard

DELETE /leaderboards/{leaderboardID} — delete a leaderboard

Responses

🟢200OK

application/json

Leaderboard document. The envelope is required; the leaderboard data object is projection-aware, so individual fields are optional when fields is used.

Bodyapplication/json

🟠400Bad Request

🟠401Unauthorized

🟠404Record Not Found

🔴500Server Error

🔴502Bad Gateway

{ "meta": { "status": "success", "statusCode": 200 }, "message": "Read leaderboard success.", "data": { "_id": "507f1f77bcf86cd799439012", "communityID": "507f1f77bcf86cd799439013", "name": "April Last Leaderboard", "slug": "april-last-leaderboard", "description": "Monthly leaderboard created through the partner API.", "image": "https://cdn.example.com/leaderboards/april.png", "rankBy": "currencies", "displayedFields": [ "user", "currencies" ], "displayFieldsOrder": [ "user", "currencies" ], "timeFilters": [ "all-time", "monthly", "weekly" ], "performanceDisplay": { "showTop": { "enabled": false, "value": 10 }, "showPositive": { "enabled": false }, "showDummy": { "enabled": false } }, "duration": { "start": "2026-01-30T19:30:00.000Z", "end": "2026-12-31T23:59:59.999Z", "noEndDate": true, "timeZone": 5.3, "startTime": { "hours": 5, "minutes": 0, "ampm": "AM" }, "endTime": { "hours": 11, "minutes": 59, "ampm": "PM" } }, "rankedUserRoles": { "users": [], "roles": [ "507f1f77bcf86cd799439014" ], "tags": [] }, "viewPermissionUserRoles": { "users": [], "roles": [ "507f1f77bcf86cd799439014" ], "tags": [] }, "widget": { "enabled": false, "whitelistedDomains": [ "example.com" ], "size": { "type": "custom", "value": { "width": 420, "height": 640 } }, "button": { "enabled": true, "text": "View leaderboard", "link": "https://example.com/leaderboard" } }, "translations": { "name": [ { "languageCode": "en", "translation": "April Last Leaderboard" } ], "description": [ { "languageCode": "en", "translation": "Monthly leaderboard created through the partner API." } ] }, "enabled": true, "previewEnabled": false, "displayOrder": 3, "selected": false, "updatedAt": "2026-04-13T12:00:00.000Z", "createdAt": "2026-04-01T00:00:00.000Z" } }