> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opigno.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Challenge leaderboards
Opigno Enterprise API provides queries to build different types of the leaderboards.
All these queries return a list of `ChallengeParticipant` objects:
| Parameter | Type | Description |
| :------------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `completedOn` | `Int` | **Required**. A timestamp when the attempt has been completed. Will be empty if the attempt is still in progress. |
| `id` | `ID` | **Required**. ID of the related attempt. |
| `isAnonymized` | `Boolean` | **Required**. A marker that shows that the challenge results returned anonymized. |
| `name` | `String` | **Required**. A label of the related user context. Only first letters of name and surname will be returned if anonymization is enabled in the challenge. |
| `rank` | `Int` | **Required**. The attempt rank in the related challenge. |
| `score` | `Float` | **Required**. The total number of points that is earned by the related API user for the challenge. |
| `timeSpent` | `Int` | **Required**. The time (in seconds) that the user spent answering the related challenge questions. |
| `uuid` | `ID` | **Required**. UUID of the related user context. |
**Important**: results for these queries can be retrieved only if the ranking and
leaderboard displaying is enabled for the challenge in the backoffice.
## Classic leaderboard
Use the `getChallengeParticipants` query to get the full list of challenge participants or users with the same specific rank.
Results will be returned with the pagination and possibility to change the order and sorting key (default sorting is by the rank, ascending).
The following arguments can be used in the query:
| Argument | Type | Description | Default |
| :------------ | :----------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------ |
| `after` | `Cursor` | Returns results that come after the specified cursor. Should be used together with `first` parameter. Cannot be used if `before` is set. | — |
| `before` | `Cursor` | Returns results that come before the specified cursor. Should be used together with `last` parameter. Cannot be used if `after` is set. | — |
| `challengeId` | `ID` | ID of the challenge to retrieve the participants. | — |
| `first` | `Int` | Returns up to the first N elements from the list. Required if `after` parameter is set. Cannot be used together with `last`. | — |
| `last` | `Int` | Returns up to the first N elements from the list. Required if `before` parameter is set. Cannot be used together with `first`. | — |
| `rank` | `Int` | Optional filter by the rank. If the ranking displaying is disabled for the challenge, this filter will be omitted and all results will be returned (taking into account all other filters). | — |
| `reverse` | `Boolean` | Allows to reverse the order of the underlying list (default order is ascending). | `false` |
| `sortKey` | `ChallengeParticipantsSortKey` | Allows to change the results sorting. Available options: `RANK` (default), `NAME` (sorting by the user context name; it makes sense to use it only if the real user name is sent to the API during the user context synchronization), `COMPLETED_ON` (sorting by the challenge completion date). | `RANK` |
Here is an example of the query execution:
```filename GraphQL query theme={null}
query getChallengeParticipants {
getChallengeParticipants(challengeId: 1, first: 4, rank: 3, sortKey: "NAME") {
edges {
node {
name
score
rank
timeSpent
}
}
totalItems
}
}
```
```File Query result example [expandable] theme={null}
{
"data": {
"getChallengeParticipants": {
"edges": {
[
"node": {
"name": "David Hawk",
"score": 80,
"rank": 3,
"timeSpent": 95
}
],
[
"node": {
"name": "John Doe",
"score": 80,
"rank": 3,
"timeSpent": 93
}
]
},
"totalItems": 2
}
}
}
```
## Relative leaderboard
The relative leaderboard shows competitors closest in ranking to the current API user. The logic of displaying is the following:
1. `itemsNumberBefore` of users with the higher score than the current API user has earned;
2. the current API user;
3. `itemsNumberAfter` of users with the lower than or the same score as the current API user has earned.
Results will be returned **without** pagination and possibility to change the order.
Parameters `itemsNumberBefore` and `itemsNumberAfter` are limited to 10. If the value is greater than 10, it will be automatically reduced.
To retrieve the data for a relative leaderboard, execute the `getChallengeRelativeLeaderboard` query:
```filename GraphQL theme={null}
query getChallengeRelativeLeaderboard {
getChallengeRelativeLeaderboard(challengeId: 1, itemsNumberBefore: 2, itemsNumberAfter: 1) {
name
score
rank
timeSpent
}
}
```
```File Query result [expandable] theme={null}
{
"data": {
"getChallengeRelativeLeaderboard": {
{
"name": "Malcolm Raynolds",
"score": 100,
"rank": 1,
"timeSpent": 77
},
{
"name": "Jane Tailor",
"score": 90,
"rank": 2,
"timeSpent": 75
},
{
"name": "John Doe",
"score": 80,
"rank": 3,
"timeSpent": 93
},
{
"name": "David Hawk",
"score": 80,
"rank": 3,
"timeSpent": 95
}
}
}
}
```
## Related Features
The `getChallengeParticipants` query supports the same advanced features as other catalog queries:
Learn how to efficiently navigate through large sets of items using cursor-based pagination.
Understand the authentication requirements and how to properly authenticate your requests.