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
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
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
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
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
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 beNone
(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
Related
Source
Data scraped from: https://www.vlr.gg/matches/results