Events API

The events module provides access to Valorant esports events, tournaments, and competitions.

Overview

Access VCT Champions, VCT Masters, regional leagues, Game Changers tournaments, and other Valorant esports events. Get event details, matches, and standings.

Event-related API endpoints and models.

This module provides access to: - events.list_events(): List all events with filters - events.Info: Get event header/info - events.Matches: Get event matches - events.MatchSummary: Get event matches summary - events.Standings: Get event standings - events.Teams: Get event teams

class vlrdevapi.events.EventTier(value)[source]

Bases: str, Enum

Event tier options.

ALL = 'all'

VCT = 'vct'

VCL = 'vcl'

T3 = 't3'

GC = 'gc'

CG = 'cg'

OFFSEASON = 'offseason'

class vlrdevapi.events.EventStatus(value)[source]

Bases: str, Enum

Event status filter options.

ALL = 'all'

UPCOMING = 'upcoming'

ONGOING = 'ongoing'

COMPLETED = 'completed'

class vlrdevapi.events.ListEvent(id: int, name: str, status: Literal['upcoming', 'ongoing', 'completed'], url: str, region: str | None = None, start_date: date | None = None, end_date: date | None = None, start_text: str | None = None, end_text: str | None = None, prize: str | None = None)[source]

Bases: object

Event summary from events listing.

id: int

name: str

status: Literal['upcoming', 'ongoing', 'completed']

url: str

region: str | None = None

start_date: date | None = None

end_date: date | None = None

start_text: str | None = None

end_text: str | None = None

prize: str | None = None

__init__(id: int, name: str, status: Literal['upcoming', 'ongoing', 'completed'], url: str, region: str | None = None, start_date: date | None = None, end_date: date | None = None, start_text: str | None = None, end_text: str | None = None, prize: str | None = None) → None

Bases: object

Event header/info details.

id: int

name: str

subtitle: str | None = None

date_text: str | None = None

start_date: date | None = None

end_date: date | None = None

prize: str | None = None

location: str | None = None

regions: list[str]

__init__(id: int, name: str, subtitle: str | None = None, date_text: str | None = None, start_date: date | None = None, end_date: date | None = None, prize: str | None = None, location: str | None = None, regions: list[str] = <factory>) → None

class vlrdevapi.events.MatchTeam(name: str, id: int | None = None, country: str | None = None, score: int | None = None, is_winner: bool | None = None)[source]

Bases: object

Team in an event match.

name: str

id: int | None = None

country: str | None = None

score: int | None = None

is_winner: bool | None = None

__init__(name: str, id: int | None = None, country: str | None = None, score: int | None = None, is_winner: bool | None = None) → None

class vlrdevapi.events.Match(match_id: int, event_id: int, status: str, teams: tuple[MatchTeam, MatchTeam], url: str, stage: str | None = None, phase: str | None = None, date: date | None = None, time: str | None = None)[source]

Bases: object

Event match entry.

match_id: int

event_id: int

status: str

teams: tuple[MatchTeam, MatchTeam]

url: str

stage: str | None = None

phase: str | None = None

date: date | None = None

time: str | None = None

__init__(match_id: int, event_id: int, status: str, teams: tuple[MatchTeam, MatchTeam], url: str, stage: str | None = None, phase: str | None = None, date: date | None = None, time: str | None = None) → None

class vlrdevapi.events.StageMatches(name: str, match_count: int, completed: int, upcoming: int, ongoing: int, start_date: date | None = None, end_date: date | None = None)[source]

Bases: object

Match summary for a stage.

name: str

match_count: int

completed: int

upcoming: int

ongoing: int

start_date: date | None = None

end_date: date | None = None

__init__(name: str, match_count: int, completed: int, upcoming: int, ongoing: int, start_date: date | None = None, end_date: date | None = None) → None

class vlrdevapi.events.MatchSummary(event_id: int, total_matches: int, completed: int, upcoming: int, ongoing: int, stages: list[StageMatches] = <factory>)[source]

Bases: object

Event matches summary.

event_id: int

total_matches: int

completed: int

upcoming: int

ongoing: int

stages: list[StageMatches]

__init__(event_id: int, total_matches: int, completed: int, upcoming: int, ongoing: int, stages: list[StageMatches] = <factory>) → None

Bases: object

Single standing entry.

place: str

prize: str | None = None

team_id: int | None = None

team_name: str | None = None

team_country: str | None = None

note: str | None = None

__init__(place: str, prize: str | None = None, team_id: int | None = None, team_name: str | None = None, team_country: str | None = None, note: str | None = None) → None

class vlrdevapi.events.Standings(event_id: int, stage_path: str, url: str, entries: list[StandingEntry] = <factory>)[source]

Bases: object

Event standings.

event_id: int

stage_path: str

