List leaderboards with pagination

What this endpoint does

Lists leaderboards for the community resolved from the Bearer API key.

A key missing permission leaderboard receives 403, not a catalog.

INFO

Workflow

Use a community API key that includes leaderboard → GET https://api.returning.ai/v1/leaderboards → if 403 AUTH_PERMISSION_REQUIRED, add the permission or switch keys → do not call GET /leaderboards without /v1.

Quick start

On https://api.returning.ai:

GET /v1/leaderboards — mounted. 403 when leaderboard is missing.

GET /leaderboards — not mounted (404).

Authentication and permission

Send Authorization: Bearer <COMMUNITY_API_KEY>. Required permission: leaderboard. Community is resolved from the key; do not send communityID in the path.

Failure	Result	Recovery
Valid key, missing `leaderboard`	`403` `AUTH_PERMISSION_REQUIRED` `Insufficient API key permissions` `detail: API key is missing required permissions: leaderboard`	Update the key permissions or use a key that includes `leaderboard`.
Missing or invalid token	`401`	Add a valid community key.

Complete examples

Missing permission (403).

{
  "meta": {
    "status": "error",
    "statusCode": 403,
    "code": "AUTH_PERMISSION_REQUIRED"
  },
  "message": "Insufficient API key permissions",
  "detail": "API key is missing required permissions: leaderboard",
  "solution": "Update the API key permissions or use a key with the required permissions"
}

Same body for ?page=1&limit=5.

List success (200). A key that includes leaderboard returns message Read leaderboards success. Pagination sits on meta (page, limit, total). data is an array of boards.

{
  "meta": {
    "status": "success",
    "statusCode": 200,
    "page": 1,
    "limit": 5,
    "total": 1
  },
  "message": "Read leaderboards success.",
  "data": [
    {
      "_id": "<leaderboardID>",
      "name": "Example board",
      "slug": "example-board",
      "rankBy": "Messages Sent",
      "enabled": true,
      "selected": true
    }
  ]
}

Board objects also include displayedFields, displayFieldsOrder, timeFilters, duration, widget, translations, and permission role lists. Treat those as community-specific. Pagination query: page (minimum 1) and limit (maximum 100).

Success and readback

HTTP 200 Read leaderboards success. is the list and the readback for create/update/delete. Use _id from data[] on get / patch / delete.

CHECK

403 means the route is mounted

Add the leaderboard permission and retry. GET /leaderboards without /v1 is a missing route.

Errors and recovery

Status	When	Recovery
`403` `AUTH_PERMISSION_REQUIRED` `leaderboard`	Key lacks the permission	Grant `leaderboard`.
`404`	Caller used `/leaderboards` without `/v1`	Call `/v1/leaderboards`.
`401`	Missing or invalid Bearer token	Add a valid community key.

Retry safety

TIP

Exact retry

This GET does not create leaderboards. Retry timeouts with bounded backoff. Do not retry 403 without changing the key.

Gotchas

Call /v1/leaderboards on this gateway.

A 403 is a missing permission, not a missing product.

Prize and reset fields can move rewards. Use a disposable board in tests.

Next steps

Create a new leaderboard

Requires leaderboard. Prove GET /v1/leaderboards first.

curl --location 'https://adss-production.returning.ai/apis/partner/leaderboards?page=1&limit=20&sort=displayOrder&fields=name%2Cslug%2CleaderImage%2Cwidget%2CenablePrizePool&search=spring' \ --header 'Authorization: Bearer XXXXXX'

