Models

spnkr.models.discovery_ugc

Models for the HIUGC_Discovery authority.

Asset

Bases: PascalCaseModel

A game asset, such as a map or game mode.

Attributes:

Name	Type	Description
asset_id	UUID	The asset's GUID.
version_id	UUID	The asset version's GUID.
public_name	str	The asset's name.
description	str	The asset's description.
files	AssetFiles	Information about the files that make up the asset.
contributors	tuple[str, ...]	The names of the asset's contributors.
asset_home	AssetHome	The asset's home.
asset_stats	AssetStats	Statistics about the asset.
inspection_result	InspectionResult	The asset's inspection result.
clone_behavior	CloneBehavior	The asset's clone behavior.
order	int	The asset's order.

AssetFiles

Bases: PascalCaseModel

Information about the files that make up an asset.

Attributes:

Name	Type	Description
prefix	str	The root path to the asset's files.
file_relative_paths	tuple[str, ...]	The relative paths to the asset's files.
prefix_endpoint	OnlineUriReference	Details about the endpoint of prefix.

AssetSearchPage

Bases: PascalCaseModel

A page of map/mode/prefab search results.

Attributes:

Name	Type	Description
tags	tuple[AssetSearchTagCount, ...]	The tags that appear in the filtered search results.
estimated_total	int	The estimated total number of results.
start	int	The index of the first result returned.
count	int	The number of results requested.
result_count	int	The number of results returned.
results	tuple[AssetSearchResult, ...]	The search results.
links	ReadOnlyDict[Any, Any]	...

AssetSearchResult

Bases: PascalCaseModel

An individual asset search result.

Attributes:

Name	Type	Description
asset_id	UUID	The UUID of the asset.
asset_version_id	UUID	The UUID of the asset version.
name	str	The asset's name.
description	str	The asset's description.
asset_kind	AssetKind	The kind of asset, such as "map".
tags	tuple[str, ...]	Keywords for the asset, such as "343i".
thumbnail_url	str	The URL of the asset's thumbnail image.
referenced_assets	tuple[UUID, ...]	The UUIDs of assets referenced by the asset.
original_author	str	The ID of the asset's original author.
likes	int	The number of times the asset has been liked.
bookmarks	int	The number of times the asset has been bookmarked.
plays_recent	int	The number of times the asset has been played recently.
number_of_objects	int	The number of objects in a map/prefab asset.
date_created_utc	Date	The asset's creation date.
date_modified_utc	Date	The asset's modification date.
date_published_utc	Date	The asset's publication date.
has_node_graph	bool | None	Whether the map has a node graph.
read_only_clones	bool	Whether clones of the asset can be modified.
plays_all_time	int	The number of times the asset has been played in total.
contributors	tuple[str, ...]	The IDs of the asset's contributors.
parent_asset_count	int	The number of assets that link to this asset.
average_rating	float	The asset's average rating.
number_of_ratings	int	The number of ratings the asset has received.

AssetSearchTagCount

Bases: PascalCaseModel

A tag name and count.

Attributes:

Name	Type	Description
tag	str	The tag name.
count	int	The number of times the tag appears in the filtered search results.

AssetStats

Bases: PascalCaseModel

Statistics about an asset.

Attributes:

Name	Type	Description
plays_recent	int	The number of times the asset has been played recently.
plays_all_time	int	The number of times the asset has been played in total.
favorites	int	The number of times the asset has been favorited.
likes	int	The number of times the asset has been liked.
bookmarks	int	The number of times the asset has been bookmarked.
parent_asset_count	int	The number of assets that link to this asset.
average_rating	float | None	The asset's average rating.
number_of_ratings	int	The number of ratings the asset has received.

Date

Bases: PascalCaseModel

A date object.

Attributes:

Name	Type	Description
value	datetime	The date value.

Film

Bases: PascalCaseModel

A saved film asset for a match.

Attributes:

Name	Type	Description
film_status_bond	FilmStatus	The status, such as "complete", of the film.
custom_data	FilmCustomData	Data specific to film assets, such as length and chunks.
blob_storage_path_prefix	str	The prefix for the film's blob storage path.
asset_id	UUID	The UUID of the film asset.

highlight_events_url: str | None property

Get the URL for the "highlight events" chunk of the film, if available.

get_chunks_and_urls()

Get (chunk, URL) tuples for all film chunks, in order of index.

URLs are public blob storage URLs for downloading the compressed binary chunk data. The first is the film header, the last chunk is highlight events, and all chunks in between are 20-second replication data chunks.

Returns:

Type	Description
list[tuple[FilmChunk, str]]	The chunk and blob storage URL pairs.

FilmChunk

Bases: PascalCaseModel

A chunk of a saved film.

Attributes:

Name	Type	Description
index	int	The index of the chunk.
chunk_start_time_offset_milliseconds	int	The start time of the chunk, in milliseconds.
duration_milliseconds	int	The duration of the chunk, in milliseconds.
chunk_size	int	The size of the chunk, in bytes.
file_relative_path	str	The relative path to the chunk's file.
chunk_type	FilmChunkType	The type of chunk - header, replication data, or highlight events.

