Skip to main content

MLB — MLB Stats API — Team

mlb_team​

GET /api/v1/teams/{teamId} — single team detail.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/teams/{team_id}

Valid URL: https://statsapi.mlb.com/api/v1/teams/10?sportId=1

API ParameterPythonPatternRequiredNullableDescription
team_idteam_idYteam_id path parameter.
seasonseasonYSeason year (e.g. 2024).
sportIdsport_idYsportId query parameter.
hydratehydrateYhydrate query parameter.
fieldsfieldsYfields query parameter.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame with the columns below; pass return_as_pandas=True for a pandas.DataFrame.

col_nametypedescription
all_star_statusStringAll-star status flag.
idInt64Id.
nameStringDisplay name.
linkStringAPI link to the game feed.
seasonInt64Season year.
team_codeStringInternal team code.
file_codeStringFile code abbreviation.
abbreviationStringShort abbreviation.
team_nameStringTeam name.
location_nameStringTeam location (city).
first_year_of_playStringFirst year the franchise played.
short_nameStringShort display name.
franchise_nameStringFranchise name.
club_nameStringClub name.
activeBooleanWhether the player is currently active.
spring_league_idInt64Spring league MLBAM ID.
spring_league_nameStringSpring league name.
spring_league_linkStringAPI link to the spring league.
spring_league_abbreviationStringSpring league abbreviation.
venue_idInt64MLBAM venue ID.
venue_nameStringVenue name.
venue_linkStringAPI link to the venue.
spring_venue_idInt64Spring training venue MLBAM ID.
spring_venue_linkStringAPI link to the spring venue.
league_idInt64League MLBAM ID.
league_nameStringLeague name.
league_linkStringAPI link to the league.
division_idInt64Division MLBAM ID.
division_nameStringDivision name.
division_linkStringAPI link to the division.
sport_idInt64Sport MLBAM ID.
sport_linkStringAPI link to the sport.
sport_nameStringSport name (e.g., Major League Baseball).

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
NoDataErrorThe host answered 404 -- the requested resource does not exist.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty.

Example​

mlb_team(team_id=10)

mlb_team_roster​

GET /api/v1/teams/{teamId}/roster — team roster.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/teams/{team_id}/roster

Valid URL: https://statsapi.mlb.com/api/v1/teams/10/roster?rosterType=active

API ParameterPythonPatternRequiredNullableDescription
team_idteam_idYteam_id path parameter.
seasonseasonYSeason year (e.g. 2024).
rosterTyperoster_typeYrosterType query parameter.
datedateYdate query parameter.
hydratehydrateYhydrate query parameter.
fieldsfieldsYfields query parameter.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame with the columns below; pass return_as_pandas=True for a pandas.DataFrame.

col_nametypedescription
jersey_numberStringJersey number worn (often blank for non-uniformed roles).
person_idInt64MLB player ID.
person_full_nameStringPlayer full name.
person_linkStringAPI relative link to the person.
position_codeStringNumeric scorekeeping position code.
position_nameStringFull position name (e.g. 'Point Guard', 'Goalkeeper').
position_typeStringPosition category (e.g. 'Pitcher', 'Infielder').
position_abbreviationStringPosition abbreviation.
status_codeStringStatus code identifier (e.g. 'S', 'P', 'I', 'F').
status_descriptionStringRoster status description (e.g. 'Active').

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
NoDataErrorThe host answered 404 -- the requested resource does not exist.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty.

Example​

mlb_team_roster(team_id=10)

mlb_team_alumni​

GET /api/v1/teams/{teamId}/alumni — players who played for this team in a season.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/teams/{team_id}/alumni

Valid URL: https://statsapi.mlb.com/api/v1/teams/10/alumni?group=hitting

API ParameterPythonPatternRequiredNullableDescription
team_idteam_idYteam_id path parameter.
seasonseasonYSeason year (e.g. 2024).
groupgroupYConference or group id filter (e.g. an ESPN conference id).
hydratehydrateYhydrate query parameter.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame with the columns below; pass return_as_pandas=True for a pandas.DataFrame.

