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

What it is for: Get a single leaderboard by ID. Use this to manage custom leaderboards that rank users by configured fields, points, or broker-defined metrics.
How to use it: Send a GET request to /leaderboards/{leaderboardID} with the request body, query parameters, or multipart fields shown below. Partner API key required when this surface is enabled for the community. Confirm gateway access before using in production.
Availability note: this route is legacy or partner-service-backed. During a 2026-05-18 smoke test, the equivalent root path returned 404 on https://api.returning.ai; keep it marked non-primary until the gateway alias is confirmed.
Successful response: HTTP 200. The body follows the endpoint schema; many integration endpoints wrap the useful payload under data with status and message.
Common error states:

400 invalid request body, query, ObjectId, pagination, file format, or missing required field.

401 missing, invalid, expired, or insufficient API key/token.

403 key is valid but cannot access this community/channel/user/resource, where supported by the service.

404 target resource, route, or community-scoped record was not found.

409 duplicate or conflicting state for create/update operations, where applicable.

500 unexpected Returning.AI service error.

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

🟠403Forbidden

🟠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" } }