FilmCustomData

Bases: PascalCaseModel

Custom data related to film assets.

Attributes:

Name	Type	Description
film_length	int	The length of the film, in milliseconds.
chunks	tuple[FilmChunk, ...]	The film's chunks.
has_game_ended	bool	Whether the game has ended.
manifest_refresh_seconds	int	...
match_id	UUID	The UUID of the match.
film_major_version	int	The film's major version.

Map

Bases: Asset

A map variant asset.

Attributes:

Name	Type	Description
custom_data	MapCustomData	Custom data related to the map variant.
tags	tuple[str, ...]	Keywords for the map variant asset, such as "343i".
prefab_links	tuple[Asset, ...] | None	Details about prefabricated assets used by the map variant.

MapCustomData

Bases: PascalCaseModel

Custom data related to map variant assets.

Attributes:

Name	Type	Description
num_of_objects_on_map	int	The number of objects on the map.
tag_level_id	int	The ID of the tag level.
is_baked	bool	Whether the map is baked.
has_node_graph	bool	Whether the map has a node graph.

MapModePair

Bases: Asset

A map-mode pair asset.

Attributes:

Name	Type	Description
custom_data	ReadOnlyDict[Any, Any]	Custom data related to the map-mode pair.
tags	tuple[str, ...]	Keywords for the map-mode pair asset, such as "343i".
map_link	Asset | None	Details about the map variant asset.
ugc_game_variant_link	Asset	Details about the game variant asset.

OnlineUriReference

Bases: PascalCaseModel

A reference to an online resource.

Attributes:

Name	Type	Description
authority_id	str	The ID of the authority that hosts the resource.
path	str	The path to the resource, relative to the authority's host.
query_string	str | None	The query string of the resource's URL.
retry_policy_id	str	The ID of the retry policy to use when accessing the resource.
topic_name	str	The name of the topic to use when accessing the resource.
acknowledgement_type_id	int	The ID of the acknowledgement type to use when accessing the resource.
authentication_lifetime_extension_supported	bool	Whether the resource supports extending the lifetime of an authentication token.
clearance_aware	bool	Whether the resource is clearance aware.

Playlist

Bases: Asset

A playlist asset.

Attributes:

Name	Type	Description
custom_data	PlaylistCustomData	Custom data related to the playlist.
tags	tuple[str, ...]	Keywords for the playlist asset, such as "343i".
rotation_entries	tuple[RotationEntry, ...]	The map-mode pairs in the playlist.

PlaylistCustomData

Bases: PascalCaseModel

Custom data related to playlist assets.

Attributes:

Name	Type	Description
playlist_entries	tuple[PlaylistEntry, ...]	The map-mode pairs in the playlist.
strategy	PlaylistEntrySelectionStrategy	The strategy used to select map-mode pairs in the playlist.
min_teams	int	The minimum number of teams needed to make a match.
min_team_size	int	The minimum number of team members needed to make a match.
max_teams	int	The maximum number of teams allowed in a match.
max_team_size	int	The maximum number of team members allowed in a match.
max_team_imbalance	int	The allowable difference in team size.
max_splitscreen_players_allowed	int	The maximum number of players allowed to play splitscreen.
allow_friend_join_in_progress	bool	Whether match players' friends are allowed to join a match in progress.
allow_matchmaking_join_in_progress	bool	Whether new players are allowed to join a match in progress.
allow_bot_join_in_progress	bool	Whether bots are allowed to join a match in progress.
exit_experience_duration_sec	int	The duration of the exit experience, in seconds.
fireteam_leader_kick_allowed	bool	Whether fireteam leaders are allowed to kick members.
disable_midgame_chat	bool	Whether chat is disabled in game.
allowed_device_inputs	tuple[PlaylistDeviceInput, ...]	The input devices allowed in the playlist (KB/M, controller, etc.).
bot_difficulty	PlaylistBotDifficulty	The difficulty of bots in the playlist.
min_fireteam_size	int	The minimum number of players expected in a fireteam.
max_fireteam_size	int	The maximum number of players allowed in a fireteam.

PlaylistEntry

Bases: PascalCaseModel

A map-mode pair in a playlist.

Attributes:

Name	Type	Description
map_mode_pair_asset_id	str	The UUID of the map-mode pair asset.
metadata	RotationWeight	A weighting for the map-mode pair in the playlist.

RotationEntry

Bases: Asset

A map-mode pair in a playlist.

Attributes:

Name	Type	Description
metadata	RotationWeight	A weighting for the map-mode pair in the playlist.

RotationWeight

Bases: PascalCaseModel

A weighting for a map-mode pair in a playlist.

Attributes:

Name	Type	Description
weight	float	The weight of the map-mode pair in the playlist.

UgcGameVariant

Bases: Asset