col_nametypedescription
idInt64Id.
full_nameStringPlayer's full name.
linkStringAPI link to the game feed.
first_nameStringPlayer first name.
last_nameStringPlayer last name.
primary_numberStringPlayer uniform number.
birth_dateStringDate of birth (YYYY-MM-DD).
current_ageInt64Current age in years.
birth_cityStringCity of birth.
birth_countryStringCountry of birth.
heightStringHeight (feet and inches).
weightInt64Weight in pounds.
activeBooleanWhether the player is currently active.
use_nameStringPreferred first name.
use_last_nameStringPreferred last name.
middle_nameStringPlayer middle name.
boxscore_nameStringName as shown in box scores.
nick_nameStringPlayer nickname.
genderStringPlayer gender.
is_playerBooleanWhether the person is a player.
is_verifiedBooleanWhether the player profile is verified.
pronunciationStringPhonetic name pronunciation.
mlb_debut_dateStringMLB debut date (YYYY-MM-DD).
name_first_lastStringName in first-last order.
name_slugStringURL-friendly name slug.
first_last_nameStringFirst and last name.
last_first_nameStringName in last, first order.
last_init_nameStringLast name with first initial.
init_last_nameStringFirst initial with last name.
full_fml_nameStringFull name (first-middle-last).
full_lfm_nameStringFull name (last-first-middle).
strike_zone_topFloat64Top of the player's strike zone (feet).
strike_zone_bottomFloat64Bottom of the player's strike zone (feet).
alumni_last_seasonStringLast season the player was with the team.
primary_position_codeStringPrimary position code.
primary_position_nameStringPrimary fielding position name.
primary_position_typeStringPrimary position type (e.g. Infielder).
primary_position_abbreviationStringPrimary position abbreviation.
bat_side_codeStringBatting side code (L/R/S).
bat_side_descriptionStringBatting side description.
pitch_hand_codeStringThrowing hand code (L/R).
pitch_hand_descriptionStringThrowing hand description.
birth_state_provinceStringState or province of birth.
draft_yearFloat64Year the player was drafted.
last_played_dateStringDate of last MLB game played.
name_matrilinealStringMaternal family name.

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
NoDataErrorThe host answered 404 -- the requested resource does not exist.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty.

Example​

mlb_team_alumni(team_id=10)

mlb_team_affiliates​

GET /api/v1/teams/affiliates — org affiliates (MLB parent → minor league chain).

Endpoint URL: GET https://statsapi.mlb.com/api/v1/teams/affiliates

Valid URL: https://statsapi.mlb.com/api/v1/teams/affiliates?sportId=1

API ParameterPythonPatternRequiredNullableDescription
teamIdsteam_idsYteamIds query parameter.
sportIdsport_idYsportId query parameter.
seasonseasonYSeason year (e.g. 2024).
hydratehydrateYhydrate query parameter.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame with the columns below; pass return_as_pandas=True for a pandas.DataFrame.

col_nametypedescription
all_star_statusStringAll-star status flag.
idInt64Id.
nameStringDisplay name.
linkStringAPI link to the game feed.
seasonInt64Season year.
team_codeStringInternal team code.
file_codeStringFile code abbreviation.
abbreviationStringShort abbreviation.
team_nameStringTeam name.
location_nameStringTeam location (city).
first_year_of_playStringFirst year the franchise played.
short_nameStringShort display name.
franchise_nameStringFranchise name.
club_nameStringClub name.
activeBooleanWhether the player is currently active.
spring_league_idFloat64Spring league MLBAM ID.
spring_league_nameStringSpring league name.
spring_league_linkStringAPI link to the spring league.
spring_league_abbreviationStringSpring league abbreviation.
venue_idInt64MLBAM venue ID.
venue_nameStringVenue name.
venue_linkStringAPI link to the venue.
spring_venue_idFloat64Spring training venue MLBAM ID.
spring_venue_linkStringAPI link to the spring venue.
league_idFloat64League MLBAM ID.
league_nameStringLeague name.
league_linkStringAPI link to the league.
division_idFloat64Division MLBAM ID.
division_nameStringDivision name.
division_linkStringAPI link to the division.
sport_idInt64Sport MLBAM ID.
sport_linkStringAPI link to the sport.
sport_nameStringSport name (e.g., Major League Baseball).
parent_org_nameStringParent organization name.
parent_org_idFloat64Parent organization MLBAM ID.

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
NoDataErrorThe host answered 404 -- the requested resource does not exist.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty.

