Skip to main content
Opigno Enterprise API provides queries to build different types of the leaderboards. All these queries return a list of ChallengeParticipant objects:
ParameterTypeDescription
completedOnIntRequired. A timestamp when the attempt has been completed. Will be empty if the attempt is still in progress.
idIDRequired. ID of the related attempt.
isAnonymizedBooleanRequired. A marker that shows that the challenge results returned anonymized.
nameStringRequired. A label of the related user context. Only first letters of name and surname will be returned if anonymization is enabled in the challenge.
rankIntRequired. The attempt rank in the related challenge.
scoreFloatRequired. The total number of points that is earned by the related API user for the challenge.
timeSpentIntRequired. The time (in seconds) that the user spent answering the related challenge questions.
uuidIDRequired. 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:
ArgumentTypeDescriptionDefault
afterCursorReturns results that come after the specified cursor. Should be used together with first parameter. Cannot be used if before is set.—
beforeCursorReturns results that come before the specified cursor. Should be used together with last parameter. Cannot be used if after is set.—
challengeIdIDID of the challenge to retrieve the participants.—
firstIntReturns up to the first N elements from the list. Required if after parameter is set. Cannot be used together with last.—
lastIntReturns up to the first N elements from the list. Required if before parameter is set. Cannot be used together with first.—
rankIntOptional 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).—
reverseBooleanAllows to reverse the order of the underlying list (default order is ascending).false
sortKeyChallengeParticipantsSortKeyAllows 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: 
query getChallengeParticipants {
  getChallengeParticipants(challengeId: 1, first: 4, rank: 3, sortKey: "NAME") {
    edges {
      node {
        name
        score
        rank
        timeSpent
      }
    }
    totalItems
  }
}

​
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: 
query getChallengeRelativeLeaderboard {
  getChallengeRelativeLeaderboard(challengeId: 1, itemsNumberBefore: 2, itemsNumberAfter: 1) {
    name
    score
    rank
    timeSpent
  }
}
The getChallengeParticipants query supports the same advanced features as other catalog queries:

Pagination

Learn how to efficiently navigate through large sets of badges using cursor-based pagination.

Authentication

Understand the authentication requirements and how to properly authenticate your requests.