Matches API

The matches module provides access to match schedules and results including upcoming, live, and completed matches.

Overview

Track Valorant esports matches across all tournaments and events. Get real-time updates on live matches, upcoming schedules, and historical results.

Match-related API endpoints and models.

class vlrdevapi.matches.Team(name: str, id: int | None = None, country: str | None = None, score: int | None = None)[source]

Bases: object

Represents a team in a match.

name: str

id: int | None = None

country: str | None = None

score: int | None = None

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

class vlrdevapi.matches.Match(match_id: int, team1: Team, team2: Team, event_phase: str, event: str, time: str, status: Literal['upcoming', 'live', 'completed'], date: date | None = None)[source]

Bases: object

Represents a match summary.

match_id: int

team1: Team

team2: Team

event_phase: str

event: str

time: str

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

date: date | None = None

__init__(match_id: int, team1: Team, team2: Team, event_phase: str, event: str, time: str, status: Literal['upcoming', 'live', 'completed'], date: date | None = None) → None

vlrdevapi.matches.upcoming(limit: int | None = None, page: int | None = None, timeout: float | None = None) → list[Match][source]

Get upcoming matches.

Parameters:

limit – Maximum number of matches to return (optional)
page – Page number (1-indexed, optional)
timeout – Request timeout in seconds

Returns:

List of upcoming matches. Each match includes team1 and team2 with name, country, score, and team id. Team IDs are populated by quickly opening the match header and may be None for TBD/unknown teams.

Example

>>> import vlrdevapi as vlr
>>> matches = vlr.matches.upcoming(limit=10)
>>> for match in matches:
...     print(f"{match.team1.name} vs {match.team2.name}")
...     print(f"  {match.team1.country} vs {match.team2.country}")
>>> # Team IDs may be None if a team is TBD
>>> ids = (match.team1.id, match.team2.id)

vlrdevapi.matches.completed(limit: int | None = None, page: int | None = None, timeout: float | None = None) → list[Match][source]

Get completed matches.

Parameters:

limit – Maximum number of matches to return (optional)
page – Page number (1-indexed, optional)
timeout – Request timeout in seconds

Returns:

List of completed matches with scores.

Example

>>> import vlrdevapi as vlr
>>> matches = vlr.matches.completed(limit=10)
>>> for match in matches:
...     score = f"{match.team1.score}-{match.team2.score}"
...     print(f"{match.team1.name} vs {match.team2.name} - {score}")

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

Get live matches.

Parameters:

limit – Maximum number of matches to return (optional)
timeout – Request timeout in seconds

Returns:

List of live matches.

Example

>>> import vlrdevapi as vlr
>>> matches = vlr.matches.live()
>>> for match in matches:
...     print(f"LIVE: {match.team1.name} vs {match.team2.name}")

Functions

upcoming

Get upcoming scheduled matches.

vlrdevapi.matches.upcoming(limit: int | None = None, page: int | None = None, timeout: float | None = None) → list[Match][source]

Get upcoming matches.

Parameters:

limit – Maximum number of matches to return (optional)
page – Page number (1-indexed, optional)
timeout – Request timeout in seconds

Returns:

List of upcoming matches. Each match includes team1 and team2 with name, country, score, and team id. Team IDs are populated by quickly opening the match header and may be None for TBD/unknown teams.

Example

>>> import vlrdevapi as vlr
>>> matches = vlr.matches.upcoming(limit=10)
>>> for match in matches:
...     print(f"{match.team1.name} vs {match.team2.name}")
...     print(f"  {match.team1.country} vs {match.team2.country}")
>>> # Team IDs may be None if a team is TBD
>>> ids = (match.team1.id, match.team2.id)

live

Get currently live matches. Supports an optional limit parameter to cap the number of returned matches (capped internally at 500 for consistency with other endpoints).

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

Get live matches.

Parameters:

limit – Maximum number of matches to return (optional)
timeout – Request timeout in seconds

Returns:

List of live matches.

Example

>>> import vlrdevapi as vlr
>>> matches = vlr.matches.live()
>>> for match in matches:
...     print(f"LIVE: {match.team1.name} vs {match.team2.name}")

completed

Get recently completed matches.

vlrdevapi.matches.completed(limit: int | None = None, page: int | None = None, timeout: float | None = None) → list[Match][source]

Get completed matches.

Parameters:

limit – Maximum number of matches to return (optional)
page – Page number (1-indexed, optional)
timeout – Request timeout in seconds

Returns:

List of completed matches with scores.

Example

>>> import vlrdevapi as vlr
>>> matches = vlr.matches.completed(limit=10)
>>> for match in matches:
...     score = f"{match.team1.score}-{match.team2.score}"
...     print(f"{match.team1.name} vs {match.team2.name} - {score}")

Data Models

Team

Team information in a match including name, ID, country, and score.

class vlrdevapi.matches.Team(name: str, id: int | None = None, country: str | None = None, score: int | None = None)[source]

Represents a team in a match.

name: str

id: int | None = None

country: str | None = None

score: int | None = None

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

Match

Match information including teams, scores, and event details.

class vlrdevapi.matches.Match(match_id: int, team1: Team, team2: Team, event_phase: str, event: str, time: str, status: Literal['upcoming', 'live', 'completed'], date: date | None = None)[source]

Represents a match summary.

match_id: int

team1: Team

team2: Team

event_phase: str

event: str

time: str

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

date: date | None = None

__init__(match_id: int, team1: Team, team2: Team, event_phase: str, event: str, time: str, status: Literal['upcoming', 'live', 'completed'], date: date | None = None) → None

Examples

Upcoming Matches

import vlrdevapi as vlr
matches = vlr.matches.upcoming(limit=5)
for m in matches:
    print(f"{m.team1.name} vs {m.team2.name} - {m.event}")

Live Matches

import vlrdevapi as vlr
live = vlr.matches.live(limit=3)
for m in live:
    print(f"LIVE: {m.team1.name} vs {m.team2.name}")

Completed Matches

import vlrdevapi as vlr
results = vlr.matches.completed(limit=5)
for m in results:
    print(f"{m.team1.name} {m.team1.score}-{m.team2.score} {m.team2.name}")

See more examples: Usage Examples