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.

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

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

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"