A user-generated game variant asset.

Attributes:

Name	Type	Description
custom_data	UgcGameVariantCustomData	Custom data related to the game variant.
tags	tuple[str, ...]	Keywords for the game variant asset, such as "343i".
engine_game_variant_link	Asset	Details about the mode's engine game variant.

UgcGameVariantCustomData

Bases: PascalCaseModel

Custom data related to game variant assets.

Attributes:

Name	Type	Description
key_values	ReadOnlyDict[Any, Any]	Key-value pairs of custom data.

spnkr.models.gamecms_hacs

Models for the "gamecms_hacs" authority.

CareerRank

Bases: PascalCaseModel

Information related to career rank progression.

Attributes:

Name	Type	Description
reward_track_path	str	The relative path to the career rank reward track file.

CareerRewardTrack

Bases: PascalCaseModel

The career rank progression reward track.

Attributes:

Name	Type	Description
track_id	str	The reward track's ID.
ranks	tuple[CareerRewardTrackRank, ...]	The list of ranks in the reward track.
name	TranslatableStringWithStatus	The reward track's name.
description	TranslatableStringWithStatus	The reward track's description.
operation_number	int	The reward track's operation number.
date_range	TranslatableStringWithStatus	The reward track's date range.
is_ritual	bool	...
summary_image_path	str	The relative path to the reward track's summary image file.
xp_per_rank	int	The amount of XP awarded per rank.

CareerRewardTrackRank

Bases: PascalCaseModel

A rank in the career rank progression reward track.

Title, subtitle, and grade can be combined for the rank's full name, e.g., "Sergeant Bronze 2".

Attributes:

Name	Type	Description
rank	int	The rank number.
free_rewards	RankRewards	The rewards earned by all players that reach the rank.
paid_rewards	RankRewards	The rewards earned by players that purchase the battle pass and reach the rank.
xp_required_for_rank	int	The amount of XP required to reach the rank.
rank_title	TranslatableStringWithStatus	The rank's title, such as "Private" or "General".
rank_sub_title	TranslatableStringWithStatus	The rank's subtitle, such as "Bronze" or "Onyx".
rank_tier	TranslatableStringWithStatus	The rank's integer tier/grade - the smallest unit of rank progression.
rank_icon	str	The relative path to the rank's icon file. Has a height of 280px.
rank_large_icon	str	The relative path to the rank's large icon file. This is the icon presented after a player acheives the rank. Has a height of 600px.
rank_adornment_icon	str	The relative path to the rank's adornment icon file. Has a height of 196px.
tier_type	str	The rank's tier type, such as "Bronze" or "Onyx".
rank_grade	int	The rank's integer grade. Max is 3.

CsrSeason

Bases: PascalCaseModel

A CSR season.

Attributes:

Name	Type	Description
csr_season_file_path	str	The relative path to the CSR season file. The stem of the path is the CSR season's ID, e.g., "CsrSeason5-1".
start_date	Date	The UTC start date of the season.
end_date	Date	The UTC end date of the season.

CsrSeasonCalendar

Bases: PascalCaseModel

A collection of past and current CSR seasons.

Attributes:

Name	Type	Description
seasons	tuple[CsrSeason, ...]	The list of CSR seasons.

CurrencyReward

Bases: PascalCaseModel

A currency reward, such as an XP boost.

Attributes:

Name	Type	Description
currency_path	str	The relative path to the currency file.
amount	int	The quantity of the currency awarded.

Date

Bases: PascalCaseModel

A date object.

Attributes:

Name	Type	Description
value	datetime	The date value.

Event

Bases: PascalCaseModel

A promotional, reward-track event contained within a CSR season.

Events were superseded by operations as of October 2023.

Attributes:

Name	Type	Description
reward_track_path	str	The relative path to the event's reward track file.
start_date	Date	The UTC start date of the event.
end_date	Date	The UTC end date of the event.

InventoryReward

Bases: PascalCaseModel

An inventory item reward, such as a weapon skin or armor piece.

Attributes:

Name	Type	Description
inventory_item_path	str	The relative path to the inventory item file.
amount	int	The quantity of the inventory item awarded.
type	str	The type of inventory item, such as "ArmorCoating".

Medal

Bases: CamelCaseModel

Metadata for a single medal.

Attributes:

Name	Type	Description
name_id	int	The medal's ID.
name	TranslatableString	The medal's name.
description	TranslatableString	The medal's description.
sprite_index	int	The index of the medal's sprite in the sprite sheet.
sorting_weight	int	The medal's sorting weight.
difficulty	MedalDifficulty	The medal's difficulty, such as "normal" or "legendary".
type	MedalType	The medal's type, such as "mode" or "proficiency".
personal_score	int	The amount of personal score awarded by obtaining the medal.

MedalMetadata

Bases: CamelCaseModel

Metadata for all medals.

Attributes:

Name	Type	Description
difficulties	tuple[str, ...]	The list of possible difficulties.
types	tuple[str, ...]	The list of possible types.
sprites	SpriteSheets	Information about the medal sprite sheets that contain medal.
medals	tuple[Medal, ...]	The list of available medals.

RankRewards

Bases: PascalCaseModel

A collection of inventory and currency rewards earned at a rank.

Attributes:

Name	Type	Description
inventory_rewards	tuple[InventoryReward, ...]	The list of inventory item rewards.
currency_rewards	tuple[CurrencyReward, ...]	The list of currency rewards.

Season

Bases: PascalCaseModel

An promotional, reward-track operation contained within a CSR season.

Attributes:

Name	Type	Description
csr_season_file_path	str	The relative path to the CSR season file. The stem of the path is the CSR season's ID, e.g., "CsrSeason5-1".
operation_track_path	str	The relative path to the operation's reward track file.
season_metadata	str	The relative path to the operation metadata file.
start_date	Date	The UTC start date of the season.
end_date	Date	The UTC end date of the season.

SeasonCalendar

Bases: PascalCaseModel

A collection of past and current reward tracks.

Attributes:

Name	Type	Description
seasons	tuple[Season, ...]	The list of "operation" reward tracks.
events	tuple[Event, ...]	The list of "event" reward tracks. Events were superseded by operations as of October 2023.
career_rank	CareerRank	Information about career rank progression.

SpriteSheet

Bases: CamelCaseModel

Information about a sprite sheet that contains medal sprites.

Attributes:

Name	Type	Description
path	str	The path to the sprite sheet, relative to the "gamecms_hacs" host.
columns	int	The number of columns in the sprite sheet.
size	int	The size of each sprite in the sprite sheet.

SpriteSheets

Bases: CamelCaseModel

Sizes of sprite sheets that contain medal sprites.

Attributes:

Name	Type	Description
small	SpriteSheet	A sprite sheet with small sprites.
medium	SpriteSheet	A sprite sheet with medium sprites.
extra_large	SpriteSheet	A sprite sheet with extra large sprites.

TranslatableString

Bases: CamelCaseModel

A string value accompanied by a dictionary of translations.

Attributes:

Name	Type	Description
value	str	The string value.
translations	ReadOnlyDict[str, str]	A dictionary of language codes to translations for the string value.

TranslatableStringWithStatus

Bases: CamelCaseModel

A string value accompanied by a dictionary of translations.

Attributes:

Name	Type	Description
status	str	The status of the attribute.
value	str	The string value.
translations	ReadOnlyDict[str, str]	A dictionary of language codes to translations for the string value.

spnkr.models.profile

Models for the "profile" authority.

GamerPicture

Bases: BaseModel

URLs to different sizes of a user's gamerpic.

Attributes:

Name	Type	Description
small	str	64x64 PNG
medium	str	208x208 PNG
large	str	424x424 PNG
xlarge	str	1080x1080 PNG

User

Bases: BaseModel

High-level information about an Xbox Live user.

Attributes:

Name	Type	Description
xuid	int	Xbox user ID.
gamertag	str	User's gamertag.
gamerpic	GamerPicture	URLs to different sizes of the user's gamerpic.

spnkr.models.skill

Models for the "skill" authority.

Counterfactual

Bases: PascalCaseModel

Expected performance for a given player or skill tier in a match.

Attributes:

Name	Type	Description
kills	float	Expected kills.
deaths	float	Expected deaths.

Counterfactuals

Bases: PascalCaseModel

Expected performances for the player and all skill tiers in a match.

Attributes:

Name	Type	Description
self_counterfactuals	Counterfactual	Expected performance for the player.
tier_counterfactuals	ReadOnlyDict[Tier, Counterfactual]	Expected performances for all skill tiers.

CsrContainer

Bases: PascalCaseModel

Container for a player's CSR info.

Attributes:

Name	Type	Description
value	int	The player's CSR value.
measurement_matches_remaining	int	The number of matches remaining until the player's CSR is determined.
tier	Tier	The player's CSR tier.
tier_start	int	The CSR value at which the player's current tier starts.
sub_tier	SubTier	The player's CSR sub-tier.
next_tier	Tier	The player's next CSR tier.
next_tier_start	int	The CSR value at which the player's next tier starts.
next_sub_tier	SubTier	The player's next CSR sub-tier.
initial_measurement_matches	int	The number of matches required to determine the player's CSR.

MatchSkill

Bases: PascalCaseModel

Summary of skill data for teams and players in a match.

Attributes:

Name	Type	Description
value	tuple[MatchSkillValue, ...]	List of player skill data entries.

MatchSkillResult

Bases: PascalCaseModel

Skill data for a player in a match.

Attributes:

Name	Type	Description
team_mmr	float	The MMR of the player's team.
rank_recap	RankRecap	Summary of the player's CSR change.
stat_performances	StatPerformances	Comparison of actual to expected values for player performance metrics.
team_id	int	The ID of the player's team.
team_mmrs	ReadOnlyDict[int, float]	The MMRs of all teams in the match.
ranked_rewards	RankedRewards | None	Always null.
counterfactuals	Counterfactuals	Expected performances for the player and all skill tiers in a match.

