Skip to Content

Leagues

Get a list of available leagues with optional sport filtering.

GET /api/v1/leagues

Requires an API key. Available on all tiers (Free included). Unauthenticated requests return 401.

Query ParametersPermalink for this section

ParameterTypeDefaultDescription
sportstringallFilter by sport (e.g., basketball, football). Sport ids only; a league id such as nba goes in league (details).
sportsbookstringallRestrict the league list and counts to one or more books (comma-separated), e.g. sportsbook=draftkings

Example RequestsPermalink for this section

# List all leagues curl -X GET "https://api.sharpapi.io/api/v1/leagues" \ -H "X-API-Key: YOUR_API_KEY" # Filter by sport curl -X GET "https://api.sharpapi.io/api/v1/leagues?sport=basketball" \ -H "X-API-Key: YOUR_API_KEY"

ResponsePermalink for this section

Success (200)Permalink for this section

Real response for ?sport=basketball, truncated to the first three of ~140 basketball leagues:

{ "data": [ { "id": "nba", "display_name": "NBA", "numerical_id": 364, "sport": "basketball", "event_count": 414, "live_count": 0 }, { "id": "ncaab", "display_name": "NCAAB", "numerical_id": 366, "sport": "basketball", "event_count": 138, "live_count": 0 }, { "id": "wnba", "display_name": "WNBA", "numerical_id": 611, "sport": "basketball", "event_count": 98, "live_count": 5 } ], "updated_at": "2026-07-02T18:17:55.590257979Z" }

All Leagues (No Filter)Permalink for this section

Real response, truncated — the full unfiltered list currently returns 800+ leagues, ordered by event_count descending. Note the canonical slug form for soccer leagues (england_-_premier_league), and that numerical_id is omitted on unmapped entries (like the game grouping bucket below):

{ "data": [ { "id": "atp", "display_name": "ATP", "numerical_id": 15, "sport": "tennis", "event_count": 1008, "live_count": 60 }, { "id": "fifa_-_world_cup", "display_name": "FIFA - World Cup", "numerical_id": 197, "sport": "soccer", "event_count": 978, "live_count": 0 }, { "id": "nfl", "display_name": "NFL", "numerical_id": 376, "sport": "football", "event_count": 746, "live_count": 0 }, { "id": "mlb", "display_name": "MLB", "numerical_id": 354, "sport": "baseball", "event_count": 646, "live_count": 14 }, { "id": "game", "display_name": "Game", "sport": "soccer", "event_count": 536, "live_count": 0 }, { "id": "england_-_premier_league", "display_name": "England - Premier League", "numerical_id": 163, "sport": "soccer", "event_count": 55, "live_count": 0 } ], "updated_at": "2026-07-02T18:17:55.590257979Z" }

League Object SchemaPermalink for this section

FieldTypeDescription
idstringLeague identifier (lowercase, use in API filters)
numerical_idintegerStable integer key for the league (frozen, never reused; omitted when unmapped). New (May 2026) — additive, optional. See Entity reference IDs.
display_namestringHuman-readable league name
sportstringParent sport ID
event_countintegerNumber of matches (games) in the league with odds right now. Futures markets are not counted. Changed (November 2026); see below.
live_countintegerMatches currently live/in-play (never more than event_count)

Changed (November 2026): event_count and live_count count matches only. They used to count every event with odds in the league, futures markets included. They now count matches (games) only: a futures market, such as a championship winner, is not counted, so a league with many futures shows a lower count than before, and a league with only futures right now shows 0 and stays listed. Futures and their odds are on the futures endpoints (Enterprise).

New (May 2026): numerical_idPermalink for this section

numerical_id is a frozen, dense-from-1 integer assigned per league in the SharpAPI atlas. The live catalog currently serves 800+ leagues across ~28 sports; mapped leagues carry the integer, unmapped ones omit it. Use it as a compact join/index key when storing rows in your own database.

  • Frozen: never reused or remapped.
  • Optional: omitted for leagues that haven’t been mapped yet — slug id is always present.
  • Domain-scoped: unique across leagues only.

Every odds row and opportunity leg also carries a matching league_ref block ({id, label, numerical_id}) so you don’t need to second-fetch this endpoint just to label a row. See Entity reference IDs for the full contract.

Common LeaguesPermalink for this section

The endpoint is the canonical source of truth — call GET /api/v1/leagues for the complete, up-to-date list. The live catalog currently returns 800+ leagues across ~28 sports including UEFA continental competitions, multiple basketball circuits per country, and full tennis/golf/MMA/esports/cricket coverage. The illustrative subset below shows the highest-volume entries you’ll typically filter on:

SportCommon league IDs
Basketballnba, ncaab, wnba
Footballnfl, ncaaf
Hockeynhl
Baseballmlb
Soccerengland_-_premier_league, spain_-_la_liga, italy_-_serie_a, germany_-_bundesliga, france_-_ligue_1, uefa_-_champions_league, usa_-_major_league_soccer
Tennisatp, wta, atp_challenger, itf_men, itf_women
MMAufc
Golfpga, dp_world_tour, world_tour
  • League IDs use canonical slug form (england_-_premier_league, not epl). Some short forms are accepted as filter input for backward compatibility, but the canonical slug is what /leagues returns and what other endpoints emit on response payloads.
  • The event_count and live_count values are dynamic. Off-season leagues (e.g., MLB in winter, WNBA in fall) show 0 but stay in the catalog, also while their futures markets are open.
  • For programmatic access (e.g. building dropdown filters), call /api/v1/leagues and use the response — never hard-code a list.

Using Leagues in FiltersPermalink for this section

Use the league id as a filter parameter on other endpoints:

# Get NBA odds curl "https://api.sharpapi.io/api/v1/odds?league=nba" \ -H "X-API-Key: YOUR_API_KEY" # Get best odds for NFL and NBA curl "https://api.sharpapi.io/api/v1/odds/best?league=nfl,nba" \ -H "X-API-Key: YOUR_API_KEY"
Last updated on