Client¶

The StartGGClient is the primary entry point for fetching data from the start.gg GraphQL API. It handles authentication, rate limiting and exponential-backoff retries on transient failures.

class lptk.StartGGClient¶

Bases: object

Client for the start.gg GraphQL API.

This client provides methods for fetching tournament data including event information, standings, phases, and match details.

api_url¶: The GraphQL API endpoint URL.

rate_limit_delay¶: Delay between API calls in seconds.

Example

>>> with StartGGClient() as client:
...     event_id, name = client.get_event_id("tournament/xyz/event/abc")
...     teams = client.get_event_standings(event_id, top_n=16)

__init__(token=None, session=None)¶

Initialize the StartGG client.

Parameters:

token (str | None (default: None)) – API bearer token. If not provided, loaded from config.
session (Session | None (default: None)) – Optional requests session for connection pooling.

Raises:

ConfigurationError – If token is not provided and not found in config.

close()¶

Close the HTTP session if we own it.

Return type:: None

get_event_id(slug)¶

Get event ID and name from a slug.

Parameters:: slug (str) – Event URL slug (e.g., “tournament/xyz/event/abc”).
Return type:: tuple[int, str]
Returns:: Tuple of (event_id, event_name).
Raises:: StartGGAPIError – If the event is not found or request fails.

get_event_standings(event_id, top_n)¶

Get event-level standings (final placements).

Parameters:

event_id (int) – Internal start.gg event ID.
top_n (int) – Number of top teams to fetch.

Return type:

list[Team]

Returns:

List of Team models with placement and roster data.

get_tournament_phases(event_id)¶

Get all phases for an event with metadata.

Parameters:: event_id (int) – Internal start.gg event ID.
Return type:: list[Phase]
Returns:: List of Phase models with phase groups.
Raises:: StartGGAPIError – If the event is not found or request fails.

get_phase_group_standings(phase_group_id)¶

Get standings from a specific phase group.

Parameters:: phase_group_id (int) – Internal start.gg phase group ID.
Return type:: list[Team]
Returns:: List of Team models with placement data.

get_phase_group_seeds(phase_group_id)¶

Get seeds from a phase group (for upcoming phases).

Parameters:: phase_group_id (int) – Internal start.gg phase group ID.
Return type:: list[Team]
Returns:: List of Team models with seed number as placement.

get_set_details(set_id)¶

Get details of a specific match/set.

Parameters:: set_id (int) – Internal start.gg set ID.
Return type:: SetDetails | None
Returns:: SetDetails model or None if not found/incomplete.

get_entrant_last_elimination_set_id(event_id, entrant_id)¶

Get the ID of the set that eliminated an entrant.

Parameters:

event_id (int) – Internal start.gg event ID.
entrant_id (int) – Internal start.gg entrant ID.

Return type:

int | None

Returns:

Set ID of elimination match, or None if not eliminated/found.

has_incomplete_sets(event_id, entrant_id)¶

Check if an entrant has any incomplete sets (still playing).

Parameters:

event_id (int) – Internal start.gg event ID.
entrant_id (int) – Internal start.gg entrant ID.

Return type:

bool

Returns:

True if the entrant has incomplete sets, False otherwise.