Saltar al contenido principal
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
    }
  ]
}
Límites de velocidad

Autorizaciones

X-API-KEY
string
header
requerido

Parámetros de ruta

id
string
requerido

The user's ID in your database.

key
string
requerido

Unique key of the leaderboard as set when created.

Parámetros de consulta

run
string<date>

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

numEvents
integer
predeterminado:10

The number of events to return in the history array.

Rango requerido: 1 <= x <= 100

Respuesta

Successful operation

A user's data for a specific leaderboard including rank, value, and history.

id
string
requerido

The unique ID of the leaderboard.

Ejemplo:

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

name
string
requerido

The user-facing name of the leaderboard.

Ejemplo:

"Weekly Word Count Challenge"

key
string
requerido

The unique key used to reference the leaderboard in APIs.

Ejemplo:

"weekly-words"

rankBy
enum<string>
requerido

What the leaderboard ranks by.

Opciones disponibles:
points,
streak,
metric
Ejemplo:

"metric"

breakdownAttribute
string | null
requerido

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

Ejemplo:

"country"

description
string | null
requerido

The user-facing description of the leaderboard.

Ejemplo:

"Compete weekly to see who writes the most words"

start
string<date>
requerido

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

Ejemplo:

"2025-01-01"

end
string<date> | null
requerido

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

Ejemplo:

"2025-12-31"

maxParticipants
integer
requerido

The maximum number of participants in the leaderboard.

Ejemplo:

100

runUnit
enum<string> | null
requerido

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

Opciones disponibles:
day,
month,
year,
null
Ejemplo:

"day"

runInterval
integer | null
requerido

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

Ejemplo:

7

rank
integer | null
requerido

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

Ejemplo:

2

value
integer | null
requerido

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

Ejemplo:

4500

history
LeaderboardEvent · object[]
requerido

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'.

Ejemplo:

"words-written"

metricName
string

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

Ejemplo:

"Words Written"

pointsSystemKey
string

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

Ejemplo:

"xp-system"

pointsSystemName
string

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

Ejemplo:

"Experience Points"