MatchSkillValue

Bases: PascalCaseModel

Skill data for a player in a match.

Attributes:

Name	Type	Description
id	str	The player's Xbox Live ID.
result_code	SkillResultCode	The status of the skill result.
result	MatchSkillResult	Skill data for a player in a match.

PlaylistCsr

Bases: PascalCaseModel

Summary of CSR data for players in a playlist.

Attributes:

Name	Type	Description
value	tuple[PlaylistCsrValue, ...]	List of playlist-player CSR entries.

PlaylistCsrResult

Bases: PascalCaseModel

CSR details for a player in a playlist.

Attributes:

Name	Type	Description
current	CsrContainer	Details on the player's current CSR in the playlist.
season_max	CsrContainer	Details on the player's highest CSR in the playlist for the season.
all_time_max	CsrContainer	Details on the player's highest CSR in the playlist for all seasons.

PlaylistCsrValue

Bases: PascalCaseModel

Playlist CSR result for a single player.

Attributes:

Name	Type	Description
id	str	The player's Xbox Live ID.
result_code	SkillResultCode	The status of the skill result.
result	PlaylistCsrResult	CSR details for a player in a playlist.

RankRecap

Bases: PascalCaseModel

Summary of the player's CSR change.

Attributes:

Name	Type	Description
pre_match_csr	CsrContainer	The player's CSR details before the match.
post_match_csr	CsrContainer	The player's CSR details after the match.

RankedRewards

Bases: PascalCaseModel

Rewards awarded to players based on skill acheivement.

Attributes:

Name	Type	Description
reward_id	UUID	The ID of the player's reward.

StatPerformance

Bases: PascalCaseModel

Comparison of actual to expected values for a game metric.

Attributes:

Name	Type	Description
count	int	The actual value.
expected	float	The expected value.
std_dev	float	The standard deviation between actual and expected values.

StatPerformances

Bases: PascalCaseModel

Comparison of actual to expected values for game metrics.

Attributes:

Name	Type	Description
kills	StatPerformance	Comparison of actual to expected kills.
deaths	StatPerformance	Comparison of actual to expected deaths.

spnkr.models.stats

Models for the stats authority.

Asset

Bases: PascalCaseModel

ID information about a game asset, such as a map or game mode.

Attributes:

Name	Type	Description
asset_kind	AssetKind	The kind of asset, such as "map variant" or "playlist".
asset_id	UUID	The asset's GUID.
version_id	UUID	The asset version's GUID.

AwardCount

Bases: PascalCaseModel

A count of a medal or personal score award.

Attributes:

Name	Type	Description
name_id	int	The ID of the medal or personal score award.
count	int	The number of times the medal or personal score award was earned.
total_personal_score_awarded	int	The total personal score awarded by obtaining the medal or personal score award.

BombStats

Bases: PascalCaseModel

Performance statistics for bomb game modes.

Attributes:

Name	Type	Description
bomb_carriers_killed	int	Number of times an enemy bomb carrier was killed.
bomb_defusals	int	Number of times a bomb was defused.
bomb_defusers_killed	int	Number of times an enemy bomb defuser was killed.
bomb_detonations	int	Number of times a bomb was detonated.
bomb_pick_ups	int	Number of times a bomb was picked up.
bomb_plants	int	Number of times a bomb was planted.
bomb_returns	int	Number of times a bomb was returned.
kills_as_bomb_carrier	int	Number of kills while carrying the bomb.
time_as_bomb_carrier	timedelta	Total time spent carrying the bomb.

BotAttributes

Bases: PascalCaseModel

Attributes of a bot player.

Attributes:

Name	Type	Description
difficulty	BotDifficulty	The bot's difficulty.

CaptureTheFlagStats

Bases: PascalCaseModel

Performance statistics for capture the flag game modes.

Attributes:

Name	Type	Description
flag_capture_assists	int	Number of times contributing to a flag capture.
flag_captures	int	Number of times the enemy flag was captured.
flag_carriers_killed	int	Number of times an enemy flag carrier was killed.
flag_grabs	int	Number of times the enemy flag was grabbed.
flag_returners_killed	int	Number of times an enemy flag returner was killed.
flag_returns	int	Number of times the team flag was returned.
flag_secures	int	Number of times the team flag was secured.
flag_steals	int	Number of times stealing a flag.
kills_as_flag_carrier	int	Number of kills while carrying the flag.
kills_as_flag_returner	int	Number of kills while returning the flag.
time_as_flag_carrier	timedelta	Total time spent carrying the flag.

CoreStats

Bases: _CoreStats

Core statistics about a player or team performance in a match.

Attributes:

