Event List

vlrdevapi.event.list() returns paginated event listings from vlr.gg with support for tier, region, status, and pagination.

Signature

event.list(
    tier: TierType = "all",
    region: RegionType = "all",
    status: StatusType | None = None,
    page: int = 1,
    max_page: int = 0,
    return_all: bool = False,
) -> EventList

Parameters

Prop

Type

Returns - `EventList`

Prop

Type

`EventListItem` Fields

Prop

Type

Tier Mappings

Value	Maps To
`"all"`	No filter
`"vct"`	VCT events
`"vcl"`	VCL / Challengers
`"t3"`	Tier 3
`"gc"`	Game Changers
`"collegiate"`	Collegiate
`"offseason"`	Off-season / events

Region Mappings

Value	Maps To
`"all"`	No filter
`"americas"` / `"amer"`	Americas
`"emea"`	EMEA
`"pacific"` / `"pac"`	Pacific
`"china"`	China

Examples

Basic listing

Fetch all available events without any filters. The response includes the event name, dates, and status for each event on the first page.

import vlrdevapi

events = vlrdevapi.event.list()
for e in events.events:
    dates = f"{e.start_date} - {e.end_date}" if e.start_date and e.end_date else "TBD"
    print(f"{e.name} ({dates})")

Filter by status

Use the status parameter to show only events in a specific state. Common values are "upcoming" for future events, "ongoing" for events currently being played, and "completed" for past events.

import vlrdevapi

upcoming_events = vlrdevapi.event.list(status="upcoming")
print(f"Found {len(upcoming_events.events)} upcoming events")
for e in upcoming_events.events:
    print(f"{e.name} ({e.status})")

Filter by tier and region

Combine tier and region to narrow down to specific competitive levels in specific parts of the world. For example, to find all VCT events in the Americas region:

import vlrdevapi

vct_americas = vlrdevapi.event.list(tier="vct", region="americas")
for e in vct_americas.events:
    print(f"{e.name} - {e.region} - {e.status}")

Pagination

Results are paginated. Use the page parameter to navigate through pages, or set return_all=True to collect all results automatically.

import vlrdevapi

page_2 = vlrdevapi.event.list(page=2)
print(f"Found {len(page_2.events)} events on page 2")
for e in page_2.events:
    prize = e.prize.raw_text if e.prize else "(no prize listed)"
    print(f"{e.name} | Prize: {prize}")

Fetch all pages

Use return_all=True to paginate through all available pages and collect every event.

import vlrdevapi

all_events = vlrdevapi.event.list(return_all=True)
print(f"Total events: {len(all_events.events)}")
for e in all_events.events[:5]:
    print(f"{e.name} ({e.region})")

On this page