Example​

mlb_team_affiliates()

mlb_teams_history​

View historical records for a list of teams.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/teams/history

Valid URL: https://statsapi.mlb.com/api/v1/teams/history?teamIds=147

API ParameterPythonPatternRequiredNullableDescription
teamIdsteam_idsYteamIds query parameter.
startSeasonstart_seasonYstartSeason query parameter.
endSeasonend_seasonYendSeason query parameter.
fieldsfieldsYfields query parameter.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame with the columns below; pass return_as_pandas=True for a pandas.DataFrame.

col_nametypedescription
all_star_statusStringAll-star status flag.
idInt64Id.
nameStringDisplay name.
linkStringAPI link to the game feed.
seasonInt64Season year.
team_codeStringInternal team code.
file_codeStringFile code abbreviation.
abbreviationStringShort abbreviation.
team_nameStringTeam name.
location_nameStringTeam location (city).
first_year_of_playStringFirst year the franchise played.
short_nameStringShort display name.
franchise_nameStringFranchise name.
club_nameStringClub name.
activeBooleanWhether the player is currently active.
venue_idInt64MLBAM venue ID.
venue_nameStringVenue name.
venue_linkStringAPI link to the venue.
spring_venue_idFloat64Spring training venue MLBAM ID.
spring_venue_linkStringAPI link to the spring venue.
league_idInt64League MLBAM ID.
league_nameStringLeague name.
league_linkStringAPI link to the league.
sport_idInt64Sport MLBAM ID.
sport_linkStringAPI link to the sport.
sport_nameStringSport name (e.g., Major League Baseball).

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
NoDataErrorThe host answered 404 -- the requested resource does not exist.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty.

Example​

mlb_teams_history(team_ids='147')

mlb_teams_stats​

View team stats.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/teams/stats

Valid URL: https://statsapi.mlb.com/api/v1/teams/stats?season=2023&sportIds=1&group=hitting&stats=season

API ParameterPythonPatternRequiredNullableDescription
seasonseasonYSeason year (e.g. 2024).
sportIdssport_idsYsportIds query parameter.
groupstat_groupYgroup query parameter.
gameTypegame_typeYgameType query parameter.
statsstatsYstats query parameter.
orderorderYorder query parameter.
sortStatsort_statYsortStat query parameter.
fieldsfieldsYfields query parameter.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame with the columns below; pass return_as_pandas=True for a pandas.DataFrame.

col_nametypedescription
total_splitsInt64Total number of splits in the leaderboard.
exemptionsStringA serialized list of any statistical exemption notes or flags associated with the team's stat splits (e.g., players exempt from qualifying thresholds).
splitsStringSplits.
splits_tied_with_offsetStringPlayers tied at the offset boundary.
splits_tied_with_limitStringPlayers tied at the limit boundary.
type_display_nameStringStat type display name.
group_display_nameStringStat group display name.

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
NoDataErrorThe host answered 404 -- the requested resource does not exist.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty.

Example​

mlb_teams_stats(season='2023', sport_ids='1', stat_group='hitting', stats='season')

mlb_teams_stats_leaders​

View leaders for a statistic.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/teams/stats/leaders

Valid URL: https://statsapi.mlb.com/api/v1/teams/stats/leaders?leaderCategories=homeRuns&season=2023

API ParameterPythonPatternRequiredNullableDescription
leaderCategoriesleader_categoriesYleaderCategories query parameter.
sitCodessit_codesYsitCodes query parameter.
gameTypesgame_typesYgameTypes query parameter.
statGroupstat_groupYstatGroup query parameter.
seasonseasonYSeason year (e.g. 2024).
leagueIdsleague_idsYleagueIds query parameter.
startDatestart_dateYstartDate query parameter.
endDateend_dateYendDate query parameter.
sportIdsport_idYsportId query parameter.
hydratehydrateYhydrate query parameter.
limitlimitYMaximum number of items to return.
fieldsfieldsYfields query parameter.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame with the columns below; pass return_as_pandas=True for a pandas.DataFrame.