url: str

entries: list[StandingEntry]

__init__(event_id: int, stage_path: str, url: str, entries: list[StandingEntry] = <factory>) → None

class vlrdevapi.events.EventStage(name: str, series_id: str, url: str)[source]

Bases: object

Available stage option for an event matches page.

name: str

series_id: str

url: str

__init__(name: str, series_id: str, url: str) → None

class vlrdevapi.events.Team(id: int, name: str, type: str | None = None)[source]

Bases: object

Team information for an event.

id: int

name: str

type: str | None = None

__init__(id: int, name: str, type: str | None = None) → None

vlrdevapi.events.list_events(tier: EventTier | Literal['all', 'vct', 'vcl', 't3', 'gc', 'cg', 'offseason'] = EventTier.ALL, region: str | None = None, status: EventStatus | Literal['all', 'upcoming', 'ongoing', 'completed'] = EventStatus.ALL, page: int = 1, limit: int | None = None, timeout: float | None = None) → list[ListEvent][source]

List events with filters.

Parameters:

tier – Event tier (use EventTier enum or string)
region – Region filter (optional)
status – Event status (use EventStatus enum or string)
page – Page number (1-indexed)
limit – Maximum number of events to return (optional)
timeout – Request timeout in seconds

Returns:

List of events

Example

>>> import vlrdevapi as vlr
>>> from vlrdevapi.events import EventTier, EventStatus
>>> events = vlr.events.list_events(tier=EventTier.VCT, status=EventStatus.ONGOING, limit=10)
>>> for event in events:
...     print(f"{event.name} - {event.status}")

vlrdevapi.events.info(event_id: int, timeout: float | None = None) → Info | None[source]

Get event header/info.

Parameters:

event_id – Event ID
timeout – Request timeout in seconds

Returns:

Event info or None if not found

Example

>>> import vlrdevapi as vlr
>>> event_info = vlr.events.info(event_id=123)
>>> print(f"{event_info.name} - {event_info.prize}")

vlrdevapi.events.matches(event_id: int, stage: str | None = None, limit: int | None = None, timeout: float | None = None) → list[Match][source]

Get event matches with team IDs.

Parameters:

event_id – Event ID
stage – Stage filter (optional)
limit – Maximum number of matches to return (optional)
timeout – Request timeout in seconds

Returns:

List of event matches with team IDs extracted from match pages

Example

>>> import vlrdevapi as vlr
>>> matches = vlr.events.matches(event_id=123, limit=20)
>>> for match in matches:
...     print(f"{match.teams[0].name} (ID: {match.teams[0].id}) vs {match.teams[1].name} (ID: {match.teams[1].id})")

vlrdevapi.events.match_summary(event_id: int, timeout: float | None = None) → MatchSummary | None[source]

Get event match summary.

Parameters:

event_id – Event ID
timeout – Request timeout in seconds

Returns:

Match summary or None if not found

Example

>>> import vlrdevapi as vlr
>>> summary = vlr.events.match_summary(event_id=123)
>>> print(f"Total: {summary.total_matches}, Completed: {summary.completed}")

vlrdevapi.events.standings(event_id: int, stage: str | None = None, timeout: float | None = None) → Standings | None[source]

Get event standings.

Parameters:

event_id – Event ID
stage – Stage filter (optional)
timeout – Request timeout in seconds

Returns:

Standings or None if not found

Example

>>> import vlrdevapi as vlr
>>> standings = vlr.events.standings(event_id=123)
>>> for entry in standings.entries:
...     print(f"{entry.place}. {entry.team_name} - {entry.prize}")

vlrdevapi.events.stages(event_id: int, timeout: float | None = None) → list[EventStage][source]

List available stages for an event’s matches page.

Returns a list of stage options with their series_id and URL. The special “All Stages” option will have series_id=”all”.

vlrdevapi.events.teams(event_id: int, timeout: float | None = None) → list[Team][source]

Get teams participating in an event.

Parameters:

event_id – Event ID
timeout – Request timeout in seconds

Returns:

List of teams in the event

Example

>>> import vlrdevapi as vlr
>>> teams = vlr.events.teams(event_id=123)
>>> for team in teams:
...     print(f"{team.name} (ID: {team.id}) - Type: {team.type}")

Functions

info

vlrdevapi.events.info(event_id: int, timeout: float | None = None) → Info | None[source]

Get event header/info.

Parameters:

event_id – Event ID
timeout – Request timeout in seconds

Returns:

Event info or None if not found

Example

>>> import vlrdevapi as vlr
>>> event_info = vlr.events.info(event_id=123)
>>> print(f"{event_info.name} - {event_info.prize}")

list_events