Name	Type	Description
score		Earned points related to the match outcome.
personal_score		Earned points related to personal performance.
rounds_won		The number of rounds won.
rounds_lost		The number of rounds lost.
rounds_tied		The number of rounds tied.
kills		The number of kills.
deaths		The number of deaths.
assists		The number of assists.
kda	float	Kill-death-assist metric (kills + assists / 3 - deaths).
suicides	float	The number of suicides.
betrayals	float	The number of betrayals.
average_life_duration	timedelta	The average time between deaths.
grenade_kills	timedelta	The number of kills using grenades.
headshot_kills	timedelta	The number of kills with headshots.
melee_kills	timedelta	The number of kills with melee or a melee weapon.
power_weapon_kills	timedelta	The number of kills with "power" weapons.
shots_fired	timedelta	The number of shots fired with weapons.
shots_hit	timedelta	The number of shots hit with weapons.
accuracy	timedelta	The accuracy of shots fired (shots_fired / shots_hit * 100).
damage_dealt	timedelta	The amount of damage dealt.
damage_taken	timedelta	The amount of damage taken.
callout_assists	timedelta	The number of assists earned by "marking" an enemy.
vehicle_destroys	timedelta	The number of vehicles destroyed.
driver_assists	timedelta	The number of assists earned by driving a teammate that gets a kill.
hijacks	timedelta	The number of times hijacking a vehicle.
emp_assists	timedelta	The number of assists earned by EMPing an enemy player or vehicle.
max_killing_spree	timedelta	The maximum number of kills without dying.
medals	timedelta	Medals earned.
personal_scores	timedelta	Personal score awards earned.
spawns	timedelta	The number of times spawned.

EliminationStats

Bases: _EliminationStats

Performance statistics for elimination game modes.

Attributes:

Name	Type	Description
allies_revived		Number of times reviving a teammate.
elimination_assists		Number of times contributing to an elimination.
eliminations		Number of times eliminating an enemy.
enemy_revives_denied		Number of times denying an enemy revive.
executions		Number of times executing an enemy.
kills_as_last_player_standing		Number of kills as the last player standing.
last_players_standing_killed		Number of times killing the last player standing.
rounds_survived		Number of rounds survived.
times_revived_by_ally		Number of times revived by a teammate.
lives_remaining	int | None	Number of lives remaining.
elimination_order	int	The order eliminated.

ExtractionStats

Bases: PascalCaseModel

Performance statistics for extraction game modes.

Attributes:

Name	Type	Description
extraction_conversions_completed	int	Number of times converting an extraction zone.
extraction_conversions_denied	int	Number of times denying an enemy extraction zone conversion.
extraction_initiations_completed	int	Number of times initiating an extraction zone.
extraction_initiations_denied	int	Number of times denying an enemy extraction zone initiation.
successful_extractions	int	Number of times extracting a zone.

InfectionStats

Bases: PascalCaseModel

Performance statistics for infection game modes.

Attributes:

Name	Type	Description
alphas_killed	int	Number of times infecting an alpha zombie.
spartans_infected	int	Number of times infecting a spartan.
spartans_infected_as_alpha	int	Number of times infecting a spartan as an alpha zombie.
kills_as_last_spartan_standing	int	Number of kills as the last spartan standing.
last_spartans_standing_infected	int	Number of times infecting the last spartan standing.
rounds_as_alpha	int	Number of rounds as an alpha zombie.
rounds_as_last_spartan_standing	int	Number of rounds as the last spartan standing.
rounds_finished_as_infected	int	Number of rounds finished as an infected.
rounds_survived_as_spartan	int	Number of rounds survived as a spartan.
rounds_survived_as_last_spartan_standing	int	Number of rounds survived as the last spartan standing.
time_as_last_spartan_standing	timedelta	Total time spent as the last spartan standing.
infected_killed	int	Number of times killing an infected.

MatchCount

Bases: PascalCaseModel

A player's match count summary.

Attributes:

Name	Type	Description
custom_matches_played_count	int	The number of custom matches the player has played.
matches_played_count	int	The number of matches the player has played.
matchmade_matches_played_count	int	The number of matchmade matches the player has played.
local_matches_played_count	int	The number of local matches the player has played.

MatchHistory

Bases: PascalCaseModel

A page of a player's match history.

Attributes:

Name	Type	Description
start	int	The index of the first match in the page. 0 is the most recent match.
count	int	The number of matches requested.
result_count	int	The actual number of matches in the page.
results	tuple[MatchHistoryResult, ...]	The matches in the page.

MatchHistoryResult

Bases: PascalCaseModel

A match history entry.

Attributes:

Name	Type	Description
match_id	UUID	The match's GUID.
match_info	MatchInfo	Information about the match.
last_team_id	int	The ID of the last team the player was on.
outcome	Outcome	The player's outcome in the match.
rank	int	The player's rank in the match.
present_at_end_of_match	bool	Whether the player was present at the end of the match.

MatchInfo

Bases: PascalCaseModel

Information about a match.

Attributes:

Name	Type	Description
start_time	datetime	The UTC datetime when the match started.
end_time	datetime	The UTC datetime when the match ended.
duration	timedelta	The match's duration.
lifecycle_mode	LifecycleMode	The match's lifecycle mode.
game_variant_category	GameVariantCategory	The game mode category.
level_id	UUID	The ID of the level the match was played on.
map_variant	Asset	The map the match was played on.
ugc_game_variant	Asset	The game mode the match was played with.
clearance_id	UUID	Clearance ID.
playlist	Asset | None	The playlist the match was made in, if the match was matchmade.
playlist_experience	PlaylistExperience | None	The general category of playlist the match was made in, if the match was matchmade.
playlist_map_mode_pair	Asset | None	The map and game mode the match was made in, if the match was matchmade.
season_id	str | None	The ID of the season the match was played in, if the match was matchmade.
playable_duration	timedelta	The match's playable duration.
teams_enabled	bool	Whether teams were enabled in the match.
team_scoring_enabled	bool	Whether team scoring was enabled in the match.

MatchStats

Bases: PascalCaseModel

Player and team performance details for a match.

Attributes:

Name	Type	Description
match_id	UUID	The match's GUID.
match_info	MatchInfo	Information about the match.
teams	tuple[TeamStats, ...]	Performance statistics for all teams in the match.
players	tuple[PlayerStats, ...]	Performance statistics for all players in the match.

OddballStats

Bases: PascalCaseModel

Performance statistics for oddball game modes.

Attributes:

Name	Type	Description
kills_as_skull_carrier	int	Number of kills while carrying the skull.
longest_time_as_skull_carrier	timedelta	Longest time spent carrying the skull.
skull_carriers_killed	int	Number of times an enemy skull carrier was killed.
skull_grabs	int	Number of times the skull was grabbed.
time_as_skull_carrier	timedelta	Total time spent carrying the skull.
skull_scoring_ticks	int	Number of ticks the skull was held.

ParticipationInfo

Bases: PascalCaseModel

Information about a player's participation in a match.

Attributes:

Name	Type	Description
first_joined_time	datetime	The UTC datetime when the player first joined the match.
last_leave_time	datetime | None	The UTC datetime when the player last left the match, if the player left the match.
present_at_beginning	bool	Whether the player was present at the beginning of the match.
joined_in_progress	bool	Whether the player joined the match in progress.
left_in_progress	bool	Whether the player left the match in progress.
present_at_completion	bool	Whether the player was present at the completion of the match.
time_played	timedelta	The amount of time the player was present in the match.
confirmed_participation	bool | None	Whether the player's participation was confirmed.

PlayerStats

Bases: PascalCaseModel

Statistics for a player in a match.

Attributes:

Name	Type	Description
player_id	str	The player's Xbox Live ID.
player_type	PlayerType	The player's type, such as "human" or "bot".
bot_attributes	BotAttributes | None	Details about bot players, if applicable.
last_team_id	int	The ID of the last team the player was on.
outcome	Outcome	The player's outcome in the match.
rank	int	The player's rank in the match.
participation_info	ParticipationInfo	Information about the player's participation in the match.
player_team_stats	tuple[PlayerTeamStats, ...]	The player's performance statistics for each team they were on during the match.

is_human: bool property

Whether the player is a human player.

PlayerTeamStats

Bases: PascalCaseModel

Statistics for a player on a team in a match.

Attributes:

Name	Type	Description
team_id	int	The team's ID.
stats	Stats	The player's performance statistics while on the team.

ServiceRecord

Bases: PascalCaseModel

A player's service record within a given context.

Attributes:

Name	Type	Description
subqueries	ServiceRecordSubqueries	Subquerying options for the service record request.
time_played	timedelta	The player's total time played.
matches_completed	int	The number of matches the player has completed.
wins	int	The number of matches the player has won.
losses	int	The number of matches the player has lost.
ties	int	The number of matches the player has tied.
core_stats	ServiceRecordCoreStats	The player's core performance statistics.
bomb_stats	BombStats | None	The player's performance statistics for bomb game modes.
capture_the_flag_stats	CaptureTheFlagStats | None	The player's performance statistics for capture the flag game modes.
elimination_stats	ServiceRecordEliminationStats | None	The player's performance statistics for elimination game modes.
infection_stats	InfectionStats | None	The player's performance statistics for infection game modes.
oddball_stats	OddballStats | None	The player's performance statistics for oddball game modes.
zones_stats	ServiceRecordZonesStats | None	The player's performance statistics for zones game modes.
stockpile_stats	StockpileStats | None	The player's performance statistics for stockpile game modes.

ServiceRecordCoreStats

Bases: _CoreStats

Core statistics about a player or team performance in a match.

Attributes:

