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

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

const response = await trophy.users.leaderboards("user-123", "weekly-words", {
  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",
  "description": "Compete weekly to see who writes the most words",
  "start": "2025-01-01",
  "end": null,
  "maxParticipants": 100,
  "breakdownAttribute": null,
  "runUnit": "day",
  "runInterval": 7,
  "rank": 2,
  "value": 4500,
  "history": [
    {
      "timestamp": "2025-01-15T10:30:00Z",
      "previousRank": null,
      "rank": 5,
      "previousValue": null,
      "value": 1000
    },
    {
      "timestamp": "2025-01-15T14:15:00Z",
      "previousRank": 5,
      "rank": 3,
      "previousValue": 1000,
      "value": 3000
    },
    {
      "timestamp": "2025-01-15T18:45:00Z",
      "previousRank": 3,
      "rank": 2,
      "previousValue": 3000,
      "value": 4500
    }
  ]
}

Authorizations

​
X-API-KEY
string
header
required

Path Parameters

​
id
string
required

The user's ID in your database.

​
key
string
required

Unique key of the leaderboard as set when created.

Query Parameters

​
run
string<date>

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

​
numEvents
integer
default:10

The number of events to return in the history array.

Required range: 1 <= x <= 100

Response

Successful operation

A user's data for a specific leaderboard including rank, value, and history. A user's data for a specific leaderboard including rank, value, and history. 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 | 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,
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

​
rank
integer | null
required

The user's current rank in this leaderboard. Null if the user is not on the leaderboard.

Example:

2

​
value
integer | null
required

The user's current value in this leaderboard. Null if the user is not on the leaderboard.

Example:

4500

​
history
LeaderboardEvent · object[]
required

An array of events showing the user's rank and value changes over time.

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