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

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

const response = await trophy.leaderboards.get("weekly-words", {
  offset: 0,
  limit: 10,
  run: "2025-01-15"
});
{
  "id": "5100fe51-6bce-6j44-b0hs-bddc4e123682",
  "name": "Weekly Word Count Challenge",
  "key": "weekly-words",
  "rankBy": "metric",
  "metricKey": "words-written",
  "metricName": "Words Written",
  "pointsSystemKey": null,
  "pointsSystemName": null,
  "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,
  "rankings": [
    {
      "userId": "user-123",
      "userName": "Alice Johnson",
      "rank": 1,
      "value": 5000
    },
    {
      "userId": "user-456",
      "userName": "Bob Smith",
      "rank": 2,
      "value": 4500
    },
    {
      "userId": "user-789",
      "userName": "Charlie Brown",
      "rank": 3,
      "value": 4200
    }
  ]
}

Authorizations

​
X-API-KEY
string
header
required

Path Parameters

​
key
string
required

Unique key of the leaderboard as set when created.

Query Parameters

​
offset
integer
default:0

Number of rankings to skip for pagination.

Required range: x >= 0
​
limit
integer
default:10

Maximum number of rankings to return. Cannot be greater than the size of the leaderboard.

Required range: x >= 0
​
run
string<date>

Specific run date in YYYY-MM-DD format. If not provided, returns the current run.

​
userId
string

When provided, offset is relative to this user's position on the leaderboard. If the user is not found in the leaderboard, returns empty rankings array.

​
userAttributes
string

Attribute key and value to filter the rankings by, separated by a colon. For example, city:London. This parameter is required, and only valid for leaderboards with a breakdown attribute.

Response

Successful operation

A leaderboard with its configuration details.

​
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"

​
rankings
LeaderboardRanking · object[]
required

Array of user rankings for the leaderboard.

​
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"