class valaw.Client(token: str, cluster: str, raw_data: bool = False)

The client that connects to the Riot Games API.

  • token (str) – A Riot Games API access token used to authenticate requests.

  • cluster (str) – The default cluster to use in requests. The nearest cluster to the host computer/server should be selected.

  • raw_data – Whether or not to send raw JSON data or not. If False, Riot Games API requests will return an object. Defaults to False.

async GET_getActiveShard(puuid: str, cluster: str = None) ActiveShardDto | Dict

Get active shard for a player.

  • puuid (str) – The PUUID of the account.

  • cluster (str) – The cluster to retreive from. Defaults to self.cluster.

Return type:

Union[ActiveShardDto, Dict]

async GET_getByAccessToken(authorization: str, cluster: str = None) AccountDto | Dict

Get account by access token.

  • authorization (str) – The access token.

  • cluster (str) – The cluster to retreive from. Defaults to self.cluster.

Return type:

Union[AccountDto, Dict]

async GET_getByPuuid(puuid: str, cluster: str = None) AccountDto | Dict

Get account by PUUID.

  • puuid (str) – The PUUID of the account.

  • cluster (str) – The cluster to retreive from. Defaults to self.cluster.

Return type:

Union[AccountDto, Dict]

async GET_getByRiotId(gameName: str, tagLine: str, cluster: str = None) AccountDto | Dict

