Skip to main content
GET
/
leaderboards
JavaScript
import { TrophyApiClient } from '@trophyso/node';

const trophy = new TrophyApiClient({
  apiKey: 'YOUR_API_KEY'
});

const response = await trophy.leaderboards.all();
[
  {
    "id": "5100fe51-6bce-6j44-b0hs-bddc4e123682",
    "name": "Weekly Word Count Challenge",
    "key": "weekly-words",
    "rankBy": "metric",
    "metricKey": "words-written",
    "metricName": "Words Written",
    "description": "Compete weekly to see who writes the most words",
    "status": "active",
    "start": "2025-01-01",
    "end": null,
    "maxParticipants": 100,
    "breakdownAttribute": null,
    "runUnit": "day",
    "runInterval": 7
  },
  {
    "id": "5100fe51-6bce-6j44-b0hs-bddc4e123683",
    "name": "XP Leaderboard",
    "key": "xp-board",
    "rankBy": "points",
    "pointsSystemKey": "xp-system",
    "pointsSystemName": "Experience Points",
    "description": "Overall ranking by XP earned",
    "status": "active",
    "start": "2025-01-01",
    "end": null,
    "maxParticipants": 50,
    "breakdownAttribute": null,
    "runUnit": null,
    "runInterval": 0
  }
]

Authorizations

​
X-API-KEY
string
header
required

Response

Successful operation

​
id
string
required

The unique ID of the leaderboard.

Example:

"5100fe51-6bce-6j44-b0hs-bddc4e123682"

​
name
string
required

The user-facing name of the leaderboard.

Example:

"Weekly Word Count Challenge"

​
key
string
required

The unique key used to reference the leaderboard in APIs.

Example:

"weekly-words"

​
rankBy
enum<string>
required

What the leaderboard ranks by.

Available options:
points,
streak,
metric
Example:

"metric"

​
breakdownAttribute
string | null
required

The key of the attribute to break down this leaderboard by.

Example:

"country"

​
description
string
required

The user-facing description of the leaderboard.

Example:

"Compete weekly to see who writes the most words"

​
start
string<date>
required

The start date of the leaderboard in YYYY-MM-DD format.

Example:

"2025-01-01"

​
end
string<date> | null
required

The end date of the leaderboard in YYYY-MM-DD format, or null if it runs forever.

Example:

"2025-12-31"

​
maxParticipants
integer
required

The maximum number of participants in the leaderboard.

Example:

100

​
runUnit
enum<string> | null
required

The repetition type for recurring leaderboards, or null for one-time leaderboards.

Available options:
day,
month,
year
Example:

"day"

​
runInterval
integer
required

The interval between repetitions, relative to the start date and repetition type.

Example:

7

​
status
enum<string>
required

The status of the leaderboard.

Available options:
active,
scheduled,
finished
Example:

"active"

​
metricKey
string

The key of the metric to rank by, if rankBy is 'metric'.

Example:

"words-written"

​
metricName
string

The name of the metric to rank by, if rankBy is 'metric'.

Example:

"Words Written"

​
pointsSystemKey
string

The key of the points system to rank by, if rankBy is 'points'.

Example:

"xp-system"

​
pointsSystemName
string

The name of the points system to rank by, if rankBy is 'points'.

Example:

"Experience Points"