Name	Type	Description
score		Earned points related to the match outcome.
personal_score		Earned points related to personal performance.
rounds_won		The number of rounds won.
rounds_lost		The number of rounds lost.
rounds_tied		The number of rounds tied.
kills		The number of kills.
deaths		The number of deaths.
assists		The number of assists.
average_kda	float	Kill-death-assist metric (kills + assists / 3 - deaths).
suicides	float	The number of suicides.
betrayals	float	The number of betrayals.
grenade_kills	float	The number of kills using grenades.
headshot_kills	float	The number of kills with headshots.
melee_kills	float	The number of kills with melee or a melee weapon.
power_weapon_kills	float	The number of kills with "power" weapons.
shots_fired	float	The number of shots fired with weapons.
shots_hit	float	The number of shots hit with weapons.
accuracy	float	The accuracy of shots fired (shots_fired / shots_hit * 100).
damage_dealt	float	The amount of damage dealt.
damage_taken	float	The amount of damage taken.
callout_assists	float	The number of assists earned by "marking" an enemy.
vehicle_destroys	float	The number of vehicles destroyed.
driver_assists	float	The number of assists earned by driving a teammate that gets a kill.
hijacks	float	The number of times hijacking a vehicle.
emp_assists	float	The number of assists earned by EMPing an enemy player or vehicle.
max_killing_spree	float	The maximum number of kills without dying.
medals	float	Medals earned.
personal_scores	float	Personal score awards earned.
spawns	float	The number of times spawned.

ServiceRecordEliminationStats

Bases: _EliminationStats

Performance statistics for elimination game modes.

Attributes:

Name	Type	Description
allies_revived		Number of times reviving a teammate.
elimination_assists		Number of times contributing to an elimination.
eliminations		Number of times eliminating an enemy.
enemy_revives_denied		Number of times denying an enemy revive.
executions		Number of times executing an enemy.
kills_as_last_player_standing		Number of kills as the last player standing.
last_players_standing_killed		Number of times killing the last player standing.
rounds_survived		Number of rounds survived.
times_revived_by_ally		Number of times revived by a teammate.

ServiceRecordSubqueries

Bases: PascalCaseModel

Subqueries for a service record request.

Attributes:

Name	Type	Description
season_ids	tuple[str, ...] | None	Seasons available for filtering.
game_variant_categories	tuple[GameVariantCategory, ...] | None	Game variant categories available for filtering.
is_ranked	tuple[bool, ...] | None	Ranked status available for filtering.
playlist_asset_ids	tuple[UUID, ...] | None	Playlists available for filtering.

ServiceRecordZonesStats

Bases: PascalCaseModel

Performance statistics for zones game modes.

Attributes:

Name	Type	Description
zone_captures	int	Number of times capturing a zone.
zone_defensive_kills	int	Number of kills defending a zone.
zone_offensive_kills	int	Number of kills attacking a zone.
zone_secures	int	Number of times securing a zone.
total_zone_occupation_time	timedelta	Total time spent in a zone.
zone_scoring_ticks	int	Number of ticks a zone was held.

Stats

Bases: PascalCaseModel

Performance statistics for a player or team in a match.

Attributes:

Name	Type	Description
core_stats	CoreStats	Performance statistics common to all game modes.
bomb_stats	BombStats | None	Performance statistics for bomb game modes.
capture_the_flag_stats	CaptureTheFlagStats | None	Performance statistics for capture the flag game modes.
elimination_stats	EliminationStats | None	Performance statistics for elimination game modes.
extraction_stats	ExtractionStats | None	Performance statistics for extraction game modes.
infection_stats	InfectionStats | None	Performance statistics for infection game modes.
oddball_stats	OddballStats | None	Performance statistics for oddball game modes.
zones_stats	ZonesStats | None	Performance statistics for zones game modes.
stockpile_stats	StockpileStats | None	Performance statistics for stockpile game modes.

StockpileStats

Bases: PascalCaseModel

Performance statistics for stockpile game modes.

Attributes:

Name	Type	Description
kills_as_power_seed_carrier	int	Number of kills while carrying a power seed.
power_seeds_deposited	int	Number of power seeds deposited.
power_seeds_stolen	int	Number of power seeds stolen.
power_seed_carriers_killed	int	Number of times an enemy power seed carrier was killed.
time_as_power_seed_carrier	timedelta	Total time spent carrying a power seed.
time_as_power_seed_driver	timedelta	Total time spent driving a power seed.

TeamStats

Bases: PascalCaseModel

Statistics for a team in a match.

Attributes:

Name	Type	Description
team_id	int	The team's ID.
outcome	Outcome	The team's outcome in the match.
rank	int	The team's rank in the match.
stats	Stats	The team's performance statistics.

ZonesStats

Bases: PascalCaseModel

Performance statistics for zones game modes.

Attributes:

Name	Type	Description
stronghold_captures	int	Number of times capturing a stronghold.
stronghold_defensive_kills	int	Number of kills defending a stronghold.
stronghold_offensive_kills	int	Number of kills attacking a stronghold.
stronghold_secures	int	Number of times securing a stronghold.
stronghold_occupation_time	timedelta	Total time spent in a stronghold.
stronghold_scoring_ticks	int	Number of ticks a stronghold was held.