List leaderboards with pagination

Lists leaderboards for the API-key's community and returns paginated leaderboard documents.

Use this to browse leaderboard configurations, verify permission allow-lists, or sync leaderboard metadata into a partner system.

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:

page starts at 1 and defaults to 1

limit defaults to 20 and has a max of 100

total is the number of records after the community and search filters are applied

Omit search to count/list all leaderboards for the API-key community

search=keyword:<value> filters by leaderboard name or slug

fields is a projection; omit it to return the default full document shape

Leaderboard item properties are optional in the response schema because projected responses may omit them

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

Example — list all:

GET /leaderboards?page=1&limit=20&sort=createdAt:desc

Example — filtered search:

GET /leaderboards?page=1&limit=20&sort=createdAt:desc&search=keyword:top

Related endpoints:

POST /leaderboards — create a leaderboard

GET /leaderboards/{leaderboardID} — read a single leaderboard

PATCH /leaderboards/{leaderboardID} — update a leaderboard

DELETE /leaderboards/{leaderboardID} — delete a leaderboard

Responses

🟢200OK

application/json

Paginated list of leaderboards. The envelope is required; each leaderboard item uses the full leaderboard schema, but individual item properties are optional because fields projection or legacy rows may omit them.

Bodyapplication/json

🟠401Unauthorized

🔴500Server Error

{ "meta": { "status": "success", "statusCode": 200, "page": 1, "limit": 20, "total": 11 }, "message": "Read leaderboards success.", "data": [ { "_id": "69ea45dcecb17b3d0cb8824c", "communityID": "6502c97314a3e564c5bbfa84", "name": "Top Traders 2", "slug": "top-traders-2", "description": "Monthly trading leaderboard", "rankBy": "currencies", "displayedFields": [ "name", "score" ], "displayFieldsOrder": [ "name", "score" ], "timeFilters": [ "all-time", "monthly" ], "performanceDisplay": { "showTop": { "enabled": true, "value": 10 }, "showPositive": { "enabled": true }, "showDummy": { "enabled": false } }, "rankedUserRoles": { "users": [], "roles": [], "tags": [] }, "viewPermissionUserRoles": { "users": [], "roles": [], "tags": [] }, "enabled": true, "previewEnabled": false, "selected": false, "updatedAt": "2026-04-23T16:16:28.537Z", "createdAt": "2026-04-23T16:16:28.537Z" } ] }

List leaderboards with pagination

Request

Responses