API reference / Gamification / Leaderboards

List leaderboards

List the leaderboards in the community that owns your API key, one page at a time.

Last updated 26 Sep 2026API v1

Method: GET
Path: https://api.returning.ai/v1/leaderboards
Permission: leaderboard
Retries: Read-only; exact retries are safe

When to use this

Find a leaderboard's ID before you read or change it.
Check that a slug or name is free before you create a leaderboard.
Audit which leaderboards are live and who can see them.

Authentication#

Header: Authorization: Bearer <API_KEY>
Permission: leaderboardShown in the dashboard as “Leaderboard”

Send a Community API key with the leaderboard permission. The key decides the community, so never send a community ID.

Behaviour#

The list includes every leaderboard in your community, whether or not it is enabled, started or ended, and whoever it is visible to. Without sort, the oldest leaderboard comes first; to show them in their display order, sort data by displayOrder yourself.

Request#

Query parameters#

page#integerOPTIONAL

Page number, starting at 1.

RuleWhole number, 1 or more; default 1

Eg1

limit#integerOPTIONAL

Leaderboards per page, up to 100.

RuleDefault 20; max 100

Eg20

sort#stringOPTIONAL

One field and a direction. Sortable fields are createdAt, updatedAt, name and slug. Without it, the oldest leaderboard comes first.

Rulefield:asc or field:desc

EgcreatedAt:desc

search#stringOPTIONAL

keyword:<text> matches the name or slug; name:<text> or slug:<text> matches one of them. Matches anywhere in the value, ignoring case.

Rulekeyword:, name: or slug: prefix

Egkeyword:trading

fields#stringOPTIONAL

Comma-separated fields to return; _id always comes back. Use the stored names here: leaderImage returns image, serverId returns communityID.

RuleLeaderboard field names

Egname,slug,enabled,duration

Headers#

Authorization#stringREQUIRED

Community API key with leaderboard.

RuleBearer <API_KEY>

curl --request GET \
  --url 'https://api.returning.ai/v1/leaderboards?page=1&limit=20&sort=createdAt:desc' \
  --header 'Authorization: Bearer <API_KEY>'

Response#

A 200 returns the page in data and the paging details in meta. When meta.page * meta.limit is less than meta.total, request the next page. Branch on the HTTP status.

meta#objectALWAYS

Status and paging details. There is no meta.code on success.

status#stringALWAYS

Result of the request.

Rulesuccess

statusCode#integerALWAYS

The HTTP status, repeated.

page#integerALWAYS

The page returned.

limit#integerALWAYS

The page size used.

total#integerALWAYS

Leaderboards that match your search, across all pages.

message#stringALWAYS

Human-readable summary. Do not branch on it.

data#object[]ALWAYS

Leaderboards on this page. An empty array when none match.

Eg[ ... ]

_id#string

Leaderboard ID. Use it to read, update or delete the leaderboard.

Eg"66f000000000000000000301"

communityID#string

Your community ID.

Eg"66f000000000000000000010"

kind#string

default for your community's built-in Default Leaderboard, which can't be deleted; custom for every other leaderboard.

name#string

Leaderboard name.

Eg"Monthly Trading Volume"

slug#string

URL-friendly ID, unique in your community.

Eg"monthly-trading-volume"

description#string

Description shown to traders. Empty string when none.

Eg"Top traders by trading volume each month."

image#string

Leaderboard image URL, when one is set.

enabled#boolean

true when the leaderboard is live for the traders who can see it.

Egtrue

displayOrder#number

Position among your leaderboards, starting at 1. Older leaderboards may not have one.

Eg2

order#number

Same value as displayOrder.

Eg2

rankBy#string

What traders are ranked by: XP, Coins, Referrals, or a user-field key.

Eg"tradingvolume"

duration#object

When the leaderboard runs.

Eg{ ... }

start#string

Start date. The leaderboard starts at startTime on this date, in its time zone.

Eg"2026-10-01T00:00:00.000Z"

end#string

End date, or null when there is none.

RuleNullable

Egnull

noEndDate#boolean

true when the leaderboard runs with no end date.

timeZone#number

Time zone as an offset from UTC in minutes, for example 480 for UTC+8.

startTime#object

Start time of day, as hours (1-12), minutes and ampm.

endTime#object

End time of day, in the same format.

timeFilters#string[]

Period tabs traders can switch between: all-time, daily, weekly, monthly, yearly.

Eg["monthly", "all-time"]

rankedUserRoles#object

Traders who get ranked.

Eg{ ... }

users#object[]

Traders listed one by one, as id (numeric platform user ID), _id, username and email. The last three are null for a trader who has left your community.

roles#object[]

Roles, as _id and name. name is null for a deleted role.

tags#object[]

Tags, as _id and name. name is null for a deleted tag.

viewPermissionUserRoles#object

Traders who can see the leaderboard, in the same shape as rankedUserRoles.

Eg{ ... }

enableLeaderboardReset#boolean

true when scores restart every period.

Egtrue

leaderboardResetFrequency#string

How often scores restart: daily, weekly, monthly or yearly.

