List leaderboards with pagination
GET
https://sgtr-api.returning.ai/v1/leaderboards
Gamification/Leaderboards
What this endpoint does
leaderboard receives 403, not a catalog.INFO
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
https://api.returning.ai:GET /v1/leaderboards — mounted. 403 when leaderboard is missing.GET /leaderboards — not mounted (404).Authentication and permission
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
{
"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"
}?page=1&limit=5.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
}
]
}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
200 Read leaderboards success. is the list and the readback for create/update/delete. Use _id from data[] on get / patch / delete.CHECK
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
403 without changing the key.Gotchas
/v1/leaderboards on this gateway.403 is a missing permission, not a missing product.Next steps
Request
Query Params
Header Params
Responses
Request Request Example
Shell
JavaScript
Java
Swift
curl --location 'https://sgtr-api.returning.ai/v1/leaderboards?page=1&limit=20&sort=displayOrder&fields=name%2Cslug%2CleaderImage%2Cwidget%2CenablePrizePool&search=spring' \
--header 'Authorization: Bearer XXXXXX'Response Response Example
{"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": 600, "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"}]}Modified at 2026-08-19 18:38:48