vlrdevapi.events.list_events(tier: EventTier | Literal['all', 'vct', 'vcl', 't3', 'gc', 'cg', 'offseason'] = EventTier.ALL, region: str | None = None, status: EventStatus | Literal['all', 'upcoming', 'ongoing', 'completed'] = EventStatus.ALL, page: int = 1, limit: int | None = None, timeout: float | None = None) → list[ListEvent][source]

List events with filters.

Parameters:

tier – Event tier (use EventTier enum or string)
region – Region filter (optional)
status – Event status (use EventStatus enum or string)
page – Page number (1-indexed)
limit – Maximum number of events to return (optional)
timeout – Request timeout in seconds

Returns:

List of events

Example

>>> import vlrdevapi as vlr
>>> from vlrdevapi.events import EventTier, EventStatus
>>> events = vlr.events.list_events(tier=EventTier.VCT, status=EventStatus.ONGOING, limit=10)
>>> for event in events:
...     print(f"{event.name} - {event.status}")

match_summary

vlrdevapi.events.match_summary(event_id: int, timeout: float | None = None) → MatchSummary | None[source]

Get event match summary.

Parameters:

event_id – Event ID
timeout – Request timeout in seconds

Returns:

Match summary or None if not found

Example

>>> import vlrdevapi as vlr
>>> summary = vlr.events.match_summary(event_id=123)
>>> print(f"Total: {summary.total_matches}, Completed: {summary.completed}")

matches

vlrdevapi.events.matches(event_id: int, stage: str | None = None, limit: int | None = None, timeout: float | None = None) → list[Match][source]

Get event matches with team IDs.

Parameters:

event_id – Event ID
stage – Stage filter (optional)
limit – Maximum number of matches to return (optional)
timeout – Request timeout in seconds

Returns:

List of event matches with team IDs extracted from match pages

Example

>>> import vlrdevapi as vlr
>>> matches = vlr.events.matches(event_id=123, limit=20)
>>> for match in matches:
...     print(f"{match.teams[0].name} (ID: {match.teams[0].id}) vs {match.teams[1].name} (ID: {match.teams[1].id})")

stages

vlrdevapi.events.stages(event_id: int, timeout: float | None = None) → list[EventStage][source]

List available stages for an event’s matches page.

Returns a list of stage options with their series_id and URL. The special “All Stages” option will have series_id=”all”.

standings

vlrdevapi.events.standings(event_id: int, stage: str | None = None, timeout: float | None = None) → Standings | None[source]

Get event standings.

Parameters:

event_id – Event ID
stage – Stage filter (optional)
timeout – Request timeout in seconds

Returns:

Standings or None if not found

Example

>>> import vlrdevapi as vlr
>>> standings = vlr.events.standings(event_id=123)
>>> for entry in standings.entries:
...     print(f"{entry.place}. {entry.team_name} - {entry.prize}")

teams

vlrdevapi.events.teams(event_id: int, timeout: float | None = None) → list[Team][source]

Get teams participating in an event.

Parameters:

event_id – Event ID
timeout – Request timeout in seconds

Returns:

List of teams in the event

Example

>>> import vlrdevapi as vlr
>>> teams = vlr.events.teams(event_id=123)
>>> for team in teams:
...     print(f"{team.name} (ID: {team.id}) - Type: {team.type}")

Enums

EventTier

class vlrdevapi.events.EventTier(value)[source]

Event tier options.

ALL = 'all'

VCT = 'vct'

VCL = 'vcl'

T3 = 't3'

GC = 'gc'

CG = 'cg'

OFFSEASON = 'offseason'

EventStatus

class vlrdevapi.events.EventStatus(value)[source]

Event status filter options.

ALL = 'all'

UPCOMING = 'upcoming'

ONGOING = 'ongoing'

COMPLETED = 'completed'

Data Models

EventStage

class vlrdevapi.events.EventStage(name: str, series_id: str, url: str)[source]

Available stage option for an event matches page.

name: str

series_id: str

url: str

__init__(name: str, series_id: str, url: str) → None

Info

Event header/info details.

id: int

name: str

subtitle: str | None = None

date_text: str | None = None

start_date: date | None = None

end_date: date | None = None

prize: str | None = None

location: str | None = None

regions: list[str]

__init__(id: int, name: str, subtitle: str | None = None, date_text: str | None = None, start_date: date | None = None, end_date: date | None = None, prize: str | None = None, location: str | None = None, regions: list[str] = <factory>) → None

ListEvent

class vlrdevapi.events.ListEvent(id: int, name: str, status: Literal['upcoming', 'ongoing', 'completed'], url: str, region: str | None = None, start_date: date | None = None, end_date: date | None = None, start_text: str | None = None, end_text: str | None = None, prize: str | None = None)[source]

Event summary from events listing.

id: int

name: str

status: Literal['upcoming', 'ongoing', 'completed']

url: str

region: str | None = None