Get account by Riot ID.

  • gameName (str) – The game name of the account (gameName#tagLine).

  • tagLine (str) – The tag line of the account (gameName#tagLine).

  • cluster (str) – The cluster to retreive from. Defaults to self.cluster.

Return type:

Union[AccountDto, Dict]

async GET_getContent(region: str, locale: str = '') ContentDto | Dict

Get content optionally filtered by locale. A locale is recommended to be used for faster response times.

  • region (str) – The region to execute against.

  • locale (str) – The locale to retrieve data for, defaults to “”.

Return type:

Union[ContentDto, Dict]

async GET_getLeaderboard(actId: str, region: str, size: int = 200, startIndex: int = 0) LeaderboardDto | Dict

Get leaderboard for the competitive queue.

  • actId (str) – The act id.

  • region (str) – The region to execute against.

  • size (int) – The amount of entries to retrieve, defaults to 200.

  • startIndex (int) – The index to start from, defaults to 0.

Return type:

Union[LeaderboardDto, Dict]

async GET_getMatch(matchId: str, region: str) MatchDto | Dict

Get match by id.

  • matchId (str) – The match id.

  • region (str) – The region to execute against.

Return type:

Union[MatchDto, Dict]

async GET_getMatchlist(puuid: str, region: str) MatchlistDto | Dict

Get matchlist for games played by puuid.

  • puuid (str) – The PUUID of the account.

  • region (str) – The region to execute against.

Return type:

Union[MatchlistDto, Dict]

async GET_getPlatformData(region: str) PlatformDataDto | Dict

Get VALORANT status for the given platform.


region (str) – The region to execute against.

Return type:

Union[PlatformDataDto, Dict]

async GET_getRecent(queue: str, region: str) RecentMatchesDto | Dict

Get recent matches.

Returns a list of match ids that have completed in the last 10 minutes for live regions and 12 hours for the esports routing value. NA/LATAM/BR share a match history deployment. As such, recent matches will return a combined list of matches from those three regions. Requests are load balanced so you may see some inconsistencies as matches are added/removed from the list.

  • queue (str) – The queue to retrieve recent matches for.

  • region (str) – The region to execute against.

Return type:

Union[RecentMatchesDto, Dict]

change_cluster(cluster: str)

Change the cluster.

change_raw_data(raw_data: bool)

Change the raw_data.

create_RSO_link(redirect_uri: str, client_id: str, response_type: str, scopes: List[str], login_hint: str = None, ui_locales: List[str] = None, state: str = None)

Create a Riot Sign-On Link.

  • redirect_uri (str) – OAuth2 callback route

  • client_id (str) – Client ID of the RSO application

  • response_type (str) – OAuth2 response type, should be ‘code’ for authorization code flow

  • scopes (List[str]) – List of scopes to request, must include ‘openid’ to authenticate, addition scopes are ‘cpid’, and ‘offline_access’

  • login_hint (str) – Used to specify hints to pre-populate data on the login page. Formats {regioncode}, {regioncode}|{username}, {regioncode}#{userid}. Defaults to None

  • ui_locales (List[str]) – List of BCP47 language tag values in order of most to least preferred. Defaults to None

  • state (str) – Opaque value provided to authorize the endpoint, the same value will be returned to the redirect_uri. Defaults to None



For more information on RSO, visit


class valaw.Exceptions
exception FailedToParseJSON

Failed to parse JSON.

exception InvalidCluster

Invalid Cluster.

Valid clusters are: americas, asia, esports, europe.

exception InvalidRegion

Invalid Region.

Valid regions are: ap, br, esports, eu, kr, latam, na.

exception RiotAPIResponseError(status_code: int, status_message: str)

Riot API Response Error.

More information about response errors can be found at:


More information about response codes and other exceptions can be found here.


class valaw.objects.AbilityCastsDto(grenadeCasts: int, ability1Casts: int, ability2Casts: int, ultimateCasts: int)
ability1Casts: int
ability2Casts: int
grenadeCasts: int
ultimateCasts: int
class valaw.objects.AbilityDto(grenadeEffects: str, ability1Effects: str, ability2Effects: str, ultimateEffects: str)
ability1Effects: str
ability2Effects: str
grenadeEffects: str
ultimateEffects: str
class valaw.objects.AccountDto(puuid: str, gameName: str | None = None, tagLine: str | None = None)
gameName: str | None = None
puuid: str
tagLine: str | None = None
class valaw.objects.ActDto(name: str, id: str, isActive: bool, type: str, localizedNames: valaw.objects.content.LocalizedNamesDto | None = None, parentId: str | None = None)
id: str
isActive: bool
localizedNames: LocalizedNamesDto | None = None
name: str
parentId: str | None = None
type: str
class valaw.objects.ActiveShardDto(puuid: str, game: str, activeShard: str)
activeShard: str
game: str
puuid: str
class valaw.objects.CoachDto(puuid: str, teamId: str)
puuid: str
teamId: str
class valaw.objects.ContentDto(version: str, characters: List[valaw.objects.content.ContentItemDto], maps: List[valaw.objects.content.ContentItemDto], chromas: List[valaw.objects.content.ContentItemDto], skins: List[valaw.objects.content.ContentItemDto], skinLevels: List[valaw.objects.content.ContentItemDto], equips: List[valaw.objects.content.ContentItemDto], gameModes: List[valaw.objects.content.ContentItemDto], sprays: List[valaw.objects.content.ContentItemDto], sprayLevels: List[valaw.objects.content.ContentItemDto], charms: List[valaw.objects.content.ContentItemDto], charmLevels: List[valaw.objects.content.ContentItemDto], playerCards: List[valaw.objects.content.ContentItemDto], playerTitles: List[valaw.objects.content.ContentItemDto], acts: List[valaw.objects.content.ActDto])
acts: List[ActDto]
characters: List[ContentItemDto]
charmLevels: List[ContentItemDto]
charms: List[ContentItemDto]
chromas: List[ContentItemDto]
equips: List[ContentItemDto]
gameModes: List[ContentItemDto]
maps: List[ContentItemDto]
playerCards: List[ContentItemDto]
playerTitles: List[ContentItemDto]
skinLevels: List[ContentItemDto]
skins: List[ContentItemDto]
sprayLevels: List[ContentItemDto]
sprays: List[ContentItemDto]
version: str
class valaw.objects.ContentItemDto(name: str, id: str, assetName: str, localizedNames: valaw.objects.content.LocalizedNamesDto | None = None, assetPath: str | None = None)
assetName: str
assetPath: str | None = None
id: str
localizedNames: LocalizedNamesDto | None = None
name: str
class valaw.objects.DamageDto(receiver: str, damage: int, legshots: int, bodyshots: int, headshots: int)
bodyshots: int
damage: int
headshots: int
legshots: int
receiver: str
class valaw.objects.EconomyDto(loadoutValue: int, weapon: str, armor: str, remaining: int, spent: int)
armor: str
loadoutValue: int
remaining: int
spent: int
weapon: str
class valaw.objects.FinishingDamageDto(damageType: str, damageItem: str, isSecondaryFireMode: bool)
damageItem: str
damageType: str
isSecondaryFireMode: bool
class valaw.objects.KillDto(timeSinceGameStartMillis: int, timeSinceRoundStartMillis: int, killer: str, victim: str, victimLocation: valaw.objects.match.LocationDto, assistants: List[str] | None, playerLocations: List[valaw.objects.match.PlayerLocationsDto], finishingDamage: valaw.objects.match.FinishingDamageDto)
assistants: List[str] | None
finishingDamage: FinishingDamageDto
killer: str
playerLocations: List[PlayerLocationsDto]
timeSinceGameStartMillis: int
timeSinceRoundStartMillis: int
victim: str
victimLocation: LocationDto
class valaw.objects.LeaderboardDto(actId: str, players: List[valaw.objects.ranked.PlayerDto], totalPlayers: int, immortalStartingPage: int, immortalStartingIndex: int, topTierRRThreshold: int, tierDetails: dict, startIndex: int, shard: str, query: str | None)
actId: str
immortalStartingIndex: int
immortalStartingPage: int
players: List[PlayerDto]
query: str | None
shard: str
startIndex: int
tierDetails: dict
topTierRRThreshold: int
totalPlayers: int
class valaw.objects.LocalizedNamesDto(ar_AE: str, de_DE: str, en_GB: str, en_US: str, es_ES: str, es_MX: str, fr_FR: str, id_ID: str, it_IT: str, ja_JP: str, ko_KR: str, pl_PL: str, pt_BR: str, ru_RU: str, th_TH: str, tr_TR: str, vi_VN: str, zh_CN: str, zh_TW: str)
ar_AE: str
de_DE: str
en_GB: str
en_US: str
es_ES: str
es_MX: str
fr_FR: str
id_ID: str
it_IT: str
ja_JP: str
ko_KR: str
pl_PL: str
pt_BR: str
ru_RU: str
th_TH: str
tr_TR: str
vi_VN: str
zh_CN: str
zh_TW: str
class valaw.objects.LocationDto(x: int, y: int)
x: int
y: int
class valaw.objects.MatchDto(matchInfo: valaw.objects.match.MatchInfoDto, players: List[valaw.objects.match.PlayerDto], coaches: List[valaw.objects.match.CoachDto], teams: List[valaw.objects.match.TeamDto], roundResults: List[valaw.objects.match.RoundResultDto])
coaches: List[CoachDto]
matchInfo: MatchInfoDto
players: List[PlayerDto]
roundResults: List[RoundResultDto]
teams: List[TeamDto]
class valaw.objects.MatchInfoDto(matchId: str, mapId: str, gameLengthMillis: int, gameStartMillis: int, provisioningFlowId: str, isCompleted: bool, customGameName: str, queueId: str, gameMode: str, isRanked: bool, seasonId: str)
customGameName: str
gameLengthMillis: int
gameMode: str
gameStartMillis: int
isCompleted: bool
isRanked: bool
mapId: str
matchId: str
provisioningFlowId: str
queueId: str
seasonId: str
class valaw.objects.MatchlistDto(puuid: str, history: List[valaw.objects.match.MatchlistEntryDto])
history: List[MatchlistEntryDto]
puuid: str
class valaw.objects.MatchlistEntryDto(matchId: str, gameStartTimeMillis: int, queueId: str)
gameStartTimeMillis: int
matchId: str
queueId: str
class valaw.objects.PlatformDataDto(id: str, name: str, locales: List[str], maintenances: List[valaw.objects.status.StatusDto], incidents: List[valaw.objects.status.StatusDto])
id: str
incidents: List[StatusDto]
locales: List[str]
maintenances: List[StatusDto]
name: str
class valaw.objects.PlayerDto(leaderboardRank: int, rankedRating: int, numberOfWins: int, competitiveTier: int, puuid: str = '', gameName: str = 'Private', tagLine: str = '')
competitiveTier: int
gameName: str = 'Private'
leaderboardRank: int
numberOfWins: int
puuid: str = ''
rankedRating: int
tagLine: str = ''
class valaw.objects.PlayerLocationsDto(puuid: str, viewRadians: float, location: valaw.objects.match.LocationDto)
location: LocationDto
puuid: str
viewRadians: float
class valaw.objects.PlayerRoundStatsDto(puuid: str, kills: List[valaw.objects.match.KillDto], damage: List[valaw.objects.match.DamageDto], score: int, economy: valaw.objects.match.EconomyDto, ability: valaw.objects.match.AbilityDto)
ability: AbilityDto
damage: List[DamageDto]
economy: EconomyDto
kills: List[KillDto]
puuid: str
score: int
class valaw.objects.PlayerStatsDto(score: int, roundsPlayed: int, kills: int, deaths: int, assists: int, playtimeMillis: int, abilityCasts: valaw.objects.match.AbilityCastsDto)
abilityCasts: AbilityCastsDto
assists: int
deaths: int
kills: int
playtimeMillis: int
roundsPlayed: int
score: int
class valaw.objects.RecentMatchesDto(currentTime: int, matchIds: List[str])
currentTime: int
matchIds: List[str]
class valaw.objects.RoundResultDto(roundNum: int, roundResult: str, roundCeremony: str, winningTeam: str, bombPlanter: str | None, bombDefuser: str | None, plantRoundTime: int | None, plantPlayerLocations: List[valaw.objects.match.PlayerLocationsDto] | None, plantLocation: valaw.objects.match.LocationDto | None, plantSite: str | None, defuseRoundTime: int | None, defusePlayerLocations: List[valaw.objects.match.PlayerLocationsDto] | None, defuseLocation: valaw.objects.match.LocationDto | None, playerStats: List[valaw.objects.match.PlayerRoundStatsDto], roundResultCode: str)
bombDefuser: str | None
bombPlanter: str | None
defuseLocation: LocationDto | None
defusePlayerLocations: List[PlayerLocationsDto] | None
defuseRoundTime: int | None
plantLocation: LocationDto | None
plantPlayerLocations: List[PlayerLocationsDto] | None
plantRoundTime: int | None
plantSite: str | None
playerStats: List[PlayerRoundStatsDto]
roundCeremony: str
roundNum: int
roundResult: str
roundResultCode: str
winningTeam: str
class valaw.objects.StatusDto(id: int, maintenance_status: str, incident_severity: str, titles: List[valaw.objects.status.ContentDto], updates: List[valaw.objects.status.UpdateDto], created_at: str, updated_at: str, platforms: List[str], archived_at: str | None = None)
archived_at: str | None = None
created_at: str
id: int
incident_severity: str
maintenance_status: str
platforms: List[str]
titles: List[ContentDto]
updated_at: str
updates: List[UpdateDto]
class valaw.objects.TeamDto(teamId: str, won: bool, roundsPlayed: int, roundsWon: int, numPoints: int)
numPoints: int
roundsPlayed: int
roundsWon: int
teamId: str
won: bool
class valaw.objects.UpdateDto(id: int, author: str, publish: bool, publish_locations: List[str], created_at: str, updated_at: str)
author: str
created_at: str
id: int
publish: bool
publish_locations: List[str]
updated_at: str