> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XblLeaderboardQuery

> XblLeaderboardQuery

# XblLeaderboardQuery

Represents the parameters for submitting a leaderboard query using event-based or title-based stats.

## Syntax

```cpp theme={null}
typedef struct XblLeaderboardQuery {  
    uint64_t xboxUserId;  
    char scid[XBL_SCID_LENGTH];  
    const char* leaderboardName;  
    const char* statName;  
    XblSocialGroupType socialGroup;  
    const char** additionalColumnleaderboardNames;  
    size_t additionalColumnleaderboardNamesCount;  
    XblLeaderboardSortOrder order;  
    uint32_t maxItems;  
    uint64_t skipToXboxUserId;  
    uint32_t skipResultToRank;  
    const char* continuationToken;  
    XblLeaderboardQueryType queryType;  
} XblLeaderboardQuery  
```

### Members

*xboxUserId*\
Type: uint64\_t

Optional XBOX user ID of the requesting user. If doing a global leaderboard, then set to 0.

*scid*\
Type: char\[XBL\_SCID\_LENGTH]

The UTF-8 encoded service configuration ID (SCID) of the title.

*leaderboardName*\
Type: const char\*

Optional UTF-8 encoded leaderboard name to get a leaderboard for. Set to nullptr if querying a social leaderboard or a title managed stat backed leaderboard.

*statName*\
Type: const char\*

Optional UTF-8 encoded statistic name to get a leaderboard for. Used when querying a social leaderboard or title managed stat backed leaderboard.

*socialGroup*\
Type: [XblSocialGroupType](/reference/live/xsapi-c/leaderboard_c/enums/xblsocialgrouptype.md)

Optional the social group of users to get leaderboard results. For example, to get a "friends only" leaderboard. Set to XblSocialGroupType\_None to get a global leaderboard.

*additionalColumnleaderboardNames*\
Type: const char\*\*

Optional UTF-8 encoded array of names of stats for the additional columns.

*additionalColumnleaderboardNamesCount*\
Type: size\_t

Optional count of additionalColumnleaderboardNames passed in.

*order*\
Type: [XblLeaderboardSortOrder](/reference/live/xsapi-c/leaderboard_c/enums/xblleaderboardsortorder.md)

Set sort order for the resulting leaderboard.

*maxItems*\
Type: uint32\_t

Set the maximum number of items that the resulting leaderboard contains. Set to 0 to let the service return the default maximum number of items.

*skipToXboxUserId*\
Type: uint64\_t

Set which user the resulting leaderboard centers around. Set to 0 to not skip to a specific user.

*skipResultToRank*\
Type: uint32\_t

Set which rank the resulting leaderboard centers around. Set to 0 to not skip to a specific rank.

*continuationToken*\
Type: const char\*

The UTF-8 encoded continuationToken used to get the next set of leaderboard data.

*queryType*\
Type: [XblLeaderboardQueryType](/reference/live/xsapi-c/leaderboard_c/enums/xblleaderboardquerytype.md)

The type of leaderboard to query for.

## Member of

[XblLeaderboardResult](/reference/live/xsapi-c/leaderboard_c/structs/xblleaderboardresult.md)

## Argument of

[XblLeaderboardGetLeaderboardAsync](/reference/live/xsapi-c/leaderboard_c/functions/xblleaderboardgetleaderboardasync.md)

## Remarks

### Event-based Stats

When using the *statName* member with [event-based Stats](/services/xbox-services/player-data/stats-leaderboards/event-based/live-stats-eb-overview.md), the value should coincide with a [stat instance](/services/xbox-services/player-data/stats-leaderboards/event-based/live-stats-eb-overview.md#defining-stat-instances).

### Title-managed Stats

When using [title-managed Stats](/services/xbox-services/player-data/stats-leaderboards/title-managed/live-stats-tm-overview.md) for leaderboards, setting *skipToXboxUserId* to a nonzero value compares the given *xboxUserId*'s stored stat against the global leaderboard.

Similarly, setting *socialGroup* to People or Favorites compares the stored stats of the given *xboxUserId* and the associated users. It doesn't use values of the global leaderboard.

**Note that when a player's stored stat and their score on the global leaderboard aren't the same, this can result in mismatched outputs.**

> [!NOTE]
>
> For title-managed Stats, the global leaderboard entry for a player isn't a direct projection of their current stored stat. The leaderboard service **maintains only the highest recorded value** for each player. As a result, **writing a lower value to a stat doesn't lower that player's position on the global leaderboard**; the leaderboard keeps reflecting the previously recorded high. The stored stat itself, queryable through `XblUserStatisticsGet*` or `XblTitleManagedStatsGetForUserAsync`, reflects the value most recently written, which is why it can diverge from the leaderboard.
>
> If your title needs leaderboard positions to decrease, title-managed Stats aren't suitable. Examples include a rating that goes up or down, or a score that resets on losses. Instead, consider event-based Stats with a `Replace` rule, or an external leaderboard service such as [PlayFab Leaderboards v2](/services/playfab/community/leaderboards/index.md). For more discussion of this behavior, see the `LeaderboardsTitleManaged` Microsoft Game Development Kit (GDK) sample's [Implementation Notes](https://github.com/microsoft/Xbox-GDK-Samples/blob/main/Samples/Live/LeaderboardsTitleManaged/readme_en-us.md).

## Requirements

**Header:** leaderboard\_c.h

## See also

[leaderboard\_c](/reference/live/xsapi-c/leaderboard_c/leaderboard_c_members)\
[Event-based vs. title-managed Stats](/services/xbox-services/player-data/stats-leaderboards/live-stats-eb-vs-tm.md)


## Related topics

- [XblLeaderboardQueryType](/reference/live/xsapi-c/leaderboard_c/enums/xblleaderboardquerytype.md)
- [Leaderboards](/build/steam-porting-guide/features/steam-leaderboards.md)
- [Getting a title-managed leaderboard](/services/xbox-services/player-data/stats-leaderboards/title-managed/how-to/live-getting-tm-leaderboard.md)
- [XblLeaderboardGetLeaderboardAsync](/reference/live/xsapi-c/leaderboard_c/functions/xblleaderboardgetleaderboardasync.md)
- [XblLeaderboardSortOrder](/reference/live/xsapi-c/leaderboard_c/enums/xblleaderboardsortorder.md)