{ "meta": { "status": "success", "statusCode": 200, "page": 1, "limit": 20, "total": 1 }, "message": "Read leaderboards success.", "data": [ { "_id": "507f1f77bcf86cd799439012", "communityID": "6502c97314a3e564c5bbfa84", "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", "xps", "level" ], "displayFieldsOrder": [ "user", "currencies", "xps", "level" ], "timeFilters": [ "all-time", "daily", "weekly", "monthly", "yearly" ], "performanceDisplay": { "showTop": { "enabled": true, "value": 10 }, "showPositive": { "enabled": true }, "showDummy": { "enabled": false } }, "duration": { "start": "2026-01-30T00:00:00.000Z", "end": null, "noEndDate": true, "timeZone": 7, "startTime": { "hours": 12, "minutes": 0, "ampm": "AM" }, "endTime": { "hours": 11, "minutes": 59, "ampm": "PM" } }, "rankedUserRoles": { "users": [], "roles": [ "6502c97314a3e564c5bbfa84" ], "tags": [] }, "viewPermissionUserRoles": { "users": [], "roles": [ "6502c97314a3e564c5bbfa84" ], "tags": [] }, "widget": { "enabled": true, "apiKey": "widget-key", "whitelistedDomains": [ "example.com" ], "size": "dynamic", "width": null, "height": null, "theme": { "default": "dark", "dark": { "name": "Custom Dark", "accent": "#7C3AED", "accent2": "#22C55E", "accent3": "#F59E0B", "accent4": "#EF4444", "text": "#FFFFFF", "text2": "#E5E7EB", "text3": "#D1D5DB", "text4": "#9CA3AF", "text5": "#6B7280", "text6": "#4B5563", "background": "#111827", "background2": "#1F2937", "background3": "#374151", "background4": "#4B5563", "background5": "#6B7280", "background6": "#9CA3AF", "background7": "#D1D5DB", "divider": "#374151", "divider2": "#4B5563", "shadow": "#000000", "scrollbarBackground": "#1F2937", "scrollbarThumb": "#6B7280" } }, "font": "Inter", "ctaButton": { "enabled": true, "text": "Join", "link": "https://example.com/join" }, "button": { "enabled": true, "text": "View leaderboard", "link": "https://example.com/leaderboard" }, "domains": [ "example.com" ], "communityThemeOverride": true }, "banner": { "enabled": true, "title": "April Challenge", "description": "Compete for the top monthly prize.", "image": "https://cdn.example.com/banners/april.png" }, "translations": { "name": [ { "languageCode": "en", "translation": "April Last Leaderboard" }, { "languageCode": "th", "translation": "April Leaderboard TH" } ], "description": [ { "languageCode": "en", "translation": "Monthly leaderboard created through the partner API." } ] }, "enableLeaderboardReset": true, "leaderboardResetFrequency": "weekly", "enablePrizePool": true, "prizes": [ { "_id": "prize-1", "position": 1, "positionFrom": null, "positionTo": null, "isRange": false, "prizeName": "Champion Reward", "useRewardAsPrizeName": false, "coins": 1000, "xp": 500, "customFields": [ { "id": "wallet-address", "fieldType": "text", "fieldName": "Wallet Address", "description": "Wallet address used for prize delivery.", "placeholderText": "0x...", "isRequired": true, "isExpanded": false } ] }, { "_id": "prize-2", "position": null, "positionFrom": 2, "positionTo": 5, "isRange": true, "prizeName": "Top 5 Reward", "useRewardAsPrizeName": false, "coins": 500, "xp": 250, "customFields": [] } ], "userInformationDisplay": [ { "field": "name", "displayMode": "full", "order": 0 }, { "field": "email", "displayMode": "partial", "order": 1 } ], "leaderboardPageConfig": { "bannerDisplay": { "enabled": true }, "rolesUsers": { "roles": [ "6502c97314a3e564c5bbfa84" ], "users": [] }, "viewingPermission": { "roles": [ "6502c97314a3e564c5bbfa84" ], "users": [] }, "enableWidgets": { "enabled": true }, "guestMode": { "enabled": false }, "leftPanel": { "leaderboardName": true, "startAndEndDate": true, "countdown": true, "eventImage": true, "eventDescription": true, "prizePool": true }, "rightPanel": { "podium": true, "userPosition": true, "hallOfChampions": true }, "timeFilterView": { "allTime": true, "daily": true, "weekly": true, "monthly": true, "yearly": false } }, "enabled": true, "previewEnabled": false, "displayOrder": 1, "order": 1, "selected": false, "createdAt": "2026-05-20T10:00:00.000Z", "updatedAt": "2026-05-20T10:00:00.000Z" } ] }

List leaderboards with pagination

What this endpoint does

Quick start

Authentication and permission

Complete examples

Success and readback

Errors and recovery

Retry safety

Gotchas

Next steps

Request

Responses

List leaderboards with pagination

What this endpoint does#

Quick start#

Authentication and permission#

Complete examples#

Success and readback#

Errors and recovery#

Retry safety#

Gotchas#

Next steps#

Request

Responses

What this endpoint does

Quick start

Authentication and permission

Complete examples

Success and readback

Errors and recovery

Retry safety

Gotchas

Next steps