VlrDevApi

matches.completed()

Get completed matches with scores

Signature

import vlrdevapi as vlr

result = vlr.matches.completed(
    limit: int | None = None,
    page: int | None = None,
    timeout: float = 5.0
) -> list[Match]

Parameters

Prop

Type

Return Value

Type: list[Match]

Returns a list of completed matches with scores. Each Match object contains:

Prop

Type

Team fields:

Prop

Type

Examples

Get Completed Matches

Get completed matches
import vlrdevapi as vlr

# Get recent completed matches
matches = vlr.matches.completed(limit=10)

for m in matches:
    score = f"{m.team1.score}-{m.team2.score}" if m.team1.score is not None else "N/A"
    print(f"{m.event} - {m.event_phase}")
    print(f"  {m.team1.name} vs {m.team2.name}")
    print(f"  Score: {score}")

Browse with Pagination

Browse with pagination
import vlrdevapi as vlr

# Get page 2 of completed matches
matches = vlr.matches.completed(page=2)

print(f"Found {len(matches)} matches on page 2")
for m in matches:
    if m.team1.score is not None and m.team2.score is not None:
        print(f"{m.team1.name} {m.team1.score}-{m.team2.score} {m.team2.name}")

Analyze Match Results

Analyze match results
import vlrdevapi as vlr
from collections import Counter

# Get recent matches
matches = vlr.matches.completed(limit=50)

# Count wins per team
team_wins = Counter()
for m in matches:
    if m.team1.score is not None and m.team2.score is not None:
        if m.team1.score > m.team2.score:
            team_wins[m.team1.name] += 1
        elif m.team2.score > m.team1.score:
            team_wins[m.team2.name] += 1

# Show top teams
print("Top teams by recent wins:")
for team, wins in team_wins.most_common(5):
    print(f"{team}: {wins} wins")

Get Detailed Match Info

Get detailed match info
import vlrdevapi as vlr

# Get completed matches and fetch detailed info
matches = vlr.matches.completed(limit=5)

for m in matches:
    print(f"\nMatch {m.match_id}: {m.team1.name} vs {m.team2.name}")
    print(f"Score: {m.team1.score}-{m.team2.score}")
    
    # Get detailed map-by-map stats
    # series_info = vlr.series.info(m.match_id)
    # if series_info:
    #     for map_data in series_info.maps:
    #         print(f"  {map_data.map_name}: {map_data.team1_score}-{map_data.team2_score}")

Filter by Event

Filter by event
import vlrdevapi as vlr

# Get completed matches and filter
matches = vlr.matches.completed(limit=100)

# Filter for specific event
vct_matches = [m for m in matches if "VCT" in m.event]

print(f"VCT completed matches: {len(vct_matches)}")
for m in vct_matches:
    score = f"{m.team1.score}-{m.team2.score}" if m.team1.score is not None else "N/A"
    print(f"{m.event}: {m.team1.name} vs {m.team2.name} ({score})")

Error Handling

  • Network failures: Returns an empty list []
  • No matches found: Returns an empty list []
  • Missing scores: score fields can be None (check before using)

The function never raises exceptions, making it safe to use without try-catch blocks.

Tips

  • Scores represent maps won, not rounds
  • Combine with series.info(match_id) for detailed per-map statistics
  • Team IDs are enriched by quickly opening the match header (cached)
  • Use pagination to browse through historical matches
  • The status field will always be "completed" for this endpoint

Source

Data scraped from: https://www.vlr.gg/matches/results