# Get Active Shard
Source: https://valaw.madebyjet.dev/api-reference/account/get-active-shard
Retrieve the active game shard for a player
## GET\_getActiveShard
```python theme={null}
await client.GET_getActiveShard(puuid, cluster=None)
```
Get the active shard (region) where a player is currently playing VALORANT. Use this to determine which region to query for match history and other player data.
| Parameter | Type | Description |
| --------- | --------------- | ------------------------------------------------------------------------------------ |
| `puuid` | `str` | The player's PUUID |
| `cluster` | `str`, optional | Overrides the default cluster. Valid values: `americas`, `asia`, `esports`, `europe` |
**Returns:** [`ActiveShardDto`](/api-reference/objects/account-objects#activesharddto) or `dict`
**Raises:** [`InvalidCluster`](/api-reference/exceptions#invalidcluster), [`RiotAPIResponseError`](/api-reference/exceptions#riotapiresponseerror)
***
## Example
```python theme={null}
import valaw
import asyncio
async def main():
client = valaw.Client("YOUR_TOKEN", "americas")
try:
account = await client.GET_getByRiotId("PlayerName", "NA1")
shard = await client.GET_getActiveShard(account.puuid)
# Use the active shard as the region for match queries
matches = await client.GET_getMatchlist(account.puuid, shard.activeShard)
print(f"Found {len(matches.history)} matches in {shard.activeShard}")
finally:
await client.close()
asyncio.run(main())
```
Always query the active shard before fetching match history — using the wrong region returns a 404 error.
# Get Account by Access Token
Source: https://valaw.madebyjet.dev/api-reference/account/get-by-access-token
Retrieve account information for the authenticated user using an RSO access token
## GET\_getByAccessToken
```python theme={null}
await client.GET_getByAccessToken(authorization, cluster=None)
```
Get the account associated with an RSO (Riot Sign-On) access token. Use this after completing the OAuth2 flow via [`create_RSO_link`](/api-reference/rso/create-rso-link).
| Parameter | Type | Description |
| --------------- | --------------- | ------------------------------------------------------------------------------------ |
| `authorization` | `str` | The RSO access token |
| `cluster` | `str`, optional | Overrides the default cluster. Valid values: `americas`, `asia`, `esports`, `europe` |
**Returns:** [`AccountDto`](/api-reference/objects/account-objects#accountdto) or `dict`
**Raises:** [`InvalidCluster`](/api-reference/exceptions#invalidcluster), [`RiotAPIResponseError`](/api-reference/exceptions#riotapiresponseerror)
***
## Example
```python theme={null}
import valaw
import asyncio
async def main():
client = valaw.Client("YOUR_TOKEN", "americas")
try:
# access_token comes from your OAuth2 callback handler
access_token = "Bearer "
account = await client.GET_getByAccessToken(access_token)
print(f"Authenticated as: {account.gameName}#{account.tagLine}")
finally:
await client.close()
asyncio.run(main())
```
Never expose access tokens in client-side code or logs. Always transmit tokens over HTTPS.
# Get Account by PUUID
Source: https://valaw.madebyjet.dev/api-reference/account/get-by-puuid
Retrieve account information using a player's PUUID
## GET\_getByPuuid
```python theme={null}
await client.GET_getByPuuid(puuid, cluster=None)
```
Get an account by PUUID (Player Universally Unique Identifier).
| Parameter | Type | Description |
| --------- | --------------- | ------------------------------------------------------------------------------------ |
| `puuid` | `str` | The player's PUUID |
| `cluster` | `str`, optional | Overrides the default cluster. Valid values: `americas`, `asia`, `esports`, `europe` |
**Returns:** [`AccountDto`](/api-reference/objects/account-objects#accountdto) or `dict`
**Raises:** [`InvalidCluster`](/api-reference/exceptions#invalidcluster), [`RiotAPIResponseError`](/api-reference/exceptions#riotapiresponseerror)
***
## Example
```python theme={null}
import valaw
import asyncio
async def main():
client = valaw.Client("YOUR_TOKEN", "americas")
try:
account = await client.GET_getByPuuid("player-puuid-here")
print(f"{account.gameName}#{account.tagLine}")
finally:
await client.close()
asyncio.run(main())
```
The PUUID is a persistent identifier that stays the same even if a player changes their Riot ID.
# Get Account by Riot ID
Source: https://valaw.madebyjet.dev/api-reference/account/get-by-riot-id
Retrieve account information using a player's Riot ID (gameName#tagLine)
## GET\_getByRiotId
```python theme={null}
await client.GET_getByRiotId(gameName, tagLine, cluster=None)
```
Get an account by Riot ID. The Riot ID is the player's display name in the format `gameName#tagLine`.
| Parameter | Type | Description |
| ---------- | --------------- | ------------------------------------------------------------------------------------ |
| `gameName` | `str` | The game name (left of `#`) |
| `tagLine` | `str` | The tag line (right of `#`) |
| `cluster` | `str`, optional | Overrides the default cluster. Valid values: `americas`, `asia`, `esports`, `europe` |
**Returns:** [`AccountDto`](/api-reference/objects/account-objects#accountdto) or `dict`
**Raises:** [`InvalidCluster`](/api-reference/exceptions#invalidcluster), [`RiotAPIResponseError`](/api-reference/exceptions#riotapiresponseerror)
***
## Example
```python theme={null}
import valaw
import asyncio
async def main():
client = valaw.Client("YOUR_TOKEN", "americas")
try:
account = await client.GET_getByRiotId("PlayerName", "NA1")
print(f"PUUID: {account.puuid}")
print(f"Riot ID: {account.gameName}#{account.tagLine}")
finally:
await client.close()
asyncio.run(main())
```
This endpoint queries across the entire cluster. Use the cluster closest to the player's region for best results.
# Client
Source: https://valaw.madebyjet.dev/api-reference/client
The main client used to interact with the VALORANT API.
## Constructor
```python theme={null}
valaw.Client(token, cluster, raw_data=False)
```
| Parameter | Type | Description |
| ---------- | ------ | ----------------------------------------------------------------------------------- |
| `token` | `str` | Your Riot Games API token |
| `cluster` | `str` | Default cluster for requests. Valid values: `americas`, `asia`, `esports`, `europe` |
| `raw_data` | `bool` | If `True`, returns raw JSON dicts instead of typed objects. Defaults to `False` |
```python theme={null}
import valaw
import asyncio
async def main():
client = valaw.Client("YOUR_TOKEN", "americas")
try:
account = await client.GET_getByRiotId("PlayerName", "NA1")
print(f"{account.gameName}#{account.tagLine}")
finally:
await client.close()
asyncio.run(main())
```
Always call `client.close()` when done. Use a `try/finally` block to ensure it is always called even if an error occurs.
***
## Account
### GET\_getByPuuid
```python theme={null}
await client.GET_getByPuuid(puuid, cluster=None)
```
Get an account by PUUID.
| Parameter | Type | Description |
| --------- | --------------- | ----------------------------- |
| `puuid` | `str` | The player's PUUID |
| `cluster` | `str`, optional | Overrides the default cluster |
**Returns:** [`AccountDto`](/api-reference/objects/account-objects#accountdto) or `dict`
***
### GET\_getByRiotId
```python theme={null}
await client.GET_getByRiotId(gameName, tagLine, cluster=None)
```
Get an account by Riot ID (`gameName#tagLine`).
| Parameter | Type | Description |
| ---------- | --------------- | ----------------------------- |
| `gameName` | `str` | The game name (left of `#`) |
| `tagLine` | `str` | The tag line (right of `#`) |
| `cluster` | `str`, optional | Overrides the default cluster |
**Returns:** [`AccountDto`](/api-reference/objects/account-objects#accountdto) or `dict`
***
### GET\_getByAccessToken
```python theme={null}
await client.GET_getByAccessToken(authorization, cluster=None)
```
Get the account associated with an RSO access token.
| Parameter | Type | Description |
| --------------- | --------------- | ----------------------------- |
| `authorization` | `str` | The RSO access token |
| `cluster` | `str`, optional | Overrides the default cluster |
**Returns:** [`AccountDto`](/api-reference/objects/account-objects#accountdto) or `dict`
***
### GET\_getActiveShard
```python theme={null}
await client.GET_getActiveShard(puuid, cluster=None)
```
Get the active shard for a player.
| Parameter | Type | Description |
| --------- | --------------- | ----------------------------- |
| `puuid` | `str` | The player's PUUID |
| `cluster` | `str`, optional | Overrides the default cluster |
**Returns:** [`ActiveShardDto`](/api-reference/objects/account-objects#activesharddto) or `dict`
***
## Content
### GET\_getContent
```python theme={null}
await client.GET_getContent(region, locale="")
```
Get game content (characters, maps, skins, etc.), optionally filtered by locale.
| Parameter | Type | Description |
| --------- | --------------- | ------------------------------------------------------------------------------------------------- |
| `region` | `str` | Region to query. Valid values: `ap`, `br`, `esports`, `eu`, `kr`, `latam`, `na` |
| `locale` | `str`, optional | Locale for localized names. See [Glossary](/glossary) for valid values. Input is case-insensitive |
**Returns:** [`ContentDto`](/api-reference/objects/content-objects#contentdto) or `dict`
Providing a locale results in faster response times from the API.
***
## Match
### GET\_getMatch
```python theme={null}
await client.GET_getMatch(matchId, region)
```
Get full match details by match ID.
| Parameter | Type | Description |
| --------- | ----- | ------------------------------ |
| `matchId` | `str` | The match ID |
| `region` | `str` | Region the match was played in |
**Returns:** [`MatchDto`](/api-reference/objects/match-objects#matchdto) or `dict`
***
### GET\_getMatchlist
```python theme={null}
await client.GET_getMatchlist(puuid, region)
```
Get a player's match history.
| Parameter | Type | Description |
| --------- | ----- | ------------------- |
| `puuid` | `str` | The player's PUUID |
| `region` | `str` | The player's region |
**Returns:** [`MatchlistDto`](/api-reference/objects/match-objects#matchlistdto) or `dict`
***
### GET\_getRecent
```python theme={null}
await client.GET_getRecent(queue, region)
```
Get recent match IDs for a queue. Returns matches completed in the last 10 minutes (or 12 hours for esports). NA, LATAM, and BR share a match history deployment.
| Parameter | Type | Description |
| --------- | ----- | -------------------------------------------------------------------------------------------------------------- |
| `queue` | `str` | Valid values: `competitive`, `unrated`, `spikerush`, `tournamentmode`, `deathmatch`, `onefa`, `ggteam`, `hurm` |
| `region` | `str` | Region to query |
**Returns:** [`RecentMatchesDto`](/api-reference/objects/match-objects#recentmatchesdto) or `dict`
***
## Ranked
### GET\_getLeaderboard
```python theme={null}
await client.GET_getLeaderboard(actId, region, size=200, startIndex=0)
```
Get the competitive leaderboard for an act.
| Parameter | Type | Description |
| ------------ | ----- | ------------------------------------------------------ |
| `actId` | `str` | The act ID |
| `region` | `str` | Region to query |
| `size` | `int` | Number of entries to return (1–200). Defaults to `200` |
| `startIndex` | `int` | Starting index for pagination. Defaults to `0` |
**Returns:** [`LeaderboardDto`](/api-reference/objects/ranked-objects#leaderboarddto) or `dict`
***
## Console Match
### GET\_getConsoleMatch
```python theme={null}
await client.GET_getConsoleMatch(matchId, region)
```
Get full console match details by match ID.
| Parameter | Type | Description |
| --------- | ----- | ------------------------------ |
| `matchId` | `str` | The match ID |
| `region` | `str` | Region the match was played in |
**Returns:** [`MatchDto`](/api-reference/objects/match-objects#matchdto) or `dict`
***
### GET\_getConsoleMatchlist
```python theme={null}
await client.GET_getConsoleMatchlist(puuid, region, platformType)
```
Get a console player's match history.
| Parameter | Type | Description |
| -------------- | ----- | ----------------------------------- |
| `puuid` | `str` | The player's PUUID |
| `region` | `str` | The player's region |
| `platformType` | `str` | Valid values: `playstation`, `xbox` |
**Returns:** [`MatchlistDto`](/api-reference/objects/match-objects#matchlistdto) or `dict`
***
### GET\_getConsoleRecent
```python theme={null}
await client.GET_getConsoleRecent(queue, region)
```
Get recent console match IDs for a queue.
| Parameter | Type | Description |
| --------- | ----- | ----------------------------------------------------------------------------------------------------------------- |
| `queue` | `str` | Valid values: `console_unrated`, `console_swiftplay`, `console_hurm`, `console_competitive`, `console_deathmatch` |
| `region` | `str` | Region to query |
**Returns:** [`RecentMatchesDto`](/api-reference/objects/match-objects#recentmatchesdto) or `dict`
***
## Console Ranked
### GET\_getConsoleLeaderboard
```python theme={null}
await client.GET_getConsoleLeaderboard(actId, region, platformType, size=200, startIndex=0)
```
Get the console competitive leaderboard for an act.
| Parameter | Type | Description |
| -------------- | ----- | ------------------------------------------------------ |
| `actId` | `str` | The act ID |
| `region` | `str` | Region to query |
| `platformType` | `str` | Valid values: `playstation`, `xbox` |
| `size` | `int` | Number of entries to return (1–200). Defaults to `200` |
| `startIndex` | `int` | Starting index for pagination. Defaults to `0` |
**Returns:** [`LeaderboardDto`](/api-reference/objects/ranked-objects#leaderboarddto) or `dict`
***
## Status
### GET\_getPlatformData
```python theme={null}
await client.GET_getPlatformData(region)
```
Get VALORANT platform status (maintenances and incidents) for a region.
| Parameter | Type | Description |
| --------- | ----- | --------------- |
| `region` | `str` | Region to query |
**Returns:** [`PlatformDataDto`](/api-reference/objects/status-objects#platformdatadto) or `dict`
***
## RSO
### create\_RSO\_link
```python theme={null}
client.create_RSO_link(redirect_uri, client_id, response_type, scopes, login_hint=None, ui_locales=None, state=None)
```
Constructs a Riot Sign-On (RSO) OAuth authorization URL. This is a regular synchronous method — no `await` needed.
| Parameter | Type | Description |
| --------------- | --------------------- | ------------------------------------------------------------------------------ |
| `redirect_uri` | `str` | OAuth2 callback URL |
| `client_id` | `str` | Your RSO application's client ID |
| `response_type` | `str` | OAuth2 response type, typically `code` |
| `scopes` | `list[str]` | Scopes to request. Must include `openid`. Additional: `cpid`, `offline_access` |
| `login_hint` | `str`, optional | Pre-populate login page data |
| `ui_locales` | `list[str]`, optional | Preferred UI locales in order |
| `state` | `str`, optional | Opaque value returned to your redirect URI |
**Returns:** `str` — the constructed authorization URL
# Get Console Leaderboard
Source: https://valaw.madebyjet.dev/api-reference/console/get-console-leaderboard
Get the console competitive leaderboard for an act
## GET\_getConsoleLeaderboard
```python theme={null}
await client.GET_getConsoleLeaderboard(actId, region, platformType, size=200, startIndex=0)
```
Get the console competitive leaderboard for an act.
| Parameter | Type | Description |
| -------------- | ----- | ------------------------------------------------------------------------------- |
| `actId` | `str` | The act ID |
| `region` | `str` | Region to query. Valid values: `ap`, `br`, `esports`, `eu`, `kr`, `latam`, `na` |
| `platformType` | `str` | The console platform. Valid values: `playstation`, `xbox` |
| `size` | `int` | Number of entries to return (1–200). Defaults to `200` |
| `startIndex` | `int` | Starting index for pagination. Defaults to `0` |
**Returns:** [`LeaderboardDto`](/api-reference/objects/ranked-objects#leaderboarddto) or `dict`
**Raises:** [`InvalidRegion`](/api-reference/exceptions#invalidregion), [`InvalidPlatformType`](/api-reference/exceptions#invalidplatformtype), [`RiotAPIResponseError`](/api-reference/exceptions#riotapiresponseerror)
***
## Example
```python theme={null}
import valaw
import asyncio
async def main():
client = valaw.Client("YOUR_TOKEN", "americas")
try:
leaderboard = await client.GET_getConsoleLeaderboard(
actId="act-id-here",
region="na",
platformType="playstation",
size=50
)
print(f"Total players: {leaderboard.totalPlayers}")
for player in leaderboard.players:
name = player.gameName if player.gameName != "Private" else "[Private]"
print(f" #{player.leaderboardRank} {name} — {player.rankedRating} RR")
finally:
await client.close()
asyncio.run(main())
```
PlayStation and Xbox leaderboards are separate. For PC leaderboards, use [`GET_getLeaderboard`](/api-reference/ranked/get-leaderboard).
# Get Console Match
Source: https://valaw.madebyjet.dev/api-reference/console/get-console-match
Get full console match details by match ID
## GET\_getConsoleMatch
```python theme={null}
await client.GET_getConsoleMatch(matchId, region)
```
Get full console match details by match ID.
| Parameter | Type | Description |
| --------- | ----- | ---------------------------------------------------------------------------------------------- |
| `matchId` | `str` | The match ID |
| `region` | `str` | Region the match was played in. Valid values: `ap`, `br`, `esports`, `eu`, `kr`, `latam`, `na` |
**Returns:** [`MatchDto`](/api-reference/objects/match-objects#matchdto) or `dict`
**Raises:** [`InvalidRegion`](/api-reference/exceptions#invalidregion), [`RiotAPIResponseError`](/api-reference/exceptions#riotapiresponseerror)
***
## Example
```python theme={null}
import valaw
import asyncio
async def main():
client = valaw.Client("YOUR_TOKEN", "americas")
try:
match = await client.GET_getConsoleMatch("match-id-here", "na")
print(f"Map: {match.matchInfo.mapId}")
print(f"Duration: {match.matchInfo.gameLengthMillis / 1000 / 60:.1f} minutes")
finally:
await client.close()
asyncio.run(main())
```
For PC matches, use [`GET_getMatch`](/api-reference/match/get-match) instead.
# Get Console Matchlist
Source: https://valaw.madebyjet.dev/api-reference/console/get-console-matchlist
Get match history for a console player by PUUID
## GET\_getConsoleMatchlist
```python theme={null}
await client.GET_getConsoleMatchlist(puuid, region, platformType)
```
Get a console player's match history.
| Parameter | Type | Description |
| -------------- | ----- | ----------------------------------------------------------------------------------- |
| `puuid` | `str` | The player's PUUID |
| `region` | `str` | The player's region. Valid values: `ap`, `br`, `esports`, `eu`, `kr`, `latam`, `na` |
| `platformType` | `str` | The console platform. Valid values: `playstation`, `xbox` |
**Returns:** [`MatchlistDto`](/api-reference/objects/match-objects#matchlistdto) or `dict`
**Raises:** [`InvalidRegion`](/api-reference/exceptions#invalidregion), [`InvalidPlatformType`](/api-reference/exceptions#invalidplatformtype), [`RiotAPIResponseError`](/api-reference/exceptions#riotapiresponseerror)
***
## Example
```python theme={null}
import valaw
import asyncio
async def main():
client = valaw.Client("YOUR_TOKEN", "americas")
try:
matchlist = await client.GET_getConsoleMatchlist(
puuid="player-puuid-here",
region="na",
platformType="playstation"
)
print(f"Total matches: {len(matchlist.history)}")
finally:
await client.close()
asyncio.run(main())
```
# Get Console Recent Matches
Source: https://valaw.madebyjet.dev/api-reference/console/get-console-recent
Get recently completed console match IDs for a queue
## GET\_getConsoleRecent
```python theme={null}
await client.GET_getConsoleRecent(queue, region)
```
Get recently completed console match IDs for a queue. Returns matches from the last 10 minutes for live regions, or 12 hours for the esports routing value.
| Parameter | Type | Description |
| --------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `queue` | `str` | Console queue type. Valid values: `console_unrated`, `console_swiftplay`, `console_hurm`, `console_competitive`, `console_deathmatch` |
| `region` | `str` | Region to query. Valid values: `ap`, `br`, `esports`, `eu`, `kr`, `latam`, `na` |
**Returns:** [`RecentMatchesDto`](/api-reference/objects/match-objects#recentmatchesdto) or `dict`
**Raises:** [`InvalidRegion`](/api-reference/exceptions#invalidregion), [`InvalidQueue`](/api-reference/exceptions#invalidqueue), [`RiotAPIResponseError`](/api-reference/exceptions#riotapiresponseerror)
NA, LATAM, and BR share a match history deployment. Results may be inconsistent due to load balancing.
***
## Example
```python theme={null}
import valaw
import asyncio
async def main():
client = valaw.Client("YOUR_TOKEN", "americas")
try:
recent = await client.GET_getConsoleRecent("console_competitive", "na")
print(f"Recent matches: {len(recent.matchIds)}")
finally:
await client.close()
asyncio.run(main())
```
Console queues are prefixed with `console_`. For PC queues, use [`GET_getRecent`](/api-reference/match/get-recent).
# Get Content
Source: https://valaw.madebyjet.dev/api-reference/content/get-content
Get VALORANT game content, optionally filtered by locale
## GET\_getContent
```python theme={null}
await client.GET_getContent(region, locale="")
```
Get game content (characters, maps, skins, etc.), optionally filtered by locale. Providing a locale results in faster response times.
| Parameter | Type | Description |
| --------- | --------------- | ---------------------------------------------------------------------------------------------------------------- |
| `region` | `str` | Region to query. Valid values: `ap`, `br`, `esports`, `eu`, `kr`, `latam`, `na` |
| `locale` | `str`, optional | Locale for localized names. Input is case-insensitive (e.g. `en-US`, `en-us`). Leave empty to return all locales |
**Returns:** [`ContentDto`](/api-reference/objects/content-objects#contentdto) or `dict`
**Raises:** [`InvalidRegion`](/api-reference/exceptions#invalidregion), [`InvalidLocale`](/api-reference/exceptions#invalidlocale), [`RiotAPIResponseError`](/api-reference/exceptions#riotapiresponseerror)
Always pass a locale for faster API responses. See the [glossary](/glossary) for all valid locales.
***
## Example
```python theme={null}
import valaw
import asyncio
async def main():
client = valaw.Client("YOUR_TOKEN", "americas")
try:
content = await client.GET_getContent("na", "en-US")
print(f"Version: {content.version}")
print(f"Characters: {len(content.characters)}")
for character in content.characters:
print(f" {character.name}")
finally:
await client.close()
asyncio.run(main())
```
# Exceptions
Source: https://valaw.madebyjet.dev/api-reference/exceptions
Exceptions raised by the valaw client.
All exceptions are accessible via `valaw.Exceptions`.
```python theme={null}
import valaw
try:
account = await client.GET_getByPuuid("puuid-here")
except valaw.Exceptions.RiotAPIResponseError as e:
print(e.status_code, e.status_message)
```
***
## RiotAPIResponseError
Raised when the Riot API returns an error response.
| Attribute | Type | Description |
| ---------------- | ----- | ------------------------------------------------- |
| `status_code` | `int` | HTTP status code returned by the API |
| `status_message` | `str` | Error message returned by the API |
| `message` | `str` | Formatted as `"{status_code} - {status_message}"` |
| Code | Meaning |
| ----- | ------------------------------------------- |
| `400` | Bad request |
| `401` | Unauthorized — invalid or missing API token |
| `403` | Forbidden |
| `404` | Data not found |
| `429` | Rate limit exceeded |
| `500` | Internal server error |
| `503` | Service unavailable |
```python theme={null}
try:
match = await client.GET_getMatch("match-id", "na")
except valaw.Exceptions.RiotAPIResponseError as e:
if e.status_code == 429:
print("Rate limited, try again later")
elif e.status_code == 404:
print("Match not found")
else:
print(f"Error {e.status_code}: {e.status_message}")
```
Full details on response codes can be found in the [Riot Games documentation](https://developer.riotgames.com/docs/portal#web-apis_response-codes).
***
## InvalidRegion
Raised when an invalid region is passed to a method.
Valid regions: `ap`, `br`, `esports`, `eu`, `kr`, `latam`, `na`
***
## InvalidCluster
Raised when an invalid cluster is passed to the client or a method.
Valid clusters: `americas`, `asia`, `esports`, `europe`
***
## InvalidLocale
Raised when an invalid locale is passed to `GET_getContent`.
Valid locales: `ar-AE`, `de-DE`, `en-GB`, `en-US`, `es-ES`, `es-MX`, `fr-FR`, `id-ID`, `it-IT`, `ja-JP`, `ko-KR`, `pl-PL`, `pt-BR`, `ru-RU`, `th-TH`, `tr-TR`, `vi-VN`, `zh-CN`, `zh-TW`
Locale input is case-insensitive — `en-US`, `en-us`, and `EN-US` all work.
***
## InvalidQueue
Raised when an invalid queue is passed to `GET_getRecent` or `GET_getConsoleRecent`.
Valid PC queues: `competitive`, `unrated`, `spikerush`, `tournamentmode`, `deathmatch`, `onefa`, `ggteam`, `hurm`
Valid console queues: `console_unrated`, `console_swiftplay`, `console_hurm`, `console_competitive`, `console_deathmatch`
***
## InvalidPlatformType
Raised when an invalid platform type is passed to a console method.
Valid values: `playstation`, `xbox`
***
## InvalidRiotAPIKey
Raised when `None` or an empty string is passed as the API token.
***
## FailedToParseJSON
Raised when the API response cannot be parsed as JSON. This is uncommon and usually indicates an unexpected response from the Riot API.
# Get Match
Source: https://valaw.madebyjet.dev/api-reference/match/get-match
Get full match details by match ID
## GET\_getMatch
```python theme={null}
await client.GET_getMatch(matchId, region)
```
Get full match details by match ID.
| Parameter | Type | Description |
| --------- | ----- | ---------------------------------------------------------------------------------------------- |
| `matchId` | `str` | The match ID |
| `region` | `str` | Region the match was played in. Valid values: `ap`, `br`, `esports`, `eu`, `kr`, `latam`, `na` |
**Returns:** [`MatchDto`](/api-reference/objects/match-objects#matchdto) or `dict`
**Raises:** [`InvalidRegion`](/api-reference/exceptions#invalidregion), [`RiotAPIResponseError`](/api-reference/exceptions#riotapiresponseerror)
***
## Example
```python theme={null}
import valaw
import asyncio
async def main():
client = valaw.Client("YOUR_TOKEN", "americas")
try:
match = await client.GET_getMatch("match-id-here", "na")
print(f"Map: {match.matchInfo.mapId}")
print(f"Duration: {match.matchInfo.gameLengthMillis / 1000 / 60:.1f} minutes")
for player in match.players:
if player.stats:
kda = f"{player.stats.kills}/{player.stats.deaths}/{player.stats.assists}"
print(f" {player.gameName}#{player.tagLine}: {kda}")
finally:
await client.close()
asyncio.run(main())
```
Match IDs are typically obtained from [`GET_getMatchlist`](/api-reference/match/get-matchlist) or [`GET_getRecent`](/api-reference/match/get-recent).
# Get Matchlist
Source: https://valaw.madebyjet.dev/api-reference/match/get-matchlist
Get match history for a player by PUUID
## GET\_getMatchlist
```python theme={null}
await client.GET_getMatchlist(puuid, region)
```
Get a player's match history.
| Parameter | Type | Description |
| --------- | ----- | ----------------------------------------------------------------------------------- |
| `puuid` | `str` | The player's PUUID |
| `region` | `str` | The player's region. Valid values: `ap`, `br`, `esports`, `eu`, `kr`, `latam`, `na` |
**Returns:** [`MatchlistDto`](/api-reference/objects/match-objects#matchlistdto) or `dict`
**Raises:** [`InvalidRegion`](/api-reference/exceptions#invalidregion), [`RiotAPIResponseError`](/api-reference/exceptions#riotapiresponseerror)
***
## Example
```python theme={null}
import valaw
import asyncio
async def main():
client = valaw.Client("YOUR_TOKEN", "americas")
try:
account = await client.GET_getByRiotId("PlayerName", "NA1")
matchlist = await client.GET_getMatchlist(account.puuid, "na")
print(f"Total matches: {len(matchlist.history)}")
for entry in matchlist.history[:5]:
print(f" {entry.matchId} — {entry.queueId}")
finally:
await client.close()
asyncio.run(main())
```
# Get Recent Matches
Source: https://valaw.madebyjet.dev/api-reference/match/get-recent
Get recently completed match IDs for a queue
## GET\_getRecent
```python theme={null}
await client.GET_getRecent(queue, region)
```
Get recently completed match IDs for a queue. Returns matches from the last 10 minutes for live regions, or 12 hours for the esports routing value.
| Parameter | Type | Description |
| --------- | ----- | -------------------------------------------------------------------------------------------------------------------------- |
| `queue` | `str` | Queue type. Valid values: `competitive`, `unrated`, `spikerush`, `tournamentmode`, `deathmatch`, `onefa`, `ggteam`, `hurm` |
| `region` | `str` | Region to query. Valid values: `ap`, `br`, `esports`, `eu`, `kr`, `latam`, `na` |
**Returns:** [`RecentMatchesDto`](/api-reference/objects/match-objects#recentmatchesdto) or `dict`
**Raises:** [`InvalidRegion`](/api-reference/exceptions#invalidregion), [`InvalidQueue`](/api-reference/exceptions#invalidqueue), [`RiotAPIResponseError`](/api-reference/exceptions#riotapiresponseerror)
NA, LATAM, and BR share a match history deployment. Results from those regions will be combined and may be inconsistent due to load balancing.
***
## Example
```python theme={null}
import valaw
import asyncio
async def main():
client = valaw.Client("YOUR_TOKEN", "americas")
try:
recent = await client.GET_getRecent("competitive", "na")
print(f"Recent competitive matches: {len(recent.matchIds)}")
for match_id in recent.matchIds[:3]:
print(f" {match_id}")
finally:
await client.close()
asyncio.run(main())
```
# Account Objects
Source: https://valaw.madebyjet.dev/api-reference/objects/account-objects
Data objects returned by account-related methods
## AccountDto
Returned by `GET_getByPuuid`, `GET_getByRiotId`, and `GET_getByAccessToken`.
| Field | Type | Description |
| ---------- | ------------- | --------------------------------------- |
| `puuid` | `str` | The player's unique identifier |
| `gameName` | `str \| None` | The player's in-game name (left of `#`) |
| `tagLine` | `str \| None` | The player's tag line (right of `#`) |
```python theme={null}
account = await client.GET_getByRiotId("PlayerName", "NA1")
print(f"{account.gameName}#{account.tagLine}")
print(f"PUUID: {account.puuid}")
```
***
## ActiveShardDto
Returned by `GET_getActiveShard`.
| Field | Type | Description |
| ------------- | ----- | --------------------------------------------------------- |
| `puuid` | `str` | The player's unique identifier |
| `game` | `str` | The game identifier (always `"val"` for VALORANT) |
| `activeShard` | `str` | The player's active region (e.g., `"na"`, `"eu"`, `"ap"`) |
```python theme={null}
shard = await client.GET_getActiveShard("player-puuid")
print(f"Active region: {shard.activeShard}")
```
# Content Objects
Source: https://valaw.madebyjet.dev/api-reference/objects/content-objects
Data objects returned by the content method
## ContentDto
Returned by `GET_getContent`.
| Field | Type | Description |
| -------------- | ---------------------- | -------------------------- |
| `version` | `str` | Content version identifier |
| `characters` | `list[ContentItemDto]` | VALORANT agents |
| `maps` | `list[ContentItemDto]` | Maps |
| `chromas` | `list[ContentItemDto]` | Weapon skin chromas |
| `skins` | `list[ContentItemDto]` | Weapon skins |
| `skinLevels` | `list[ContentItemDto]` | Skin levels |
| `equips` | `list[ContentItemDto]` | Equippable items |
| `gameModes` | `list[ContentItemDto]` | Game modes |
| `totems` | `list[ContentItemDto]` | Totems |
| `sprays` | `list[ContentItemDto]` | Sprays |
| `sprayLevels` | `list[ContentItemDto]` | Spray levels |
| `charms` | `list[ContentItemDto]` | Gun buddies |
| `charmLevels` | `list[ContentItemDto]` | Charm levels |
| `playerCards` | `list[ContentItemDto]` | Player cards |
| `playerTitles` | `list[ContentItemDto]` | Player titles |
| `acts` | `list[ActDto]` | Acts and episodes |
| `ceremonies` | `list[ContentItemDto]` | Ceremonies |
***
## ContentItemDto
A single content item (agent, map, skin, etc.).
| Field | Type | Description |
| ---------------- | --------------------------- | ------------------------------------------ |
| `name` | `str` | English name of the item |
| `id` | `str` | Unique identifier |
| `assetName` | `str` | Internal asset name |
| `localizedNames` | `LocalizedNamesDto \| None` | Localized names in all supported languages |
| `assetPath` | `str \| None` | Asset path |
***
## ActDto
An act or episode in VALORANT.
| Field | Type | Description |
| ---------------- | --------------------------- | ------------------------------------------------------------ |
| `name` | `str` | Name of the act/episode |
| `id` | `str` | Unique identifier (use as `actId` for leaderboard endpoints) |
| `isActive` | `bool` | Whether this act is currently active |
| `type` | `str` | Type (`"act"` or `"episode"`) |
| `localizedNames` | `LocalizedNamesDto \| None` | Localized names |
| `parentId` | `str \| None` | Parent episode ID (for acts) |
***
## LocalizedNamesDto
Contains the item name in all supported locales. Field names use underscores instead of hyphens.
| Field | Locale |
| ------- | --------------------- |
| `ar_AE` | Arabic (UAE) |
| `de_DE` | German |
| `en_GB` | English (UK) |
| `en_US` | English (US) |
| `es_ES` | Spanish (Spain) |
| `es_MX` | Spanish (Mexico) |
| `fr_FR` | French |
| `id_ID` | Indonesian |
| `it_IT` | Italian |
| `ja_JP` | Japanese |
| `ko_KR` | Korean |
| `pl_PL` | Polish |
| `pt_BR` | Portuguese (Brazil) |
| `ru_RU` | Russian |
| `th_TH` | Thai |
| `tr_TR` | Turkish |
| `vi_VN` | Vietnamese |
| `zh_CN` | Chinese (Simplified) |
| `zh_TW` | Chinese (Traditional) |
***
## Example
```python theme={null}
import valaw
import asyncio
async def main():
client = valaw.Client("YOUR_TOKEN", "americas")
try:
content = await client.GET_getContent("na", "en-US")
print(f"Version: {content.version}")
# List agents
for character in content.characters:
print(f" {character.name} ({character.id})")
# Find the current active act (useful for leaderboard actId)
for act in content.acts:
if act.isActive and act.type == "act":
print(f"Current act: {act.name} — ID: {act.id}")
finally:
await client.close()
asyncio.run(main())
```
Use the `id` from an active `ActDto` as the `actId` parameter for `GET_getLeaderboard`.
# Match Objects
Source: https://valaw.madebyjet.dev/api-reference/objects/match-objects
Data objects returned by match-related methods
## MatchDto
Returned by `GET_getMatch` and `GET_getConsoleMatch`.
| Field | Type | Description |
| -------------- | ---------------------- | --------------------------------- |
| `matchInfo` | `MatchInfoDto` | General match information |
| `players` | `list[PlayerDto]` | All players in the match |
| `coaches` | `list[CoachDto]` | Coaches (used in tournament mode) |
| `teams` | `list[TeamDto]` | Team results |
| `roundResults` | `list[RoundResultDto]` | Per-round data |
***
## MatchInfoDto
| Field | Type | Description |
| -------------------- | ------ | -------------------------------------- |
| `matchId` | `str` | Unique match identifier |
| `mapId` | `str` | Map identifier |
| `gameLengthMillis` | `int` | Match duration in milliseconds |
| `gameStartMillis` | `int` | Unix timestamp when the match started |
| `provisioningFlowId` | `str` | Provisioning flow identifier |
| `isCompleted` | `bool` | Whether the match has completed |
| `customGameName` | `str` | Custom game name (empty if not custom) |
| `queueId` | `str` | Queue type identifier |
| `gameMode` | `str` | Game mode |
| `isRanked` | `bool` | Whether the match was ranked |
| `seasonId` | `str` | Season identifier |
***
## MatchlistDto
Returned by `GET_getMatchlist` and `GET_getConsoleMatchlist`.
| Field | Type | Description |
| --------- | ------------------------- | --------------------- |
| `puuid` | `str` | The player's PUUID |
| `history` | `list[MatchlistEntryDto]` | Match history entries |
***
## MatchlistEntryDto
| Field | Type | Description |
| --------------------- | ----- | ----------------------------------------------- |
| `matchId` | `str` | Unique match identifier |
| `gameStartTimeMillis` | `int` | Unix timestamp when the match started |
| `queueId` | `str` | Queue type (e.g., `"competitive"`, `"unrated"`) |
***
## RecentMatchesDto
Returned by `GET_getRecent` and `GET_getConsoleRecent`.
| Field | Type | Description |
| ------------- | ----------- | -------------------------------------- |
| `currentTime` | `int` | Current Unix timestamp in milliseconds |
| `matchIds` | `list[str]` | Recently completed match IDs |
***
## PlayerDto
| Field | Type | Description |
| ----------------- | ------------------------ | ---------------------------------- |
| `puuid` | `str` | The player's PUUID |
| `gameName` | `str` | In-game name |
| `tagLine` | `str` | Tag line |
| `teamId` | `str` | Team (`"Red"` or `"Blue"`) |
| `partyId` | `str` | Party identifier |
| `characterId` | `str` | Agent identifier |
| `stats` | `PlayerStatsDto \| None` | Overall match statistics |
| `competitiveTier` | `int` | Competitive rank tier |
| `isObserver` | `bool` | Whether the player was an observer |
| `playerCard` | `str` | Player card identifier |
| `playerTitle` | `str` | Player title identifier |
| `accountLevel` | `int` | Account level |
***
## PlayerStatsDto
| Field | Type | Description |
| ---------------- | ------------------------- | ------------------------------ |
| `score` | `int` | Total score |
| `roundsPlayed` | `int` | Rounds participated in |
| `kills` | `int` | Total kills |
| `deaths` | `int` | Total deaths |
| `assists` | `int` | Total assists |
| `playtimeMillis` | `int` | Total playtime in milliseconds |
| `abilityCasts` | `AbilityCastsDto \| None` | Ability usage counts |
***
## TeamDto
| Field | Type | Description |
| -------------- | ------ | ------------------------------------- |
| `teamId` | `str` | Team identifier (`"Red"` or `"Blue"`) |
| `won` | `bool` | Whether the team won |
| `roundsPlayed` | `int` | Rounds played |
| `roundsWon` | `int` | Rounds won |
| `numPoints` | `int` | Total points scored |
***
## CoachDto
| Field | Type | Description |
| -------- | ----- | ----------------------------- |
| `puuid` | `str` | The coach's PUUID |
| `teamId` | `str` | The team the coach belongs to |
***
## RoundResultDto
| Field | Type | Description |
| ----------------- | --------------------------- | ------------------------------------------------ |
| `roundNum` | `int` | Round number (0-indexed) |
| `roundResult` | `str` | Result type (e.g., `"Eliminated"`, `"Detonate"`) |
| `roundCeremony` | `str` | Ceremony type |
| `winningTeam` | `str` | Winning team (`"Red"` or `"Blue"`) |
| `bombPlanter` | `str \| None` | PUUID of spike planter |
| `bombDefuser` | `str \| None` | PUUID of spike defuser |
| `plantRoundTime` | `int \| None` | Time of plant in milliseconds |
| `plantSite` | `str \| None` | Spike site (`"A"`, `"B"`, or `"C"`) |
| `defuseRoundTime` | `int \| None` | Time of defuse in milliseconds |
| `playerStats` | `list[PlayerRoundStatsDto]` | Per-player round statistics |
| `roundResultCode` | `str` | Round result code |
***
## PlayerRoundStatsDto
| Field | Type | Description |
| --------- | ----------------- | --------------------------------- |
| `puuid` | `str` | The player's PUUID |
| `kills` | `list[KillDto]` | Kills by this player in the round |
| `damage` | `list[DamageDto]` | Damage dealt to each opponent |
| `score` | `int` | Score earned in the round |
| `economy` | `EconomyDto` | Economic information |
| `ability` | `AbilityDto` | Ability usage |
***
## AbilityCastsDto
| Field | Type | Description |
| --------------- | ----- | ------------------ |
| `grenadeCasts` | `int` | C ability casts |
| `ability1Casts` | `int` | Q ability casts |
| `ability2Casts` | `int` | E ability casts |
| `ultimateCasts` | `int` | X (ultimate) casts |
***
## AbilityDto
| Field | Type | Description |
| ----------------- | ----- | ----------------- |
| `grenadeEffects` | `str` | C ability effects |
| `ability1Effects` | `str` | Q ability effects |
| `ability2Effects` | `str` | E ability effects |
| `ultimateEffects` | `str` | X ability effects |
***
## EconomyDto
| Field | Type | Description |
| -------------- | ----- | -------------------------------- |
| `loadoutValue` | `int` | Total loadout value |
| `weapon` | `str` | Weapon identifier |
| `armor` | `str` | Armor identifier |
| `remaining` | `int` | Credits remaining after purchase |
| `spent` | `int` | Credits spent in the round |
***
## KillDto
| Field | Type | Description |
| --------------------------- | -------------------------- | ------------------------------------ |
| `timeSinceGameStartMillis` | `int` | Time since match start |
| `timeSinceRoundStartMillis` | `int` | Time since round start |
| `killer` | `str` | Killer's PUUID |
| `victim` | `str` | Victim's PUUID |
| `victimLocation` | `LocationDto` | Victim's map coordinates |
| `assistants` | `list[str] \| None` | PUUIDs of assistants |
| `playerLocations` | `list[PlayerLocationsDto]` | All player positions at time of kill |
| `finishingDamage` | `FinishingDamageDto` | Final damage details |
***
## DamageDto
| Field | Type | Description |
| ----------- | ----- | ------------------ |
| `receiver` | `str` | Receiver's PUUID |
| `damage` | `int` | Total damage dealt |
| `legshots` | `int` | Leg shot count |
| `bodyshots` | `int` | Body shot count |
| `headshots` | `int` | Headshot count |
***
## FinishingDamageDto
| Field | Type | Description |
| --------------------- | ------ | -------------------------------------------------- |
| `damageType` | `str` | Type of damage (`"Weapon"`, `"Ability"`, `"Bomb"`) |
| `damageItem` | `str` | Item or ability that dealt damage |
| `isSecondaryFireMode` | `bool` | Whether secondary fire was used |
***
## LocationDto
| Field | Type | Description |
| ----- | ----- | ------------ |
| `x` | `int` | X coordinate |
| `y` | `int` | Y coordinate |
***
## PlayerLocationsDto
| Field | Type | Description |
| ------------- | ------------- | ---------------------------------------- |
| `puuid` | `str` | The player's PUUID |
| `viewRadians` | `float` | Direction the player is facing (radians) |
| `location` | `LocationDto` | Map coordinates |
***
## Example
```python theme={null}
import valaw
import asyncio
async def main():
client = valaw.Client("YOUR_TOKEN", "americas")
try:
match = await client.GET_getMatch("match-id", "na")
print(f"Map: {match.matchInfo.mapId}")
print(f"Duration: {match.matchInfo.gameLengthMillis / 1000 / 60:.1f} min")
for player in match.players:
if player.stats:
kda = f"{player.stats.kills}/{player.stats.deaths}/{player.stats.assists}"
print(f" {player.gameName}#{player.tagLine}: {kda}")
finally:
await client.close()
asyncio.run(main())
```
# Ranked Objects
Source: https://valaw.madebyjet.dev/api-reference/objects/ranked-objects
Data objects returned by ranked and leaderboard methods
## LeaderboardDto
Returned by `GET_getLeaderboard` and `GET_getConsoleLeaderboard`.
| Field | Type | Description |
| ----------------------- | ----------------- | ------------------------------------------ |
| `actId` | `str` | The act identifier |
| `players` | `list[PlayerDto]` | Leaderboard entries |
| `totalPlayers` | `int` | Total number of players on the leaderboard |
| `immortalStartingPage` | `int` | Page where Immortal rank begins |
| `immortalStartingIndex` | `int` | Index where Immortal rank begins |
| `topTierRRThreshold` | `int` | RR threshold for top tier players |
| `tierDetails` | `dict` | Tier-specific thresholds |
| `startIndex` | `int` | Starting index for this page |
| `shard` | `str` | Region/shard for this leaderboard |
| `query` | `str \| None` | Optional filter query |
***
## PlayerDto
A player entry on the leaderboard. Note: this is different from the `PlayerDto` in match objects.
| Field | Type | Description |
| ----------------- | ----- | ----------------------------------------------- |
| `leaderboardRank` | `int` | Position on the leaderboard (1 = top) |
| `rankedRating` | `int` | Current Ranked Rating (RR) |
| `numberOfWins` | `int` | Competitive wins for the act |
| `competitiveTier` | `int` | Competitive rank tier |
| `puuid` | `str` | Player's PUUID (empty for private profiles) |
| `gameName` | `str` | In-game name (`"Private"` for private profiles) |
| `tagLine` | `str` | Tag line (empty for private profiles) |
Players with private profiles will have `gameName = "Private"` and empty `puuid` and `tagLine` fields.
***
## Competitive Tier Reference
| Tier | Rank |
| ---- | ----------- |
| 0 | Unranked |
| 3 | Iron 1 |
| 4 | Iron 2 |
| 5 | Iron 3 |
| 6 | Bronze 1 |
| 7 | Bronze 2 |
| 8 | Bronze 3 |
| 9 | Silver 1 |
| 10 | Silver 2 |
| 11 | Silver 3 |
| 12 | Gold 1 |
| 13 | Gold 2 |
| 14 | Gold 3 |
| 15 | Platinum 1 |
| 16 | Platinum 2 |
| 17 | Platinum 3 |
| 18 | Diamond 1 |
| 19 | Diamond 2 |
| 20 | Diamond 3 |
| 21 | Ascendant 1 |
| 22 | Ascendant 2 |
| 23 | Ascendant 3 |
| 24 | Immortal 1 |
| 25 | Immortal 2 |
| 26 | Immortal 3 |
| 27 | Radiant |
***
## Example
```python theme={null}
import valaw
import asyncio
async def main():
client = valaw.Client("YOUR_TOKEN", "americas")
try:
leaderboard = await client.GET_getLeaderboard(
actId="act-id-here",
region="na",
size=10
)
print(f"Total players: {leaderboard.totalPlayers}")
for player in leaderboard.players:
if player.gameName != "Private":
print(f" #{player.leaderboardRank} {player.gameName}#{player.tagLine} — {player.rankedRating} RR")
finally:
await client.close()
asyncio.run(main())
```
# Status Objects
Source: https://valaw.madebyjet.dev/api-reference/objects/status-objects
Data objects returned by the platform status method
## PlatformDataDto
Returned by `GET_getPlatformData`.
| Field | Type | Description |
| -------------- | ----------------- | ---------------------------------- |
| `id` | `str` | Platform identifier |
| `name` | `str` | Platform name |
| `locales` | `list[str]` | Supported locales |
| `maintenances` | `list[StatusDto]` | Current and scheduled maintenances |
| `incidents` | `list[StatusDto]` | Active incidents |
***
## StatusDto
Represents a maintenance or incident.
| Field | Type | Description |
| -------------------- | ------------------ | ----------------------------------------------------------------------- |
| `id` | `int` | Unique identifier |
| `maintenance_status` | `str` | Maintenance status (e.g., `"scheduled"`, `"in_progress"`, `"complete"`) |
| `incident_severity` | `str` | Incident severity (e.g., `"info"`, `"warning"`, `"critical"`) |
| `titles` | `list[ContentDto]` | Localized titles |
| `updates` | `list[UpdateDto]` | Status updates |
| `created_at` | `str` | ISO 8601 creation timestamp |
| `updated_at` | `str` | ISO 8601 last updated timestamp |
| `archived_at` | `str \| None` | ISO 8601 archive timestamp (`None` if still active) |
| `platforms` | `list[str]` | Affected platforms |
`maintenance_status` applies to maintenance entries; `incident_severity` applies to incident entries.
***
## ContentDto
Localized content for a status title or update body.
| Field | Type | Description |
| --------- | ----- | ----------------------------- |
| `locale` | `str` | Locale code (e.g., `"en_US"`) |
| `content` | `str` | Localized text |
***
## UpdateDto
An update or announcement for a maintenance or incident.
| Field | Type | Description |
| ------------------- | ----------- | -------------------------------- |
| `id` | `int` | Unique identifier |
| `author` | `str` | Author of the update |
| `publish` | `bool` | Whether this update is published |
| `publish_locations` | `list[str]` | Where the update is published |
| `created_at` | `str` | ISO 8601 creation timestamp |
| `updated_at` | `str` | ISO 8601 last updated timestamp |
***
## Example
```python theme={null}
import valaw
import asyncio
async def main():
client = valaw.Client("YOUR_TOKEN", "americas")
try:
status = await client.GET_getPlatformData("na")
print(f"Platform: {status.name}")
for incident in status.incidents:
en_title = next((t for t in incident.titles if t.locale == "en_US"), None)
if en_title:
print(f"Incident: {en_title.content}")
print(f" Severity: {incident.incident_severity}")
for maintenance in status.maintenances:
en_title = next((t for t in maintenance.titles if t.locale == "en_US"), None)
if en_title:
print(f"Maintenance: {en_title.content}")
print(f" Status: {maintenance.maintenance_status}")
finally:
await client.close()
asyncio.run(main())
```
# Get Leaderboard
Source: https://valaw.madebyjet.dev/api-reference/ranked/get-leaderboard
Get the competitive leaderboard for an act
## GET\_getLeaderboard
```python theme={null}
await client.GET_getLeaderboard(actId, region, size=200, startIndex=0)
```
Get the competitive leaderboard for an act.
| Parameter | Type | Description |
| ------------ | ----- | ------------------------------------------------------------------------------- |
| `actId` | `str` | The act ID |
| `region` | `str` | Region to query. Valid values: `ap`, `br`, `esports`, `eu`, `kr`, `latam`, `na` |
| `size` | `int` | Number of entries to return (1–200). Defaults to `200` |
| `startIndex` | `int` | Starting index for pagination. Defaults to `0` |
**Returns:** [`LeaderboardDto`](/api-reference/objects/ranked-objects#leaderboarddto) or `dict`
**Raises:** [`InvalidRegion`](/api-reference/exceptions#invalidregion), [`RiotAPIResponseError`](/api-reference/exceptions#riotapiresponseerror)
***
## Example
```python theme={null}
import valaw
import asyncio
async def main():
client = valaw.Client("YOUR_TOKEN", "americas")
try:
# Get the top 50 players for a specific act
leaderboard = await client.GET_getLeaderboard(
actId="act-id-here",
region="na",
size=50
)
print(f"Total players: {leaderboard.totalPlayers}")
for player in leaderboard.players:
name = player.gameName if player.gameName != "Private" else "[Private]"
print(f" #{player.leaderboardRank} {name} — {player.rankedRating} RR")
finally:
await client.close()
asyncio.run(main())
```
Some players have private profiles. For these entries, `gameName` is `"Private"` and `puuid`/`tagLine` are empty strings.
Use `startIndex` to paginate through the full leaderboard. For example, to get entries 201–400, set `startIndex=200`.
# Create RSO Link
Source: https://valaw.madebyjet.dev/api-reference/rso/create-rso-link
Construct a Riot Sign-On (RSO) OAuth authorization URL
## create\_RSO\_link
```python theme={null}
client.create_RSO_link(redirect_uri, client_id, response_type, scopes, login_hint=None, ui_locales=None, state=None)
```
Constructs a Riot Sign-On (RSO) OAuth authorization URL. This is a **synchronous** method — no `await` needed.
| Parameter | Type | Description |
| --------------- | --------------------- | ------------------------------------------------------------------------------ |
| `redirect_uri` | `str` | OAuth2 callback URL |
| `client_id` | `str` | Your RSO application's client ID |
| `response_type` | `str` | OAuth2 response type, typically `"code"` |
| `scopes` | `list[str]` | Scopes to request. Must include `openid`. Additional: `cpid`, `offline_access` |
| `login_hint` | `str`, optional | Pre-populate login page data |
| `ui_locales` | `list[str]`, optional | Preferred UI locales in order |
| `state` | `str`, optional | Opaque value returned to your redirect URI for CSRF protection |
**Returns:** `str` — the constructed authorization URL
***
## Example
```python theme={null}
import valaw
import secrets
client = valaw.Client("YOUR_TOKEN", "americas")
# Generate a CSRF state token
state_token = secrets.token_urlsafe(32)
auth_url = client.create_RSO_link(
redirect_uri="https://yourapp.com/callback",
client_id="your-client-id",
response_type="code",
scopes=["openid", "cpid"],
state=state_token
)
print(f"Redirect user to: {auth_url}")
```
## OAuth2 Flow
1. Call `create_RSO_link` to generate the authorization URL
2. Redirect the user to that URL
3. The user logs in and grants permissions
4. Riot redirects back to your `redirect_uri` with an authorization code
5. Exchange the code for an access token (via Riot's token endpoint)
6. Use the access token with [`GET_getByAccessToken`](/api-reference/account/get-by-access-token)
Always validate the `state` parameter in your callback to prevent CSRF attacks.
# Get Platform Data
Source: https://valaw.madebyjet.dev/api-reference/status/get-platform-data
Get VALORANT platform status for a region
## GET\_getPlatformData
```python theme={null}
await client.GET_getPlatformData(region)
```
Get VALORANT platform status (maintenances and incidents) for a region.
| Parameter | Type | Description |
| --------- | ----- | ------------------------------------------------------------------------------- |
| `region` | `str` | Region to query. Valid values: `ap`, `br`, `esports`, `eu`, `kr`, `latam`, `na` |
**Returns:** [`PlatformDataDto`](/api-reference/objects/status-objects#platformdatadto) or `dict`
**Raises:** [`InvalidRegion`](/api-reference/exceptions#invalidregion), [`RiotAPIResponseError`](/api-reference/exceptions#riotapiresponseerror)
***
## Example
```python theme={null}
import valaw
import asyncio
async def main():
client = valaw.Client("YOUR_TOKEN", "americas")
try:
status = await client.GET_getPlatformData("na")
print(f"Platform: {status.name}")
if status.incidents:
print(f"Active incidents: {len(status.incidents)}")
for incident in status.incidents:
en_title = next((t for t in incident.titles if t.locale == "en_US"), None)
if en_title:
print(f" - {en_title.content}")
else:
print("No active incidents")
if status.maintenances:
print(f"Maintenances: {len(status.maintenances)}")
finally:
await client.close()
asyncio.run(main())
```
# Console support
Source: https://valaw.madebyjet.dev/examples/console-support
Access VALORANT console data for PlayStation and Xbox platforms
VALORANT console (PlayStation and Xbox) has separate API endpoints. They mirror the PC endpoints but require a `platformType` parameter. Valid values are `playstation` and `xbox` (case-insensitive).
## Match history
```python theme={null}
import valaw
import asyncio
async def main():
client = valaw.Client("YOUR_TOKEN", "americas")
try:
# Account lookup is the same as PC
account = await client.GET_getByRiotId("ConsolePlayer", "PS5")
print(f"Found: {account.gameName}#{account.tagLine}")
# Get console match history — requires platformType
matchlist = await client.GET_getConsoleMatchlist(
puuid=account.puuid,
region="na",
platformType="playstation"
)
print(f"PlayStation matches: {len(matchlist.history)}")
# Get details for recent matches
for entry in matchlist.history[:3]:
match = await client.GET_getConsoleMatch(entry.matchId, "na")
print(f"\nMap: {match.matchInfo.mapId}")
player = next((p for p in match.players if p.puuid == account.puuid), None)
if player and player.stats:
kda = f"{player.stats.kills}/{player.stats.deaths}/{player.stats.assists}"
print(f"K/D/A: {kda}")
finally:
await client.close()
asyncio.run(main())
```
## Recent console matches
```python theme={null}
import valaw
import asyncio
async def main():
client = valaw.Client("YOUR_TOKEN", "americas")
try:
recent = await client.GET_getConsoleRecent("console_competitive", "na")
print(f"Recent matches: {len(recent.matchIds)}")
for match_id in recent.matchIds[:3]:
match = await client.GET_getConsoleMatch(match_id, "na")
print(f" {match_id} — {match.matchInfo.mapId} ({len(match.players)} players)")
finally:
await client.close()
asyncio.run(main())
```
Valid console queues: `console_unrated`, `console_swiftplay`, `console_hurm`, `console_competitive`, `console_deathmatch`
## Console leaderboard
```python theme={null}
import valaw
import asyncio
async def main():
client = valaw.Client("YOUR_TOKEN", "americas")
try:
leaderboard = await client.GET_getConsoleLeaderboard(
actId="act-id-here",
region="na",
platformType="playstation",
size=10
)
print(f"PlayStation Top {len(leaderboard.players)}:")
for player in leaderboard.players:
name = f"{player.gameName}#{player.tagLine}" if player.gameName != "Private" else "[Private]"
print(f" #{player.leaderboardRank}: {name} — {player.rankedRating} RR")
finally:
await client.close()
asyncio.run(main())
```
PlayStation and Xbox leaderboards are separate — each platform has its own rankings.
## Error handling
```python theme={null}
try:
matchlist = await client.GET_getConsoleMatchlist(
puuid=account.puuid,
region="na",
platformType="playstation"
)
except valaw.Exceptions.InvalidPlatformType as e:
print(f"Invalid platform: {e}")
except valaw.Exceptions.InvalidRegion as e:
print(f"Invalid region: {e}")
except valaw.Exceptions.RiotAPIResponseError as e:
print(f"API error {e.status_code}: {e.status_message}")
```
# Leaderboard
Source: https://valaw.madebyjet.dev/examples/leaderboard
Fetch and display competitive leaderboard rankings
This example shows how to retrieve the competitive leaderboard for a specific act and region.
To get the `actId`, use `GET_getContent` and find the active act — see the [content objects reference](/api-reference/objects/content-objects) for details.
```python theme={null}
import valaw
import asyncio
async def main():
client = valaw.Client("YOUR_TOKEN", "americas")
try:
leaderboard = await client.GET_getLeaderboard(
actId="act-id-here",
region="na",
size=10,
startIndex=0
)
print(f"Total players: {leaderboard.totalPlayers}")
print(f"Immortal starts at index: {leaderboard.immortalStartingIndex}")
for player in leaderboard.players:
name = f"{player.gameName}#{player.tagLine}" if player.gameName != "Private" else "[Private]"
print(f"#{player.leaderboardRank}: {name} — {player.rankedRating} RR ({player.numberOfWins} wins)")
finally:
await client.close()
asyncio.run(main())
```
## Pagination
The leaderboard returns up to 200 entries per request. Use `startIndex` to paginate:
```python theme={null}
import valaw
import asyncio
async def main():
client = valaw.Client("YOUR_TOKEN", "americas")
try:
all_players = []
page_size = 200
for page in range(5): # fetch first 1000 players
leaderboard = await client.GET_getLeaderboard(
actId="act-id-here",
region="na",
size=page_size,
startIndex=page * page_size
)
all_players.extend(leaderboard.players)
if len(leaderboard.players) < page_size:
break # reached the end
print(f"Fetched {len(all_players)} players")
finally:
await client.close()
asyncio.run(main())
```
## Getting the act ID
```python theme={null}
import valaw
import asyncio
async def main():
client = valaw.Client("YOUR_TOKEN", "americas")
try:
content = await client.GET_getContent("na")
for act in content.acts:
if act.isActive and act.type == "act":
print(f"Current act: {act.name}")
print(f"Act ID: {act.id}")
finally:
await client.close()
asyncio.run(main())
```
## Competitive tier reference
| Tier | Rank |
| ----- | ------------- |
| 0 | Unranked |
| 3–5 | Iron 1–3 |
| 6–8 | Bronze 1–3 |
| 9–11 | Silver 1–3 |
| 12–14 | Gold 1–3 |
| 15–17 | Platinum 1–3 |
| 18–20 | Diamond 1–3 |
| 21–23 | Ascendant 1–3 |
| 24–26 | Immortal 1–3 |
| 27 | Radiant |
The `immortalStartingIndex` field tells you where Immortal+ players begin, useful if you only need top-tier entries.
## Error handling
```python theme={null}
try:
leaderboard = await client.GET_getLeaderboard(actId="...", region="na", size=250)
except ValueError as e:
print(f"Invalid size: {e}") # size must be 1–200
except valaw.Exceptions.RiotAPIResponseError as e:
print(f"API error {e.status_code}: {e.status_message}")
except valaw.Exceptions.InvalidRegion as e:
print(f"Invalid region: {e}")
```
# Match history
Source: https://valaw.madebyjet.dev/examples/match-history
Retrieve and display a player's match history
This example shows how to fetch a player's match history and retrieve detailed information about their recent games.
To get match history you need to:
1. Look up the account by Riot ID to get the PUUID
2. Fetch the matchlist using the PUUID
3. Optionally retrieve detailed match data for specific games
```python theme={null}
import valaw
import asyncio
async def main():
client = valaw.Client("YOUR_TOKEN", "americas")
try:
# Step 1: Get account by Riot ID
account = await client.GET_getByRiotId("PlayerName", "NA1")
print(f"Found: {account.gameName}#{account.tagLine}")
# Step 2: Get match history
matchlist = await client.GET_getMatchlist(account.puuid, "na")
print(f"Total matches: {len(matchlist.history)}")
# Step 3: Get details for recent matches
for entry in matchlist.history[:5]:
match = await client.GET_getMatch(entry.matchId, "na")
print(f"\nMatch: {entry.matchId}")
print(f" Map: {match.matchInfo.mapId}")
print(f" Mode: {match.matchInfo.gameMode}")
print(f" Duration: {match.matchInfo.gameLengthMillis // 1000 // 60} minutes")
# Find the player's stats in this match
player = next((p for p in match.players if p.puuid == account.puuid), None)
if player and player.stats:
kda = f"{player.stats.kills}/{player.stats.deaths}/{player.stats.assists}"
print(f" K/D/A: {kda} — Score: {player.stats.score}")
finally:
await client.close()
asyncio.run(main())
```
## Filtering by queue type
The `queueId` field on each `MatchlistEntryDto` lets you filter by game mode:
```python theme={null}
competitive_matches = [
entry for entry in matchlist.history
if entry.queueId == "competitive"
]
print(f"Competitive matches: {len(competitive_matches)}")
```
Common queue IDs: `competitive`, `unrated`, `spikerush`, `deathmatch`
## Error handling
```python theme={null}
try:
matchlist = await client.GET_getMatchlist(account.puuid, "na")
except valaw.Exceptions.RiotAPIResponseError as e:
if e.status_code == 404:
print("Player not found")
else:
print(f"API error {e.status_code}: {e.status_message}")
except valaw.Exceptions.InvalidRegion as e:
print(f"Invalid region: {e}")
```
The matchlist returns matches in reverse chronological order — most recent first.
# Player stats
Source: https://valaw.madebyjet.dev/examples/player-stats
Calculate and analyze player statistics from match data
Player statistics aren't directly available from the API. You need to fetch match history, retrieve each match's details, and aggregate the data yourself.
```python theme={null}
import valaw
import asyncio
async def main():
client = valaw.Client("YOUR_TOKEN", "americas")
try:
# Step 1: Look up player
account = await client.GET_getByRiotId("PlayerName", "NA1")
print(f"Found: {account.gameName}#{account.tagLine}")
# Step 2: Get match history
matchlist = await client.GET_getMatchlist(account.puuid, "na")
print(f"Matches found: {len(matchlist.history)}")
# Step 3: Aggregate stats across recent matches
total_kills = total_deaths = total_assists = total_score = 0
wins = losses = 0
matches_counted = 0
for entry in matchlist.history[:10]:
match = await client.GET_getMatch(entry.matchId, "na")
player = next((p for p in match.players if p.puuid == account.puuid), None)
if not player or not player.stats:
continue
total_kills += player.stats.kills
total_deaths += player.stats.deaths
total_assists += player.stats.assists
total_score += player.stats.score
matches_counted += 1
player_team = next((t for t in match.teams if t.teamId == player.teamId), None)
if player_team and player_team.won:
wins += 1
else:
losses += 1
# Step 4: Display results
if matches_counted > 0:
kda = (total_kills + total_assists) / max(total_deaths, 1)
win_rate = (wins / matches_counted) * 100
print(f"\nStats over {matches_counted} matches:")
print(f" Record: {wins}W / {losses}L ({win_rate:.1f}% win rate)")
print(f" Avg K/D/A: {total_kills/matches_counted:.1f}/{total_deaths/matches_counted:.1f}/{total_assists/matches_counted:.1f}")
print(f" KDA: {kda:.2f}")
print(f" Avg Score: {total_score/matches_counted:.0f}")
finally:
await client.close()
asyncio.run(main())
```
## Per-round headshot percentage
Round-level data lets you calculate headshot percentage from damage stats:
```python theme={null}
async def headshot_percentage(client, match_id, puuid, region):
match = await client.GET_getMatch(match_id, region)
total_shots = headshots = 0
for round_result in match.roundResults:
player_round = next(
(ps for ps in round_result.playerStats if ps.puuid == puuid), None
)
if not player_round:
continue
for dmg in player_round.damage:
total_shots += dmg.headshots + dmg.bodyshots + dmg.legshots
headshots += dmg.headshots
return (headshots / total_shots * 100) if total_shots > 0 else 0.0
```
## Filtering by queue
```python theme={null}
competitive = [e for e in matchlist.history if e.queueId == "competitive"]
print(f"Competitive matches: {len(competitive)}")
```
## Error handling
```python theme={null}
try:
match = await client.GET_getMatch(entry.matchId, "na")
player = next((p for p in match.players if p.puuid == account.puuid), None)
if not player:
print("Player not found in this match")
elif not player.stats:
print("Stats unavailable for this match")
except valaw.Exceptions.RiotAPIResponseError as e:
print(f"Failed to fetch match: {e.status_code} - {e.status_message}")
```
When analyzing many matches, use `asyncio.gather()` with a semaphore to fetch them concurrently while staying within rate limits.
# Glossary
Source: https://valaw.madebyjet.dev/glossary
Definitions for common terms used throughout the valaw documentation
## Cluster
A cluster is a group of servers used to connect to the Riot Games API. Valid clusters: `americas`, `asia`, `esports`, `europe`.
You can use any cluster to retrieve data, though using the one closest to you may be faster. Clusters are set when initializing the client and used for account-related endpoints.
***
## Region
A region is used for game data endpoints (match history, leaderboards, etc.). Valid regions: `ap`, `br`, `esports`, `eu`, `kr`, `latam`, `na`.
Always use the region associated with the account — using the wrong region returns a `404` error.
***
## Locale
The locale controls the language of localized content returned by `GET_getContent`. Valid locales:
`ar-AE`, `de-DE`, `en-GB`, `en-US`, `es-ES`, `es-MX`, `fr-FR`, `id-ID`, `it-IT`, `ja-JP`, `ko-KR`, `pl-PL`, `pt-BR`, `ru-RU`, `th-TH`, `tr-TR`, `vi-VN`, `zh-CN`, `zh-TW`
Locale input is case-insensitive — `en-US`, `en-us`, and `EN-US` all work.
***
## Riot ID
The Riot ID is the display name of an account, formatted as `gameName#tagLine` (e.g. `PlayerName#NA1`).
***
## gameName
The gameName is the part of the Riot ID to the left of the `#` (e.g. `PlayerName` in `PlayerName#NA1`).
***
## tagLine
The tagLine is the part of the Riot ID to the right of the `#` (e.g. `NA1` in `PlayerName#NA1`).
***
## PUUID
A PUUID (Player Universally Unique Identifier) is a player's unique ID used across Riot Games APIs. The PUUID returned by the API is an encrypted form of the actual user ID.
***
## Queue
A queue identifies the type of match. Valid PC queues: `competitive`, `unrated`, `spikerush`, `tournamentmode`, `deathmatch`, `onefa`, `ggteam`, `hurm`.
Valid console queues: `console_unrated`, `console_swiftplay`, `console_hurm`, `console_competitive`, `console_deathmatch`.
***
## platformType
The platformType identifies which console platform to query. Valid values: `playstation`, `xbox`. Used only for console endpoints.
# Authentication
Source: https://valaw.madebyjet.dev/guides/authentication
Learn how to authenticate with the Riot Games API using Valaw
## Getting a Riot API key
To use Valaw, you need a Riot Games API key from the [Riot Developer Portal](https://developer.riotgames.com/).
### Development vs production keys
Riot Games provides two types of API keys:
* **Development keys**: Free, automatically generated keys that expire every 24 hours. These have significant restrictions — only a small subset of endpoints are accessible, making them unsuitable for most real use cases.
* **Production keys**: Require an application and approval process. These keys have full endpoint access, higher rate limits, and don't expire.
A production key is strongly recommended. Development keys only have access to a handful of endpoints and will return 403 errors for most of the API.
## Storing keys securely
Never hardcode your API key directly in your source code. Use environment variables instead.
Create a `.env` file in your project root:
```bash theme={null}
RIOT_API_TOKEN=RGAPI-your-api-key-here
```
Then load it in Python using `python-dotenv`:
```python theme={null}
import os
from dotenv import load_dotenv
import valaw
load_dotenv()
RIOT_API_TOKEN = os.getenv("RIOT_API_TOKEN")
```
Add `.env` to your `.gitignore` to prevent accidentally committing your API key.
## Initializing the client
```python theme={null}
import valaw
import os
client = valaw.Client(
token=os.getenv("RIOT_API_TOKEN"),
cluster="americas"
)
```
### Choosing a cluster
The cluster determines which Riot API server handles your requests:
* `americas` — North America, Latin America, Brazil
* `europe` — Europe, Turkey, Russia, Middle East
* `asia` — Asia Pacific, Korea
* `esports` — Esports data
Choose the cluster nearest to your server for best performance. Note that the cluster is for the API routing, not the player's region — use `region` parameters on individual method calls for player-specific data.
### Client validation
The client validates your API key and cluster on initialization:
```python theme={null}
try:
client = valaw.Client(token="", cluster="invalid")
except valaw.Exceptions.InvalidRiotAPIKey:
print("API key is required")
except valaw.Exceptions.InvalidCluster:
print("Invalid cluster")
```
## Closing the client
Always close the client session when you're done:
```python theme={null}
import valaw
import asyncio
import os
async def main():
client = valaw.Client(token=os.getenv("RIOT_API_TOKEN"), cluster="americas")
try:
account = await client.GET_getByRiotId("PlayerName", "NA1")
print(f"Found: {account.gameName}#{account.tagLine}")
finally:
await client.close()
asyncio.run(main())
```
## Best practices
1. **Use a production key** — development keys only work with a few endpoints
2. **Use environment variables** — never commit API keys to version control
3. **Always close the session** — call `await client.close()` in a `finally` block
4. **Choose the right cluster** — use the cluster closest to your server
5. **Handle auth errors** — implement proper handling for expired or invalid keys
# Error handling
Source: https://valaw.madebyjet.dev/guides/error-handling
Handle exceptions raised by Valaw
All exceptions are available under `valaw.Exceptions`. See the [Exceptions reference](/api-reference/exceptions) for the full list.
## Basic error handling
Wrap API calls in a `try/except` to handle errors gracefully:
```python theme={null}
import valaw
import asyncio
async def main():
client = valaw.Client("YOUR_TOKEN", "americas")
try:
account = await client.GET_getByRiotId("PlayerName", "NA1")
print(f"Found: {account.gameName}#{account.tagLine}")
except valaw.Exceptions.RiotAPIResponseError as e:
print(f"API error {e.status_code}: {e.status_message}")
except valaw.Exceptions.InvalidCluster as e:
print(f"Invalid cluster: {e}")
finally:
await client.close()
asyncio.run(main())
```
## Handling rate limits (429)
When you exceed the rate limit, a `RiotAPIResponseError` is raised with status code `429`. Retry after a delay:
```python theme={null}
import valaw
import asyncio
async def request_with_retry(fn, max_retries=2):
"""Call fn(), retrying once on 429 after a delay."""
for attempt in range(max_retries):
try:
return await fn()
except valaw.Exceptions.RiotAPIResponseError as e:
if e.status_code == 429 and attempt == 0:
print("Rate limited, retrying in 10s...")
await asyncio.sleep(10)
else:
raise
# Usage
async def main():
client = valaw.Client("YOUR_TOKEN", "americas")
try:
account = await request_with_retry(
lambda: client.GET_getByRiotId("PlayerName", "NA1")
)
print(account.gameName)
finally:
await client.close()
```
## Handling not found (404)
```python theme={null}
async def get_account(client, game_name, tag_line):
try:
return await client.GET_getByRiotId(game_name, tag_line)
except valaw.Exceptions.RiotAPIResponseError as e:
if e.status_code == 404:
print(f"{game_name}#{tag_line} not found")
return None
raise # re-raise other errors
```
## Handling auth errors (401/403)
```python theme={null}
async def main():
client = valaw.Client("YOUR_TOKEN", "americas")
try:
account = await client.GET_getByRiotId("PlayerName", "NA1")
except valaw.Exceptions.RiotAPIResponseError as e:
if e.status_code == 401:
print("API key expired or invalid")
elif e.status_code == 403:
print("API key doesn't have access to this endpoint — use a production key")
else:
raise
finally:
await client.close()
```
## Handling validation errors
Validation errors are raised before making any network request:
```python theme={null}
import valaw
# InvalidRiotAPIKey — raised in Client.__init__
try:
client = valaw.Client(token="", cluster="americas")
except valaw.Exceptions.InvalidRiotAPIKey:
print("API key is required")
# InvalidCluster — raised in Client.__init__
try:
client = valaw.Client(token="YOUR_TOKEN", cluster="invalid")
except valaw.Exceptions.InvalidCluster as e:
print(f"Invalid cluster: {e}")
# InvalidQueue — raised before the API call
async def main():
client = valaw.Client("YOUR_TOKEN", "americas")
try:
matches = await client.GET_getRecent("not-a-queue", "na")
except valaw.Exceptions.InvalidQueue as e:
print(f"Invalid queue: {e}")
finally:
await client.close()
```
## Full example
```python theme={null}
import asyncio
import os
import valaw
from dotenv import load_dotenv
load_dotenv()
async def request_with_retry(fn, max_retries=2):
for attempt in range(max_retries):
try:
return await fn()
except valaw.Exceptions.RiotAPIResponseError as e:
if e.status_code == 429 and attempt == 0:
print("Rate limited, retrying in 10s...")
await asyncio.sleep(10)
else:
raise
async def main():
api_token = os.getenv("RIOT_API_TOKEN")
if not api_token:
raise ValueError("RIOT_API_TOKEN is not set")
client = valaw.Client(api_token, "americas")
try:
recent = await request_with_retry(
lambda: client.GET_getRecent("competitive", "na")
)
print(f"Found {len(recent.matchIds)} recent matches")
except valaw.Exceptions.RiotAPIResponseError as e:
if e.status_code == 403:
print("403 Forbidden — make sure you're using a production key")
elif e.status_code == 404:
print("No data found")
else:
print(f"API error {e.status_code}: {e.status_message}")
finally:
await client.close()
asyncio.run(main())
```
Full details on response codes can be found in the [Riot Games documentation](https://developer.riotgames.com/docs/portal#web-apis_response-codes).
# Rate limits
Source: https://valaw.madebyjet.dev/guides/rate-limits
Understand and manage Riot API rate limits
A production key is strongly recommended. Development keys only have access to a handful of endpoints and will return 403 errors for most of the API.
## Riot API rate limits
Rate limits are applied per API key. When exceeded, the API returns a `429` status code and valaw raises `RiotAPIResponseError`.
### Development key limits
* **20 requests per second**
* **100 requests per 2 minutes**
### Production key limits
Higher limits that vary by application approval level. See the [Riot Developer Portal](https://developer.riotgames.com/) for your specific limits.
## Handling rate limits
Valaw does not automatically retry rate-limited requests — this is intentional so you have full control. Handle `429` responses yourself:
```python theme={null}
import valaw
import asyncio
async def request_with_retry(fn, max_retries=2):
"""Call fn(), retrying once on 429 after a delay."""
for attempt in range(max_retries):
try:
return await fn()
except valaw.Exceptions.RiotAPIResponseError as e:
if e.status_code == 429 and attempt == 0:
print("Rate limited, retrying in 10s...")
await asyncio.sleep(10)
else:
raise
async def main():
client = valaw.Client("YOUR_TOKEN", "americas")
try:
account = await request_with_retry(
lambda: client.GET_getByRiotId("PlayerName", "NA1")
)
print(account.gameName)
finally:
await client.close()
asyncio.run(main())
```
## Best practices
**Space out requests** — avoid making many requests in rapid succession, especially in loops.
**Cache responses** — data like account info and content rarely changes. Store results rather than re-fetching:
```python theme={null}
cache = {}
async def get_account(client, game_name, tag_line):
key = f"{game_name}#{tag_line}"
if key not in cache:
cache[key] = await client.GET_getByRiotId(game_name, tag_line)
return cache[key]
```
**Limit concurrency** — when making multiple requests at once, use a semaphore:
```python theme={null}
import asyncio
import valaw
async def main():
client = valaw.Client("YOUR_TOKEN", "americas")
semaphore = asyncio.Semaphore(5) # max 5 concurrent requests
async def fetch(match_id):
async with semaphore:
return await client.GET_getMatch(match_id, "na")
match_ids = ["id1", "id2", "id3", "id4", "id5", "id6", "id7", "id8", "id9", "id10"]
try:
matches = await asyncio.gather(*[fetch(mid) for mid in match_ids])
print(f"Fetched {len(matches)} matches")
finally:
await client.close()
asyncio.run(main())
```
More information on rate limiting can be found in the [Riot API documentation](https://developer.riotgames.com/docs/portal#web-apis_rate-limiting).
# Raw data mode
Source: https://valaw.madebyjet.dev/guides/raw-data
Return raw JSON dicts instead of typed objects
By default, Valaw converts API responses into typed Python objects using `dataclass-wizard`. This gives you attribute access, IDE autocomplete, and type safety.
If you'd rather work with plain dictionaries — for example, to forward the response directly to another service — you can enable raw data mode.
## Enabling raw data mode
Pass `raw_data=True` when initializing the client:
```python theme={null}
import valaw
client = valaw.Client("YOUR_TOKEN", "americas", raw_data=True)
```
## Typed vs raw
**Typed (default):**
```python theme={null}
import valaw
import asyncio
async def main():
client = valaw.Client("YOUR_TOKEN", "americas")
try:
account = await client.GET_getByRiotId("PlayerName", "NA1")
print(account.gameName) # attribute access, IDE autocomplete works
print(account.tagLine)
finally:
await client.close()
asyncio.run(main())
```
**Raw:**
```python theme={null}
import valaw
import asyncio
async def main():
client = valaw.Client("YOUR_TOKEN", "americas", raw_data=True)
try:
account = await client.GET_getByRiotId("PlayerName", "NA1")
print(account["gameName"]) # dictionary access
print(account["tagLine"])
finally:
await client.close()
asyncio.run(main())
```
## When to use raw mode
Use raw mode when:
* You're forwarding the response directly to another service or API
* You want the exact JSON structure as Riot returns it
* You're debugging and want to inspect the raw response
Use typed mode (default) when:
* You want IDE autocomplete and type checking
* You're building an application that works with the data
## Error handling
Error handling works the same in both modes — `RiotAPIResponseError` is raised regardless.
```python theme={null}
import valaw
async def main():
client = valaw.Client("YOUR_TOKEN", "americas", raw_data=True)
try:
account = await client.GET_getByRiotId("PlayerName", "NA1")
except valaw.Exceptions.RiotAPIResponseError as e:
print(f"Error: {e.status_code} - {e.status_message}")
finally:
await client.close()
```
## Serializing to JSON
Raw mode is useful when you want to save the API response directly:
```python theme={null}
import valaw
import asyncio
import json
async def main():
client = valaw.Client("YOUR_TOKEN", "americas", raw_data=True)
try:
match = await client.GET_getMatch("match-id", "na")
with open("match.json", "w") as f:
json.dump(match, f, indent=2)
finally:
await client.close()
asyncio.run(main())
```
# Installation
Source: https://valaw.madebyjet.dev/installation
Install Valaw using pip or uv
## Install Valaw
Valaw is available on PyPI and can be installed using your preferred package manager.
```bash pip theme={null}
pip install valaw
```
```bash uv theme={null}
uv add valaw
```
## Dependencies
Valaw automatically installs the following required dependencies:
* **aiohttp** (3.14 or newer): Async HTTP client for making API requests
* **dataclass-wizard** (1.x): JSON deserialization into typed Python objects
These dependencies are specified in the project's `pyproject.toml` and will be installed automatically.
## Verify installation
After installation, verify that Valaw is available in your Python environment:
```python theme={null}
import valaw
print(valaw.__author__) # Should print: Jet612
```
If the import succeeds without errors, Valaw is installed correctly.
## Optional dev dependencies
If you're contributing to Valaw or running the test suite, install the optional dev dependencies:
```bash theme={null}
pip install valaw[dev]
```
This includes:
* **python-dotenv**: For loading environment variables from `.env` files
* **Ruff**: For linting and formatting the Python source
## Next steps
Now that Valaw is installed, you're ready to make your first API call:
Learn how to initialize the client and make your first request
# Introduction
Source: https://valaw.madebyjet.dev/introduction
Fast, typed, async Python wrapper for the official VALORANT API
## What is Valaw?
Valaw is a fast, typed, asynchronous Python wrapper for the [Official VALORANT API](https://developer.riotgames.com/) by Riot Games. It provides a clean, Pythonic interface for accessing match history, leaderboards, content, platform status, and console endpoints.
## Why use Valaw?
Valaw is designed to make working with the VALORANT API simple and efficient:
Built on `aiohttp` for non-blocking, high-performance requests
Returns typed objects instead of raw JSON for better IDE support and type safety
Supports all official PC and console endpoints for match, ranked, content, account, and status data
Compatible with Python 3.10 through 3.14
## System requirements
* **Python**: 3.10 or higher
* **Riot Games API Key**: Required for authentication ([Get your API key](https://developer.riotgames.com/))
* **Dependencies**: `aiohttp` 3.14+ and `dataclass-wizard` 1.x
## Typed vs raw responses
By default, Valaw returns typed Python objects for all API responses:
```python client.py:149-150 theme={null}
client = valaw.Client("YOUR_API_KEY", "americas")
content = await client.GET_getContent("na", "en-US")
print(content.version) # IDE autocomplete works!
```
If you prefer working with raw JSON dictionaries, you can opt out:
```python client.py:149-150 theme={null}
client = valaw.Client("YOUR_API_KEY", "americas", raw_data=True)
content = await client.GET_getContent("na", "en-US")
print(content["version"]) # Returns dict instead of ContentDto
```
## Getting started
Ready to start building with Valaw? Follow our installation guide to get set up:
Install Valaw using pip or uv
## Resources
* **[Riot Games Developer Portal](https://developer.riotgames.com/)**: Register for an API key and view official documentation
* **[Discord Community](https://discord.gg/mVXpvunBbF)**: Get help and connect with other developers
* **[GitHub Repository](https://github.com/Jet612/valaw)**: View source code and report issues
# Quickstart
Source: https://valaw.madebyjet.dev/quickstart
Get up and running with Valaw
First, install valaw. See the [Installation](/installation) guide for directions.
After installing, import valaw into your project:
```python theme={null}
import valaw
import asyncio
```
Then initialize the client with your API token and the [cluster](/api-reference/client#constructor) closest to you:
```python theme={null}
client = valaw.Client("YOUR_API_TOKEN", "americas")
```
A production key is strongly recommended — development keys only have access to a handful of endpoints and will return 403 errors for most of the API. You can apply for a production key through the [Riot Developer Portal](https://developer.riotgames.com/).
All API methods are `async` and must be called inside an `async` function. Always call `client.close()` when you are done to cleanly shut down the session.
After initializing the client, you can use it to make requests. For example, to get content for the `na` region:
```python theme={null}
async def main():
content = await client.GET_getContent("na", "en-US")
print(content)
await client.close()
asyncio.run(main())
```
A full working example:
```python theme={null}
import valaw
import asyncio
async def main():
client = valaw.Client("YOUR_API_TOKEN", "americas")
try:
content = await client.GET_getContent("na", "en-US")
print(content)
finally:
await client.close()
asyncio.run(main())
```
## Raw data
If you want raw JSON dictionaries instead of typed objects, pass `raw_data=True`:
```python theme={null}
client = valaw.Client("YOUR_API_TOKEN", "americas", raw_data=True)
```
This returns the raw API response as a `dict` instead of a typed object like `ContentDto`.