events.list_events()

Signature

import vlrdevapi as vlr

result = vlr.events.list_events(
    tier: EventTier | Literal["all", "vct", "vcl", "t3", "gc", "cg", "offseason"] = "all",
    region: str | None = None,
    status: EventStatus | Literal["all", "upcoming", "ongoing", "completed"] = "all",
    page: int = 1,
    limit: int | None = None,
    timeout: float = 5.0
) -> list[ListEvent]

Return Value

Type: list[ListEvent]

Returns a list of event summaries. Each ListEvent object contains:

Prop

Type

Examples

List VCT Events

List VCT events

import vlrdevapi as vlr
from vlrdevapi.events import EventTier, EventStatus

# Get ongoing VCT events
events = vlr.events.list_events(
    tier=EventTier.VCT,
    status=EventStatus.ONGOING,
    limit=10
)

for event in events:
    print(f"{event.name}")
    print(f"  Status: {event.status}")
    print(f"  Prize: {event.prize or 'TBD'}")
    print(f"  Region: {event.region or 'Global'}")

Browse with Pagination

Browse with pagination

import vlrdevapi as vlr

# Get page 2 of completed events
events = vlr.events.list_events(
    tier="gc",
    status="completed",
    page=2,
    limit=20
)

print(f"Found {len(events)} events on page 2")
for event in events:
    if event.start_date and event.end_date:
        duration = (event.end_date - event.start_date).days
        print(f"{event.name} - {duration} days")

Error Handling

Network failures: Returns an empty list []
Invalid parameters: Uses defaults (e.g., unknown tier defaults to VCT)
No results: Returns an empty list []

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

The list_events() function uses the info() function internally to obtain accurate dates with correct years. This fixes an issue where past events were incorrectly assigned the current year when only partial date information was available in the event listing.

The start_date and end_date fields are parsed from the event's date text and include the correct year, making them reliable for filtering and sorting events by date.