Event Matches

event.matches(event_id) returns matches for an event with flexible filtering by stage and match status. Team IDs are enriched in parallel via series info lookups.

Signature

event.matches(
    event_id: int,
    stage_id: str | None = None,
    state: Literal["all", "completed", "live", "upcoming"] = "all",
) -> EventMatches

Parameters

Returns - EventMatches

EventMatch Fields

MatchTeam Fields

MatchStatus Enum

Team ID Enrichment

After parsing, each match's team IDs are enriched by fetching series info in parallel (up to 5 concurrent requests). This ensures team IDs are populated even when they aren't directly available from the event matches page.

• If enrichment fails for a particular match (e.g. the series page doesn't exist), a debug log is emitted and the team IDs remain as-is.
• Enrichment failures do not propagate exceptions to the caller.

Examples

All matches

Fetch every match for the event regardless of stage or status. Each EventMatch contains two MatchTeam entries representing the competing teams, along with stage and phase information.

import vlrdevapi

matches = vlrdevapi.event(2765).matches()
for match in matches.matches:
    t1, t2 = match.teams[0], match.teams[1]
    print(f"{match.phase}: {t1.name} vs {t2.name}")

Filter matches by stage

Combine event.stages() with event.matches() to fetch matches for a specific tournament stage. First retrieve the available stages, then pass the stage's id as the stage_id parameter. This is useful for building stage-specific match schedules.

import vlrdevapi

stages = vlrdevapi.event(2765).stages()
stage_matches = vlrdevapi.event(2765).matches(stage_id=stages[0].id)
for match in stage_matches.matches:
    print(f"[{match.stage}] {match.teams[0].name} vs {match.teams[1].name}")

Filter matches by status

Use the state parameter to filter matches by their current status. This is helpful for displaying different sections of a tournament page - upcoming matches, currently live matches, and completed results.

import vlrdevapi

completed = vlrdevapi.event(2765).matches(state="completed")
print(f"Completed: {len(completed.matches)} matches")

upcoming = vlrdevapi.event(2765).matches(state="upcoming")
print(f"Upcoming: {len(upcoming.matches)} matches")

Match details with scores

For completed matches, each team has a score and a winner flag. Use these fields to display results. The match_date and datetime_utc fields provide scheduling information, while match_id can be used to link to the detailed series page.

import vlrdevapi

matches = vlrdevapi.event(2765).matches(state="completed")
for match in matches.matches[:3]:
    print(f"Match ID: {match.match_id}")
    print(f"Date: {match.match_date}")
    for team in match.teams:
        winner_tag = " (Winner)" if team.winner else ""
        print(f"  {team.name} - Score: {team.score}{winner_tag}")
    print()