col_nametypedescription
leader_categoryStringTeam leader category (e.g., homeRuns).
seasonStringSeason year.
leadersStringSerialized representation of the statistical leaders entries for the team stat category returned by the MLB Stats API.
stat_groupStringStat group (e.g., hitting).
total_splitsInt64Total number of splits in the leaderboard.
game_type_idStringGame type code (e.g., R for regular season).
game_type_descriptionStringGame type description.

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
NoDataErrorThe host answered 404 -- the requested resource does not exist.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty.

Example​

mlb_teams_stats_leaders(leader_categories='homeRuns', season='2023')

mlb_team_coaches​

View biographical information on all coaches for a given club.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/teams/{team_id}/coaches

Valid URL: https://statsapi.mlb.com/api/v1/teams/147/coaches?season=2023

API ParameterPythonPatternRequiredNullableDescription
team_idteam_idYteam_id path parameter.
seasonseasonYSeason year (e.g. 2024).
datedateYdate query parameter.
fieldsfieldsYfields query parameter.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame with the columns below; pass return_as_pandas=True for a pandas.DataFrame.

col_nametypedescription
jersey_numberStringJersey number worn (often blank for non-uniformed roles).
jobStringJob title (e.g. 'Umpire').
job_idStringJob code identifier.
titleStringSpecific role title for the assignment.
person_idInt64MLB player ID.
person_full_nameStringPlayer full name.
person_linkStringAPI relative link to the person.

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
NoDataErrorThe host answered 404 -- the requested resource does not exist.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty.

Example​

mlb_team_coaches(team_id=147, season='2023')

mlb_team_personnel​

View biographical information on all personnel for a given club.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/teams/{team_id}/personnel

Valid URL: https://statsapi.mlb.com/api/v1/teams/147/personnel

API ParameterPythonPatternRequiredNullableDescription
team_idteam_idYteam_id path parameter.
datedateYdate query parameter.
fieldsfieldsYfields query parameter.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame with the columns below; pass return_as_pandas=True for a pandas.DataFrame.

col_nametypedescription
jersey_numberStringJersey number worn (often blank for non-uniformed roles).
jobStringJob title (e.g. 'Umpire').
job_idStringJob code identifier.
titleStringSpecific role title for the assignment.
person_idInt64MLB player ID.
person_full_nameStringPlayer full name.
person_linkStringAPI relative link to the person.

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
NoDataErrorThe host answered 404 -- the requested resource does not exist.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty.

Example​

mlb_team_personnel(team_id=147)

mlb_team_roster_type​

View biographical and statistical information for a club's roster based on roster type.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/teams/{team_id}/roster/{roster_type}

Valid URL: https://statsapi.mlb.com/api/v1/teams/147/roster/active?season=2023

API ParameterPythonPatternRequiredNullableDescription
team_idteam_idYteam_id path parameter.
roster_typeroster_typeYroster_type path parameter.
seasonseasonYSeason year (e.g. 2024).
datedateYdate query parameter.
hydratehydrateYhydrate query parameter.
fieldsfieldsYfields query parameter.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame with the columns below; pass return_as_pandas=True for a pandas.DataFrame.

col_nametypedescription
jersey_numberStringJersey number worn (often blank for non-uniformed roles).
person_idInt64MLB player ID.
person_full_nameStringPlayer full name.
person_linkStringAPI relative link to the person.
position_codeStringNumeric scorekeeping position code.
position_nameStringPosition name.
position_typeStringPosition category (e.g. 'Pitcher', 'Infielder').
position_abbreviationStringPosition abbreviation.
status_codeStringStatus code identifier (e.g. 'S', 'P', 'I', 'F').
status_descriptionStringRoster status description (e.g. 'Active').

return_parsed=False — the raw JSON Dict payload, unparsed.

Raises​

ExceptionDescription
NoDataErrorThe host answered 404 -- the requested resource does not exist.
ValueErrorThe host answered 400 / 422 -- the request is wrong; retrying cannot help.
AssetFetchErrorThe fetch failed (a non-2xx answer or a connection failure after retries, e.g. 401/403/429/5xx, or an empty or unreadable 200 body) -- the answer is unknown, not empty.

Example​

mlb_team_roster_type(team_id=147, roster_type='active', season='2023')