Events API Overview

The Events namespace provides access to Valorant tournament data from vlr.gg - listing events, fetching metadata, stages, teams, matches, and standings.

The Events API is the entry point for all tournament-related data. It is accessed via vlrdevapi.event(id) (curried access) or through an explicit VLRClient instance.

All sub-namespaces are lazily initialized and share the same HTTP client configuration, timeout, retry, and rate-limiting settings.

Access Patterns

Module-level (default client)

import vlrdevapi

# List/browse events
events = vlrdevapi.event.list(tier="vct", region="americas")
print(f"Found {len(events.events)} VCT Americas events")

# Curried access - pass ID once, chain methods
event = vlrdevapi.event(2765)
info = event.info()
print(f"Event: {info.name}")
stages = event.stages()
print(f"Stages: {len(stages)}")
matches = event.matches()
print(f"Matches: {len(matches.matches)}")

Explicit client

from vlrdevapi import VLRClient

with VLRClient(timeout=30, requests_per_second=8) as client:
    e = client.event(2765)
    info = e.info()
    print(f"Event: {info.name}")
    print(f"Prize: {info.prize.raw_text if info.prize else 'N/A'}")

Sub-namespace Reference

Method	Returns	Description
`event.list(tier, region, status, ...)`	`EventList`	Browse and search events with tier/region/status/date filters
`event.info(event_id)`	`EventInfo`	Metadata for a specific event
`event.stages(event_id)`	`EventStages`	Stage breakdown with dates
`event.teams(event_id, stage)`	`EventTeams`	Teams per stage
`event.matches(event_id, stage_id, state)`	`EventMatches`	Match list with filtering
`event.standings(event_id, stage)`	`EventStandings`	Standings per stage

Common Error Handling

All event methods raise typed exceptions from vlrdevapi.exceptions:

Exception	Raised When
`ValidationError`	Invalid arguments (bad `event_id`, tier, region, etc.)
`NotFoundError`	Event page doesn't exist (HTTP 404)
`RequestError`	Network failure or HTTP error
`RateLimitError`	Too many requests (HTTP 429)
`ParsingError`	Page structure is unrecognised
`DataNotFoundError`	Data is semantically absent from the page

import vlrdevapi
from vlrdevapi.exceptions import NotFoundError, ParsingError

try:
    info = vlrdevapi.event(2765).info()
    print(f"Event loaded: {info.name}")
except NotFoundError:
    print("Event not found")
except ParsingError as e:
    print(f"Failed to parse: {e}")