API reference / Gamification / Leaderboards

Get leaderboard

Read one leaderboard in the community that owns your API key, with its schedule, audience, prizes and display settings.

Last updated 26 Sep 2026API v1

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

When to use this

Confirm a leaderboard you just created or changed.
Read a leaderboard's current schedule, audience and prizes before you update it.
Check whether a leaderboard is live (enabled) when traders say they can't see it.

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 a leaderboard in another community returns 404.

Behaviour#

enabled decides whether the leaderboard is live. Traders see it only if they are on a view or rank list; @all in roles covers everyone. Dates in duration are read in the leaderboard's timeZone, which is minutes from UTC.

Request#

Path parameters#

leaderboardID#stringREQUIRED

The leaderboard's _id, from List leaderboards or Create leaderboard.

Rule24-character hex ID

Eg66f000000000000000000301

Query parameters#

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/66f000000000000000000301 \
  --header 'Authorization: Bearer <API_KEY>'

Response#

A 200 returns the leaderboard in data, with user, role and tag references expanded. Branch on the HTTP status. With fields, only the fields you ask for come back, plus _id.

meta#objectALWAYS

Status of the request. There is no meta.code on success.

status#stringALWAYS

Result of the request.

Rulesuccess

statusCode#integerALWAYS

The HTTP status, repeated.

message#stringALWAYS

Human-readable summary. Do not branch on it.

data#objectALWAYS

The leaderboard.

Eg{ ... }

_id#string

Leaderboard ID.

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
  },
  "message": "Read leaderboard 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. 404, 500 and 502 errors have no code; branch on the HTTP status and read detail.

Fix the request04

400VALIDATION_FAILEDFix the request

leaderboardID isn't a valid ID, or fields names a field that doesn't exist. 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.

Fix the data01

404Fix the data

No leaderboard with this ID in your community. It may have been deleted, or belong to another community. Find the ID again with List leaderboards.

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": {
    "leaderboardID": "leaderboardID must be a valid MongoDB ObjectId string"
  },
  "solution": "Please check the request and try again"
}

Next step#

Update an existing leaderboardPATCH/v1/leaderboards/{leaderboardID}Change the leaderboard's schedule, audience, prizes or display settings.

Back to List leaderboards

Get leaderboard

When to use this

01Authentication#

02Behaviour#

03Request#

Path parameters#

Query parameters#

Headers#

04Response#

05Errors#

06Next step#

Authentication#

Behaviour#

Request#

Response#

Errors#

Next step#