Skip to content
All guides
Guide

Getting Started with VLRdevAPI

Install the SDK, make your first API calls, and learn the core patterns — module access, client usage, and error handling.

This guide walks through everything you need to start using VLRdevAPI with real code examples.

Installation

pip install vlrdevapi
# or with uv (recommended)
uv add vlrdevapi

Requires Python 3.11+.

Quick Example

import vlrdevapi

matches = vlrdevapi.matches.upcoming()

for m in matches.matches[:5]:
    t1 = m.team1.name if m.team1 else "TBD"
    t2 = m.team2.name if m.team2 else "TBD"
    print(f"{t1} vs {t2}")

That's it. The library creates a default client automatically.

Module-Level Access

Every namespace is accessible directly from the module:

import vlrdevapi

# Matches
upcoming = vlrdevapi.matches.upcoming()
print(f"{len(upcoming.matches)} upcoming matches")

# Teams
team = vlrdevapi.team(2593)
print(team.info().name)
print(f"  Roster: {team.roster().players[0].ign}")

# Players
player = vlrdevapi.player(438)
print(f"Player: {player.info().name}")

# Events
stages = vlrdevapi.event(2765).stages()
print(f"Event stages: {len(stages)}")

# Series
info = vlrdevapi.series(670471).info()
print(f"Series: {info.team1.name} vs {info.team2.name}")

# News
page = vlrdevapi.news(page=1)
print(f"News items: {len(page.news)}")
first = vlrdevapi.news.article(page.news[0].id)
print(f"Article: {first.title} by {first.author}")

Using VLRClient

For more control, create an explicit client:

from vlrdevapi import VLRClient

with VLRClient(timeout=30, max_retries=5) as client:
    data = client.matches.upcoming(page=1)
    print(f"Found {len(data.matches)} matches")
    team = client.team.info(team_id=2593)
    print(f"Team: {team.name}")

The client supports context manager for proper resource cleanup.

Using Context Manager

from vlrdevapi import VLRClient

with VLRClient(timeout=30, requests_per_second=8) as client:
    live = client.matches.live()
    if live.matches:
        for m in live.matches:
            t1 = m.team1.name if m.team1 else "TBD"
            t2 = m.team2.name if m.team2 else "TBD"
            print(f"LIVE: {t1} vs {t2}")
    else:
        print("(no live matches currently)")

Error Handling

import vlrdevapi
from vlrdevapi.exceptions import NotFoundError, RateLimitError

try:
    team = vlrdevapi.team(2593).info()
    print(f"Team: {team.name}")
except NotFoundError:
    print("Team not found")
except RateLimitError:
    print("Rate limited — waiting...")

Pagination

List endpoints return paginated results:

page = vlrdevapi.matches.upcoming(page=1)
print(f"Found {len(page.matches)} matches on this page")
print(f"More pages: {page.has_next_page}")
for m in page.matches[:3]:
    t1 = m.team1.name if m.team1 else "TBD"
    t2 = m.team2.name if m.team2 else "TBD"
    print(f"{t1} vs {t2}")

Next Steps

Next step

Ready to build with VLRdevAPI?

Install the Python SDK and start fetching Valorant esports data in minutes. No API key required.

uv add vlrdevapi
Read the docs