Get a single leaderboard by ID

GET

/leaderboards/{leaderboardID}

Returns a single leaderboard by ID within the API-key's community.

Use this to fetch a specific leaderboard's full configuration (rank rules, display fields, duration, widget config) for rendering or editing.

Authentication:

Bearer API key in Authorization header

API key must have the leaderboard permission

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

Returns 401 if the key is missing, invalid, or lacks the required permission

Rate limits:

Standard API rate limits apply

Constraints:

leaderboardID must be a valid Mongo ObjectId or string ID

fields projection only accepts whitelisted selectable fields — invalid fields return 400

Returns 404 if the leaderboard does not exist in this community

Related endpoints:

GET /leaderboards — list leaderboards

PATCH /leaderboards/{leaderboardID} — update this leaderboard

DELETE /leaderboards/{leaderboardID} — delete this leaderboard

Request

Path Params

Query Params

Header Params

Responses

🟢200OK

application/json

Single leaderboard

Body

🟠401Unauthorized

🟠404Record Not Found

🔴500Server Error

Request Example

Shell

JavaScript

Java

Swift

curl --location --request GET 'https://api.returning.ai/v1/leaderboards/507f1f77bcf86cd799439012?fields=name,slug,enabled' \
--header 'Authorization: Bearer XXXXXX'

Response Example

200 - Success Example

{
    "meta": {
        "status": "success",
        "statusCode": 200
    },
    "message": "Read leaderboard success.",
    "data": {
        "_id": "507f1f77bcf86cd799439012",
        "communityID": "507f1f77bcf86cd799439013",
        "name": "Top Traders",
        "slug": "top-traders",
        "description": "Monthly trading leaderboard",
        "rankBy": "currencies",
        "displayedFields": [
            "name",
            "score"
        ],
        "displayFieldsOrder": [
            "name",
            "score"
        ],
        "timeFilters": [
            "all-time",
            "monthly"
        ],
        "duration": {
            "start": "2026-01-01T00:00:00.000Z",
            "end": "2026-12-31T23:59:59.999Z",
            "noEndDate": false,
            "timeZone": 7
        },
        "enabled": true,
        "previewEnabled": false,
        "selected": false,
        "createdAt": "2026-04-01T00:00:00.000Z",
        "updatedAt": "2026-04-13T12:00:00.000Z"
    }
}

Modified at 2026-04-20 06:48:15

Create a new leaderboard

Update an existing leaderboard