Skip to main content
GET
JavaScript

Authorizations

X-API-KEY
string
header
required

Headers

Tenant-ID
string

The tenant identifier for multi-tenant organisations. Required when the organisation has multi-tenancy enabled. The value should be your internal ID for the tenant. Ignored for single-tenant organisations.

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 days to return in the leaderboard history for the user.

Required range: 0 <= x <= 100

Response

Successful operation

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

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
deprecated

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

Example:

"country"

breakdownAttributes
string[]
required

The user attribute keys that this leaderboard is broken down by.

The key of a user attribute in this leaderboard breakdown.

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"

startTime
string | null
required

When set, ranking only counts activity at or after this time of day in the user's timezone (HH:mm format).

Pattern: ^([01][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$
Example:

"09:00"

endTime
string | null
required

When set, ranking only counts activity before this time of day in the user's timezone (HH:mm format).

Pattern: ^([01][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$
Example:

"17:00"

maxParticipants
integer | null
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

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 daily change events showing the user's rank and value 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"