Skip to content

Python SDK for VLR.gg

Valorant esportsdata, straightinto Python.

VLRdevAPI reads VLR.gg and returns Pydantic models for matches, players, teams, events, and series. No API key, no account, and no parser to maintain.

Read the docs
uv add vlrdevapi

Used by partnered, Tier 1, Tier 2, and Game Changers orgs.

player.py
import vlrdevapi
player = vlrdevapi.player(11225)
info = player.info()
agents = player.agents(timespan="60d")
print(info.name, info.country)
print(agents.agents[0].agent)
returns Player InfoPlayers reference
player.info()player.teams()player.agents()player.matches()player.profile()
All namespaces

What it handles

The parts you would
otherwise have to write.

No HTML parsing. No selectors that break when VLR.gg ships a redesign. No glue code between the site and your app — just import the client and query the data.

Typed models

No more dict.get("name")

Every response is a Pydantic model with real fields, types, and descriptions. Autocomplete works. Validation is free.

models.pyruntime validation

class PlayerInfo(BaseModel):

player_id: int
name: str
real_name: str
country: str
total_winnings: int

# 13 fields · 0 validation errors

Curried access

Bind once, query anywhere

Pass an ID one time. Every related method hangs off the object you get back.

player.pyid bound once

player = client.player(11225)

player.info()Ethan
player.teams()NRG
player.agents()Kayo · 45%
player.matches()PlayerMatches
player.profile()PlayerProfile
resolving0 / 5 methods

Rate limiting

A good citizen by default

Three requests per second out of the box, with retries and exponential backoff.

1 second window0 / 3 sent
0.00idle
0.33idle
0.67idle
1.0next
window open3 req / sec

Concurrency

Parallel where it counts

Multi-stage endpoints fetch their pages in parallel with a thread pool.

event.stages()thread pool
stage 1
stage 2
stage 3
dispatched togetherjoined once

Timezones

Timezones, handled

VLR.gg renders times for a viewer. Set source_tz once and dates come back UTC-aware.

SeriesInfo.datetimeAmerica/New_York

VLR.gg

07:00 EDT

model

11:00 UTC

source_tz → UTCtz-aware

The namespaces

Every surface.
One import.

Bind an ID once, then query everything attached to it. Scroll through the full surface, or jump straight to a namespace.

Browse the full reference
01

Players

Profiles, career teams, agent stats, placements, and match history.

Player Profile
player.py
from vlrdevapi import VLRClient
with VLRClient() as client:
player = client.player(11225)
info = player.info()
teams = player.teams()
agents = player.agents(timespan="90d")
print(info.name, info.country)
print(teams.current_teams[0].name)
print(agents.agents[0].agent)
info()teams()agents()matches()placements()profile()

Player profile

Ethan

Ethan Arnold · United States

Player Info

Top agent · 90d

Kayo · 299 rounds

Rating

1.11

ACS

199.4

K / D

1.05

Kayo45%
Phoenix19%
Omen16%
Career winnings$645,700

Live VLR.gg snapshot · 2026-10-23

02

Teams

Rosters, staff, placements, prize money, and full match history.

Team Placements
team.py
from vlrdevapi import VLRClient
with VLRClient() as client:
team = client.team(1034)
print(team.info().name)
for member in team.roster().players:
print(member.ign, member.roles)
for placement in team.placements().placements[:3]:
print(placement.event_name)
print(placement.placements[0].placement)
info()roster()placements()transactions()stats()completed_matches()

Team profile

NRG

United States · 5 players · 3 staff

Team Roster
01Ethan
Captain
02keiko
Player
03brawk
Player
04mada
Player
05skuba
Player

Winnings

$2,050,375

Best result

Champions 2025 · 1st

Live VLR.gg snapshot · 2026-10-23

03

Series

Scores, map vetoes, round data, player stats, economy, and VODs.

Economy Data
series.py
from vlrdevapi import VLRClient
with VLRClient() as client:
series = client.series(542272)
info = series.info()
rounds = series.rounds(game_id=1)
economy = series.economy(game_id=1)
print(f"{info.team1.name} {info.score1}-{info.score2}")
print(len(rounds.rounds), "rounds")
print(economy.rounds[0].winner.name)
info()rounds()players()performance()economy()vods()

Series overview

NRG vs FNATIC

Valorant Champions 2025 · Grand Final

Series Info
NRG3
FNATIC2
Corrode13–3NRG
Lotus13–6FNC
Abyss13–15NRG
Ascent8–13FNC
Sunset13–5Decider
5 maps102 rounds6 VODs

Live VLR.gg snapshot · 2026-10-23

04

Events

Event metadata, stages, brackets, matches, and final standings.

Event Standings
event.py
from vlrdevapi import VLRClient
with VLRClient() as client:
event = client.event(2863)
print(event.info().name)
for stage in event.stages():
print(stage.name)
standings = event.standings()
for row in standings.stages[0].standings[:3]:
print(row.place, row.team.name)
info()stages()matches()teams()standings()

Event overview

VCT 2026: EMEA Stage 1

Germany · Apr 1 – May 17

Event Standings
PlayoffsMay 7 – May 17
Group StageApr 1 – May 1

Playoffs standings

1stTeam Heretics9 pts
2ndTeam Vitality6 pts
3rdFUT Esports7 pts

Live VLR.gg snapshot · 2026-10-23

05

News

The latest headlines and full articles, converted to clean Markdown.

News Article
news.py
from vlrdevapi import VLRClient
with VLRClient() as client:
page = client.news(page=1)
for article in page.news[:3]:
print(article.title)
full = client.news.article(page.news[0].id)
print(full.author, full.date)
print(full.content_md[:500])
news()news.article()

News article

Evil Geniuses to cease operations

By jenopelle · Oct 23

News Article

The villains bow out after a five-year run in Valorant.

content_md

Evil Geniuses has announced that it will cease competitive and day-to-day operations, effective November 2. The date coincides with the official end of VCT's 2026 contracts and the start of free agency ahead of the 2027 season. The statement from CEO Chris DeAppolonio shared the efforts taken by the org to continue operations, such as stabilizing operations,

United States18 links · Markdown preserved

Live VLR.gg snapshot · 2026-10-23

FAQ

Questions,
answered.

Keys, coverage, rate limits, and licensing. The full FAQ goes deeper on each of them.

Read the full FAQ
Is VLRdevAPI an official VLR.gg API?
No. VLRdevAPI is an independent, open-source Python client that reads publicly available pages on VLR.gg and converts them into typed models. It is not affiliated with, endorsed by, or supported by VLR.gg or Riot Games.
Do I need an API key or account?
No. Install the package and start making calls. There is no key, no signup, no billing, and no environment variable to configure before your first request.
Does it support async Python?
The client is intentionally synchronous to keep the dependency surface small and the call path predictable. In an async app, run calls in a worker thread or background task. Scripts, scheduled jobs, and data pipelines can use it directly.
How are rate limits handled?
Each client is rate limited to three requests per second by default, and you can change that with requests_per_second. Requests also retry automatically with exponential backoff, so temporary failures do not take down a job.
What data can I actually fetch?
Players, teams, matches, series, events, and news. That includes profiles and career history, rosters and placements, live and completed matches, map and round data, economy breakdowns, tournament stages and standings, plus full articles as Markdown.
Which Python versions are supported?
Python 3.11 and newer, including 3.12 through 3.14. The package is MIT licensed, so you can use it in commercial and open-source projects.

Get started

Install the SDK and query the data.

One package, six namespaces, no key. Start with the quickstart, then dig into the endpoint reference.

uv add vlrdevapi

MIT · Python 3.11+ · no API key