Get all leaderboards

Get all leaderboards for your organization. Finished leaderboards are excluded by default.

GET /leaderboards

JavaScript

JavaScript

import { TrophyApiClient } from '@trophyso/node';

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

const response = await trophy.leaderboards.all();

200

[
  {
    "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": null
  }
]

Rate Limits

Tier 2

Authorizations

X-API-KEY · string · header · required

Query Parameters

includeFinished · boolean · default: false

When set to 'true', leaderboards with status 'finished' will be included in the response. By default, finished leaderboards are excluded.

Response

200

application/json

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 | null · 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, null

Example:

"day"

runInterval · integer | null · required

The interval between repetitions, relative to the start date and repetition type. Null for one-time leaderboards.

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"