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

What it is for: List leaderboards with pagination. 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 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

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

🟠400Bad Request

🟠401Unauthorized

🟠403Forbidden

🟠404Record Not Found

🔴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" } ] }