Eg"monthly"

enablePrizePool#boolean

true when prizes are paid.

Egfalse

prizes#object[]

Prize rows by rank.

Eg[]

displayedFields#string[]

Columns shown in the leaderboard table.

Eg["user", "tier", "level"]

displayFieldsOrder#string[]

Column order.

Eg["user", "tier", "level"]

performanceDisplay#object

Table display options: showTop blurs rows below the top value ranks, showPositive hides scores of 0 or less.

Eg{ ... }

userInformationDisplay#object[]

How much of each trader's details the table shows.

Eg[]

previewEnabled#boolean

true when guests can see the leaderboard, if your community allows guest preview.

Egfalse

selected#boolean

true for the one leaderboard your community has set as its active leaderboard.

Egfalse

updatedAt#string

When the leaderboard last changed, ISO 8601 UTC.

Eg"2026-09-26T08:30:00.000Z"

createdAt#string

When the leaderboard was created, ISO 8601 UTC.

Eg"2026-09-26T08:30:00.000Z"

translations#object

Translated names and descriptions, when set.

leaderboardPageConfig#object

Leaderboard page layout settings, when set.

configurationHistory#object[]

Log of settings changes. Present only on the Default Leaderboard after it has been changed.

{
  "meta": {
    "status": "success",
    "statusCode": 200,
    "page": 1,
    "limit": 20,
    "total": 1
  },
  "message": "Read leaderboards success.",
  "data": [
    {
      "_id": "66f000000000000000000301",
      "communityID": "66f000000000000000000010",
      "kind": "custom",
      "name": "Monthly Trading Volume",
      "slug": "monthly-trading-volume",
      "description": "Top traders by trading volume each month.",
      "rankBy": "tradingvolume",
      "displayedFields": ["user", "tier", "level"],
      "displayFieldsOrder": ["user", "tier", "level"],
      "timeFilters": ["monthly", "all-time"],
      "performanceDisplay": {
        "showTop": {
          "enabled": false,
          "value": 0
        },
        "showPositive": {
          "enabled": false
        },
        "showDummy": {
          "enabled": false
        }
      },
      "duration": {
        "start": "2026-10-01T00:00:00.000Z",
        "end": null,
        "noEndDate": true,
        "timeZone": 0,
        "startTime": {
          "hours": 12,
          "minutes": 0,
          "ampm": "AM"
        },
        "endTime": {
          "hours": 11,
          "minutes": 59,
          "ampm": "PM"
        }
      },
      "rankedUserRoles": {
        "users": [],
        "roles": [
          {
            "_id": "66f000000000000000000502",
            "name": "@all"
          }
        ],
        "tags": []
      },
      "viewPermissionUserRoles": {
        "users": [],
        "roles": [
          {
            "_id": "66f000000000000000000502",
            "name": "@all"
          }
        ],
        "tags": []
      },
      "banner": {},
      "enableLeaderboardReset": true,
      "leaderboardResetFrequency": "monthly",
      "enablePrizePool": false,
      "prizes": [],
      "userInformationDisplay": [],
      "enabled": true,
      "previewEnabled": false,
      "selected": false,
      "displayOrder": 2,
      "order": 2,
      "updatedAt": "2026-09-26T08:30:00.000Z",
      "createdAt": "2026-09-26T08:30:00.000Z"
    }
  ]
}

Errors#

401, 403 and 400 errors carry a code in meta.code. 500 and 502 errors have no code; branch on the HTTP status and read detail.

Fix the request04

400VALIDATION_FAILEDFix the request

A query value is malformed or out of range, such as limit over 100, sort=displayOrder, or search without a field: prefix. detail names the parameter.

401AUTH_API_KEY_REQUIREDFix the request

No key was sent. Send Authorization: Bearer <API_KEY>.

401AUTH_API_KEY_INVALIDFix the request

The key is unknown, expired or malformed. Use a current Community API key.

403AUTH_PERMISSION_REQUIREDFix the request

The key lacks leaderboard. Add the permission in Settings > Integration > API Keys.

Retry with backoff03

500Retry with backoff

The read failed unexpectedly. Retry the same request with exponential backoff.

502Retry with backoff

Leaderboards are briefly unavailable. Retry the same request with exponential backoff.

401AUTH_API_KEY_VALIDATION_FAILEDRetry with backoff

The key could not be checked just now. Retry with backoff; the key itself may be fine.

{
  "meta": {
    "status": "error",
    "statusCode": 400,
    "code": "VALIDATION_FAILED"
  },
  "message": "Validation failed",
  "detail": {
    "limit": "limit must not be greater than 100"
  },
  "solution": "Please check the request and try again"
}

Next step#

Get leaderboardGET/v1/leaderboards/{leaderboardID}Read one leaderboard in full, using an _id from this list.

Need a new one? Create leaderboard

List leaderboards

When to use this

01Authentication#

02Behaviour#

03Request#

Query parameters#

Headers#

04Response#

05Errors#

06Next step#

Authentication#

Behaviour#

Request#

Response#

Errors#

Next step#