start_date: date | None = None

end_date: date | None = None

start_text: str | None = None

end_text: str | None = None

prize: str | None = None

__init__(id: int, name: str, status: Literal['upcoming', 'ongoing', 'completed'], url: str, region: str | None = None, start_date: date | None = None, end_date: date | None = None, start_text: str | None = None, end_text: str | None = None, prize: str | None = None) → None

Match

class vlrdevapi.events.Match(match_id: int, event_id: int, status: str, teams: tuple[MatchTeam, MatchTeam], url: str, stage: str | None = None, phase: str | None = None, date: date | None = None, time: str | None = None)[source]

Event match entry.

match_id: int

event_id: int

status: str

teams: tuple[MatchTeam, MatchTeam]

url: str

stage: str | None = None

phase: str | None = None

date: date | None = None

time: str | None = None

__init__(match_id: int, event_id: int, status: str, teams: tuple[MatchTeam, MatchTeam], url: str, stage: str | None = None, phase: str | None = None, date: date | None = None, time: str | None = None) → None

MatchSummary

class vlrdevapi.events.MatchSummary(event_id: int, total_matches: int, completed: int, upcoming: int, ongoing: int, stages: list[StageMatches] = <factory>)[source]

Event matches summary.

event_id: int

total_matches: int

completed: int

upcoming: int

ongoing: int

stages: list[StageMatches]

__init__(event_id: int, total_matches: int, completed: int, upcoming: int, ongoing: int, stages: list[StageMatches] = <factory>) → None

MatchTeam

class vlrdevapi.events.MatchTeam(name: str, id: int | None = None, country: str | None = None, score: int | None = None, is_winner: bool | None = None)[source]

Team in an event match.

name: str

id: int | None = None

country: str | None = None

score: int | None = None

is_winner: bool | None = None

__init__(name: str, id: int | None = None, country: str | None = None, score: int | None = None, is_winner: bool | None = None) → None

StageMatches

class vlrdevapi.events.StageMatches(name: str, match_count: int, completed: int, upcoming: int, ongoing: int, start_date: date | None = None, end_date: date | None = None)[source]

Match summary for a stage.

name: str

match_count: int

completed: int

upcoming: int

ongoing: int

start_date: date | None = None

end_date: date | None = None

__init__(name: str, match_count: int, completed: int, upcoming: int, ongoing: int, start_date: date | None = None, end_date: date | None = None) → None

StandingEntry

Single standing entry.

place: str

prize: str | None = None

team_id: int | None = None

team_name: str | None = None

team_country: str | None = None

note: str | None = None

__init__(place: str, prize: str | None = None, team_id: int | None = None, team_name: str | None = None, team_country: str | None = None, note: str | None = None) → None

Standings

class vlrdevapi.events.Standings(event_id: int, stage_path: str, url: str, entries: list[StandingEntry] = <factory>)[source]

Event standings.

event_id: int

stage_path: str

url: str

entries: list[StandingEntry]

__init__(event_id: int, stage_path: str, url: str, entries: list[StandingEntry] = <factory>) → None

Team

class vlrdevapi.events.Team(id: int, name: str, type: str | None = None)[source]

Team information for an event.

id: int

name: str

type: str | None = None

__init__(id: int, name: str, type: str | None = None) → None

Usage Examples

List Events

import vlrdevapi as vlr

# List all VCT events
events = vlr.events.list_events(tier="vct")

# Filter by status
ongoing = vlr.events.list_events(tier="vct", status="ongoing")

# Filter by region
na_events = vlr.events.list_events(tier="vct", region="na")

Get Event Details

import vlrdevapi as vlr

# Get event information
info = vlr.events.info(event_id=2283)
print(f"{info.name}")
print(f"Prize: {info.prize}")
print(f"Location: {info.location}")

# Access parsed dates
if info.start_date:
    print(f"Start Date: {info.start_date}")
if info.end_date:
    print(f"End Date: {info.end_date}")

Get Event Matches

import vlrdevapi as vlr

# Get all matches for an event
matches = vlr.events.matches(event_id=2498)

for match in matches:
    print(f"{match.teams[0].name} vs {match.teams[1].name}")
    print(f"Status: {match.status}")

Get Event Standings

import vlrdevapi as vlr

# Get event standings/prize distribution
standings = vlr.events.standings(event_id=2498)

for entry in standings.entries:
    print(f"{entry.place}. {entry.team_name}")
    if entry.prize:
        print(f"   Prize: {entry.prize}")

Get Event Teams

import vlrdevapi as vlr

# Get teams participating in an event
teams = vlr.events.teams(event_id=2682)

for team in teams:
    print(f"{team.name} (ID: {team.id})")
    if team.type:
        print(f"  Type: {team.type}")

See more examples: Usage Examples