Skip to main content
Version: 0.0.70

MLB — MLB Stats API

sportsdataverse.mlb — 64 endpoints.

mlb_schedule_postseason​

GET /api/v1/schedule/postseason — postseason-only schedule for a season.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/schedule/postseason

Valid URL: https://statsapi.mlb.com/api/v1/schedule/postseason

API ParameterPythonPatternRequiredNullableDescription
seasonseasonYSeason year (e.g. 2024).
sportIdsport_idYsportId query parameter.
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
schedule_datecharacterThe calendar date grouping postseason games in this response row, as returned by the MLB Stats API schedule endpoint.
game_pkintegerUnique game identifier.
game_guidcharacterGlobally unique game identifier (GUID).
linkcharacterAPI link to the game feed.
game_typecharacterGame type code (R, P, etc.).
seasoncharacterSeason year.
game_datecharacterGame date (YYYY-MM-DD).
official_datecharacterOfficial game date (YYYY-MM-DD).
is_tielogicalWhether the game ended in a tie.
is_featured_gamelogicalWhether the game is a featured game.
game_numberintegerGame number within a doubleheader.
public_facinglogicalWhether the game is public-facing.
double_headercharacterDoubleheader indicator ('N', 'S', 'Y').
gameday_typecharacterGameday data feed type.
tiebreakercharacterWhether the game is a tiebreaker.
calendar_event_idcharacterCalendar event identifier.
season_displaycharacterDisplay string for the season.
day_nightcharacterDay or night game indicator.
descriptioncharacterLong-form description text.
scheduled_inningsintegerScheduled number of innings.
reverse_home_away_statuslogicalWhether home/away teams are reversed.
inning_break_lengthintegerLength of inning breaks in seconds.
games_in_seriesintegerNumber of games in the series.
series_game_numberintegerGame number within the series.
series_descriptioncharacterDescription of the series.
record_sourcecharacterSource of the schedule record.
if_necessarycharacterWhether the game is played only if necessary.
if_necessary_descriptioncharacterDescription of the if-necessary status.
status_abstract_game_statecharacterAbstract game state (e.g. 'Final').
status_coded_game_statecharacterCoded game state.
status_detailed_statecharacterDetailed game state.
status_status_codecharacterStatus code for the game.
status_start_time_tbdlogicalWhether the start time is TBD.
status_abstract_game_codecharacterAbstract game state code.
teams_away_team_idintegerAway team MLBAM ID.
teams_away_team_namecharacterAway team name.
teams_away_team_linkcharacterAPI link to the away team.
teams_away_league_record_winsintegerAway team league-record wins.
teams_away_league_record_lossesintegerAway team league-record losses.
teams_away_league_record_tiesintegerAway team league-record ties.
teams_away_league_record_pctcharacterAway team winning percentage.
teams_away_scoreintegerAway team score.
teams_away_is_winnerlogicalWhether the away team won.
teams_away_split_squadlogicalWhether the away team is a split squad.
teams_away_series_numberintegerAway team's series number.
teams_home_team_idintegerHome team MLBAM ID.
teams_home_team_namecharacterHome team name.
teams_home_team_linkcharacterAPI link to the home team.
teams_home_league_record_winsintegerHome team league-record wins.
teams_home_league_record_lossesintegerHome team league-record losses.
teams_home_league_record_tiesintegerHome team league-record ties.
teams_home_league_record_pctcharacterHome team winning percentage.
teams_home_scoreintegerHome team score.
teams_home_is_winnerlogicalWhether the home team won.
teams_home_split_squadlogicalWhether the home team is a split squad.
teams_home_series_numberintegerHome team's series number.
venue_idintegerMLBAM venue ID.
venue_namecharacterVenue name.
venue_linkcharacterAPI link to the venue.
content_linkcharacterAPI link to the game content.

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

Example​

mlb_schedule_postseason()

Last validated n/a.

mlb_pbp​

GET /api/v1.1/game/{gamePk}/feed/live — live firehose (v1.1).

Endpoint URL: GET https://statsapi.mlb.com/api/v1.1/game/{game_pk}/feed/live

Valid URL: https://statsapi.mlb.com/api/v1.1/game/716390/feed/live

API ParameterPythonPatternRequiredNullableDescription
game_pkgame_pkY
languagelanguageY
languagetimecodeY
hydratehydrateY
fieldsfieldsY

Returns​

return_parsed=True (default) — a tidy polars.DataFrame (parser: parse_mlb_api_list); pass return_as_pandas=True for a pandas.DataFrame. return_parsed=False — the raw JSON Dict payload, unparsed.

Example​

mlb_pbp(game_pk=716390)

Last validated n/a.

mlb_boxscore​

GET /api/v1/game/{gamePk}/boxscore — team + player boxscore for one game.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/game/{game_pk}/boxscore

Valid URL: https://statsapi.mlb.com/api/v1/game/716390/boxscore

API ParameterPythonPatternRequiredNullableDescription
game_pkgame_pkYgame_pk path parameter.
timecodetimecodeYtimecode 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
team_sidecharacterHome or away indicator.
team_idintegerUnique ESPN team identifier.
team_namecharacterTeam name.
jersey_numbercharacterJersey number worn (often blank for non-uniformed roles).
parent_team_idintegerMLB Stats API identifier for the player's parent (MLB-level) organization, useful for tracking players on optional assignment.
batting_ordercharacterSpot in the batting order (1-9).
all_positionscharacterAll fielding positions played by the player during the game, as a list of position codes.
person_idintegerMLB player ID.
person_full_namecharacterPlayer full name.
person_linkcharacterAPI relative link to the person.
person_boxscore_namecharacterName as shown in box scores.
position_codecharacterNumeric scorekeeping position code.
position_namecharacterPosition name.
position_typecharacterPosition category (e.g. 'Pitcher', 'Infielder').
position_abbreviationcharacterPosition abbreviation.
status_codecharacterStatus code identifier (e.g. 'S', 'P', 'I', 'F').
status_descriptioncharacterRoster status description (e.g. 'Active').
stats_batting_summarycharacterCondensed text summary of the batter's performance line (e.g., '2-4, HR, 2 RBI') for display purposes.
stats_batting_games_playeddoubleNumber of games played indicator for this batter's boxscore row (typically 1 for a standard game appearance).
stats_batting_fly_outsdoubleNumber of outs recorded by the batter on fly balls in this game.
stats_batting_ground_outsdoubleNumber of outs recorded by the batter on ground balls in this game.
stats_batting_air_outsdoubleNumber of outs recorded by the batter on balls hit in the air during this game.
stats_batting_runsdoubleNumber of runs scored by the batter in this game.
stats_batting_doublesdoubleNumber of doubles hit by the batter in this game.
stats_batting_triplesdoubleNumber of triples hit by the batter in this game.
stats_batting_home_runsdoubleNumber of home runs hit by the batter in this game.
stats_batting_strike_outsdoubleNumber of times the batter struck out in this game.
stats_batting_base_on_ballsdoubleNumber of walks (bases on balls) drawn by the batter in this game, including intentional walks.
stats_batting_intentional_walksdoubleNumber of intentional walks issued to the batter in this game.
stats_batting_hitsdoubleTotal number of hits recorded by the batter in this game.
stats_batting_hit_by_pitchdoubleNumber of times the batter was hit by a pitch in this game.
stats_batting_at_batsdoubleNumber of official at-bats for the batter in this game.
stats_batting_caught_stealingdoubleNumber of times the batter was caught stealing in this game.
stats_batting_stolen_basesdoubleNumber of stolen bases recorded by the batter in this game.
stats_batting_stolen_base_percentagecharacterPercentage of stolen base attempts that were successful for the batter in this game.
stats_batting_ground_into_double_playdoubleNumber of times the batter grounded into a double play in this game.
stats_batting_ground_into_triple_playdoubleNumber of times the batter grounded into a triple play in this game.
stats_batting_plate_appearancesdoubleTotal number of plate appearances for the batter in this game.
stats_batting_total_basesdoubleTotal number of bases accumulated by the batter on hits in this game.
stats_batting_rbidoubleNumber of runs batted in (RBI) credited to the batter in this game.
stats_batting_left_on_basedoubleNumber of runners left on base when the batter made an out or the inning ended in this game.
stats_batting_sac_buntsdoubleNumber of sacrifice bunts executed by the batter in this game.
stats_batting_sac_fliesdoubleNumber of sacrifice flies hit by the batter that scored a run in this game.
stats_batting_catchers_interferencedoubleNumber of times the batter reached base due to catcher's interference in this game.
stats_batting_pickoffsdoubleNumber of times the batter was picked off base in this game.
stats_batting_at_bats_per_home_runcharacterAt-bats per home run ratio for the batter in this game.
stats_batting_pop_outsdoubleNumber of outs recorded by the batter on infield pop-ups in this game.
stats_batting_line_outsdoubleNumber of outs recorded by the batter on line drives caught in this game.
stats_fielding_caught_stealingdoubleNumber of baserunners caught stealing by the player (typically a catcher) in this game.
stats_fielding_stolen_basesdoubleNumber of stolen bases allowed by the player while fielding in this game.
stats_fielding_stolen_base_percentagecharacterPercentage of stolen base attempts against the player (catcher perspective) that were successful in this game.
stats_fielding_caught_stealing_percentagecharacterPercentage of stolen base attempts that the player threw out in this game.
stats_fielding_assistsdoubleNumber of fielding assists recorded by the player in this game.
stats_fielding_put_outsdoubleNumber of putouts recorded by the player in this game.
stats_fielding_errorsdoubleNumber of fielding errors committed by the player in this game.
stats_fielding_chancesdoubleTotal fielding chances for the player in this game (putouts + assists + errors).
stats_fielding_fieldingcharacterFielding percentage for the player in this game, calculated as (putouts + assists) / total chances.
stats_fielding_passed_balldoubleNumber of passed balls charged to the player (catcher-specific) in this game.
stats_fielding_pickoffsdoubleNumber of pickoffs credited to the player as a fielder in this game.
season_stats_batting_games_playedintegerSeason-to-date number of games in which the batter appeared.
season_stats_batting_fly_outsintegerSeason-to-date number of outs recorded by the batter on fly balls caught in the outfield.
season_stats_batting_ground_outsintegerSeason-to-date number of outs recorded by the batter on ground balls.
season_stats_batting_air_outsintegerSeason-to-date number of outs recorded by the batter on balls hit in the air (fly balls and line drives caught).
season_stats_batting_runsintegerSeason-to-date number of runs scored by the batter.
season_stats_batting_doublesintegerSeason-to-date number of doubles hit by the batter.
season_stats_batting_triplesintegerSeason-to-date number of triples hit by the batter.
season_stats_batting_home_runsintegerSeason-to-date number of home runs hit by the batter.
season_stats_batting_strike_outsintegerSeason-to-date number of times the batter struck out.
season_stats_batting_base_on_ballsintegerSeason-to-date total walks (bases on balls) drawn by the batter, including intentional walks.
season_stats_batting_intentional_walksintegerSeason-to-date number of intentional walks (IBB) issued to the batter.
season_stats_batting_hitsintegerSeason-to-date total number of hits recorded by the batter.
season_stats_batting_hit_by_pitchintegerSeason-to-date number of times the batter was hit by a pitch.
season_stats_batting_avgcharacterSeason-to-date batting average (hits divided by at-bats) for the batter.
season_stats_batting_at_batsintegerSeason-to-date number of official at-bats accumulated by the batter.
season_stats_batting_obpcharacterSeason-to-date on-base percentage (OBP), measuring how often the batter reaches base per plate appearance.
season_stats_batting_slgcharacterSeason-to-date slugging percentage (SLG), measuring total bases per at-bat.
season_stats_batting_opscharacterSeason-to-date on-base plus slugging percentage (OPS), a combined measure of a batter's ability to get on base and hit for power.
season_stats_batting_caught_stealingintegerSeason-to-date number of times the batter was caught stealing a base.
season_stats_batting_stolen_basesintegerSeason-to-date number of bases stolen by the batter.
season_stats_batting_stolen_base_percentagecharacterSeason-to-date percentage of stolen base attempts that were successful for the batter.
season_stats_batting_caught_stealing_percentagecharacterSeason-to-date percentage of stolen base attempts that resulted in the batter being caught stealing.
season_stats_batting_ground_into_double_playintegerSeason-to-date number of times the batter grounded into a double play.
season_stats_batting_ground_into_triple_playintegerSeason-to-date number of times the batter grounded into a triple play.
season_stats_batting_plate_appearancesintegerSeason-to-date total number of plate appearances for the batter, including at-bats, walks, HBP, and sacrifices.
season_stats_batting_total_basesintegerSeason-to-date total number of bases accumulated by the batter on hits.
season_stats_batting_rbiintegerSeason-to-date number of runs batted in (RBI) credited to the batter.
season_stats_batting_left_on_baseintegerSeason-to-date number of runners left on base when the batter made an out or the inning ended.
season_stats_batting_sac_buntsintegerSeason-to-date number of sacrifice bunts executed by the batter.
season_stats_batting_sac_fliesintegerSeason-to-date number of sacrifice flies hit by the batter that scored a run.
season_stats_batting_babipcharacterSeason-to-date Batting Average on Balls In Play (BABIP), measuring batting average excluding strikeouts and home runs.
season_stats_batting_ground_outs_to_airoutscharacterSeason-to-date ratio of ground outs to air outs, indicating the batter's tendency to hit the ball on the ground versus in the air.
season_stats_batting_catchers_interferenceintegerSeason-to-date number of times the batter reached base due to catcher's interference.
season_stats_batting_pickoffsintegerSeason-to-date number of times the batter was picked off base by a pitcher or catcher.
season_stats_batting_at_bats_per_home_runcharacterSeason-to-date ratio of at-bats per home run, reflecting the batter's home run frequency.
season_stats_batting_pop_outsintegerSeason-to-date number of outs recorded by the batter on pop-ups caught in the infield.
season_stats_batting_line_outsintegerSeason-to-date number of outs recorded by the batter on line drives caught.
season_stats_pitching_games_playedintegerSeason-to-date number of games the pitcher was active on the roster (may include non-pitching appearances).
season_stats_pitching_games_startedintegerSeason-to-date number of games in which the pitcher was the starting pitcher.
season_stats_pitching_fly_outsintegerSeason-to-date number of outs recorded by the pitcher on fly balls.
season_stats_pitching_ground_outsintegerSeason-to-date number of outs recorded by the pitcher on ground balls.
season_stats_pitching_air_outsintegerSeason-to-date number of outs recorded by the pitcher on balls hit in the air.
season_stats_pitching_runsintegerSeason-to-date total runs (earned and unearned) allowed by the pitcher.
season_stats_pitching_doublesintegerSeason-to-date number of doubles allowed by the pitcher.
season_stats_pitching_triplesintegerSeason-to-date number of triples allowed by the pitcher.
season_stats_pitching_home_runsintegerSeason-to-date number of home runs allowed by the pitcher.
season_stats_pitching_strike_outsintegerSeason-to-date number of batters struck out by the pitcher.
season_stats_pitching_base_on_ballsintegerSeason-to-date total walks (bases on balls) issued by the pitcher, including intentional walks.
season_stats_pitching_intentional_walksintegerSeason-to-date number of intentional walks (IBB) issued by the pitcher.
season_stats_pitching_hitsintegerSeason-to-date number of hits allowed by the pitcher.
season_stats_pitching_hit_by_pitchintegerSeason-to-date number of hit-by-pitch events while the pitcher was pitching (alternate field name for hit_batsmen).
season_stats_pitching_at_batsintegerSeason-to-date number of at-bats faced by the pitcher (excluding walks, HBP, and sacrifices).
season_stats_pitching_obpcharacterSeason-to-date on-base percentage allowed by the pitcher (opponents' OBP against this pitcher).
season_stats_pitching_caught_stealingintegerSeason-to-date number of baserunners caught stealing while the pitcher was on the mound.
season_stats_pitching_stolen_basesintegerSeason-to-date number of stolen bases allowed while the pitcher was pitching.
season_stats_pitching_stolen_base_percentagecharacterSeason-to-date percentage of stolen base attempts that were successful while the pitcher was on the mound.
season_stats_pitching_caught_stealing_percentagecharacterSeason-to-date percentage of stolen base attempts that were thrown out while the pitcher was pitching.
season_stats_pitching_number_of_pitchesintegerSeason-to-date total number of pitches thrown by the pitcher.
season_stats_pitching_eracharacterSeason-to-date Earned Run Average (ERA) for the pitcher, expressed as earned runs per nine innings.
season_stats_pitching_innings_pitchedcharacterSeason-to-date total innings pitched, expressed as a decimal where each out is one-third of an inning.
season_stats_pitching_winsintegerSeason-to-date number of wins credited to the pitcher.
season_stats_pitching_lossesintegerSeason-to-date number of losses charged to the pitcher.
season_stats_pitching_savesintegerSeason-to-date number of saves recorded by the pitcher.
season_stats_pitching_save_opportunitiesintegerSeason-to-date number of save opportunities the pitcher entered (leads of three runs or fewer in the seventh inning or later, or entering with the tying run on base).
season_stats_pitching_holdsintegerSeason-to-date number of holds recorded by the pitcher (relief appearance maintaining a lead without a save situation).
season_stats_pitching_blown_savesintegerSeason-to-date number of blown save opportunities for the pitcher.
season_stats_pitching_earned_runsintegerSeason-to-date number of earned runs allowed by the pitcher.
season_stats_pitching_whipcharacterSeason-to-date Walks plus Hits per Inning Pitched (WHIP), measuring baserunners allowed per inning.
season_stats_pitching_batters_facedintegerSeason-to-date total number of batters faced by the pitcher.
season_stats_pitching_outsintegerSeason-to-date total number of outs recorded by the pitcher.
season_stats_pitching_games_pitchedintegerSeason-to-date number of games in which the pitcher appeared.
season_stats_pitching_complete_gamesintegerSeason-to-date number of complete games pitched by the pitcher.
season_stats_pitching_shutoutsintegerSeason-to-date number of complete-game shutouts pitched.
season_stats_pitching_ballsintegerSeason-to-date number of ball calls recorded against the pitcher.
season_stats_pitching_strikesintegerSeason-to-date total number of strikes thrown by the pitcher.
season_stats_pitching_strike_percentagecharacterSeason-to-date percentage of all pitches thrown that were strikes.
season_stats_pitching_hit_batsmenintegerSeason-to-date number of batters hit by a pitch thrown by the pitcher.
season_stats_pitching_balksintegerSeason-to-date number of balks called against the pitcher.
season_stats_pitching_wild_pitchesintegerSeason-to-date number of wild pitches thrown by the pitcher.
season_stats_pitching_pickoffsintegerSeason-to-date number of pickoffs executed by the pitcher.
season_stats_pitching_ground_outs_to_airoutscharacterSeason-to-date ratio of ground ball outs to air ball outs allowed by the pitcher.
season_stats_pitching_rbiintegerSeason-to-date number of RBI allowed (runs batted in by opposing batters) while this pitcher was pitching.
season_stats_pitching_win_percentagecharacterSeason-to-date winning percentage for the pitcher (wins divided by decisions).
season_stats_pitching_pitches_per_inningcharacterSeason-to-date average number of pitches thrown per inning by the pitcher.
season_stats_pitching_games_finishedintegerSeason-to-date number of games in which the pitcher was the last pitcher used by their team.
season_stats_pitching_strikeout_walk_ratiocharacterSeason-to-date ratio of strikeouts to walks, measuring the pitcher's command and dominance.
season_stats_pitching_strikeouts_per9_inncharacterSeason-to-date strikeouts recorded per nine innings pitched (K/9), a rate measure of strikeout ability.
season_stats_pitching_walks_per9_inncharacterSeason-to-date walks issued per nine innings pitched (BB/9), a rate measure of control.
season_stats_pitching_hits_per9_inncharacterSeason-to-date hits allowed per nine innings pitched, a rate stat measuring hit prevention.
season_stats_pitching_runs_scored_per9characterSeason-to-date total runs (including unearned) allowed per nine innings pitched.
season_stats_pitching_home_runs_per9characterSeason-to-date home runs allowed per nine innings pitched.
season_stats_pitching_inherited_runnersintegerSeason-to-date number of baserunners already on base when the pitcher entered the game.
season_stats_pitching_inherited_runners_scoredintegerSeason-to-date number of inherited runners who eventually scored while or after the pitcher was pitching.
season_stats_pitching_catchers_interferenceintegerSeason-to-date number of times the pitcher benefited from a catcher's interference call.
season_stats_pitching_sac_buntsintegerSeason-to-date number of sacrifice bunts allowed by the pitcher.
season_stats_pitching_sac_fliesintegerSeason-to-date number of sacrifice flies allowed by the pitcher.
season_stats_pitching_passed_ballintegerSeason-to-date number of passed balls that occurred while the pitcher was pitching.
season_stats_pitching_pop_outsintegerSeason-to-date number of outs recorded by the pitcher on pop-ups caught in the infield.
season_stats_pitching_line_outsintegerSeason-to-date number of outs recorded by the pitcher on line drives caught.
season_stats_fielding_caught_stealingintegerSeason-to-date number of baserunners caught stealing by the player (typically a catcher stat).
season_stats_fielding_stolen_basesintegerSeason-to-date number of stolen bases allowed by the player while fielding (typically catcher).
season_stats_fielding_stolen_base_percentagecharacterSeason-to-date percentage of stolen base attempts against the player that were successful (catcher perspective).
season_stats_fielding_caught_stealing_percentagecharacterSeason-to-date percentage of stolen base attempts that the player (usually a catcher) threw out.
season_stats_fielding_assistsintegerSeason-to-date number of fielding assists recorded by the player (touching the ball before a putout by a teammate).
season_stats_fielding_put_outsintegerSeason-to-date number of putouts recorded by the player (directly retiring a baserunner or batter).
season_stats_fielding_errorsintegerSeason-to-date number of fielding errors committed by the player.
season_stats_fielding_chancesintegerSeason-to-date total fielding chances for the player (putouts + assists + errors).
season_stats_fielding_fieldingcharacterSeason-to-date fielding percentage for the player, calculated as (putouts + assists) / total chances.
season_stats_fielding_passed_ballintegerSeason-to-date number of passed balls charged to the player (catcher-specific).
season_stats_fielding_pickoffsintegerSeason-to-date number of pickoffs credited to the player as a fielder.
game_status_is_current_batterlogicalIndicates whether the player is currently at bat at the moment the boxscore was captured.
game_status_is_current_pitcherlogicalIndicates whether the player is currently pitching at the moment the boxscore was captured.
game_status_is_on_benchlogicalIndicates whether the player is currently on the bench (not in the active lineup) at time of capture.
game_status_is_substitutelogicalIndicates whether the player entered the game as a substitute for another player.
stats_fielding_games_starteddoubleIndicator of whether the player started at a fielding position in this game.
season_stats_fielding_games_starteddoubleSeason-to-date number of games in which the player started at a fielding position.
season_stats_pitching_pitches_throwndoubleSeason-to-date total pitches thrown by the pitcher (may differ from number_of_pitches if strikes/balls are tracked separately).
stats_pitching_summarycharacterCondensed text summary of the pitcher's performance line (e.g., '6.0 IP, 2 ER, 8 K') for display purposes.
stats_pitching_games_playeddoubleNumber of games the pitcher appeared in for this boxscore row (typically 1).
stats_pitching_games_starteddoubleIndicator of whether the pitcher was the starting pitcher in this game.
stats_pitching_fly_outsdoubleNumber of outs recorded by the pitcher on fly balls in this game.
stats_pitching_ground_outsdoubleNumber of outs recorded by the pitcher on ground balls in this game.
stats_pitching_air_outsdoubleNumber of outs recorded by the pitcher on balls hit in the air in this game.
stats_pitching_runsdoubleTotal runs (earned and unearned) allowed by the pitcher in this game.
stats_pitching_doublesdoubleNumber of doubles allowed by the pitcher in this game.
stats_pitching_triplesdoubleNumber of triples allowed by the pitcher in this game.
stats_pitching_home_runsdoubleNumber of home runs allowed by the pitcher in this game.
stats_pitching_strike_outsdoubleNumber of batters struck out by the pitcher in this game.
stats_pitching_base_on_ballsdoubleNumber of walks (bases on balls) issued by the pitcher in this game, including intentional walks.
stats_pitching_intentional_walksdoubleNumber of intentional walks (IBB) issued by the pitcher in this game.
stats_pitching_hitsdoubleNumber of hits allowed by the pitcher in this game.
stats_pitching_hit_by_pitchdoubleNumber of hit-by-pitch events while the pitcher was pitching in this game (alternate field for hit_batsmen).
stats_pitching_at_batsdoubleNumber of at-bats faced by the pitcher (excluding walks, HBP, and sacrifices) in this game.
stats_pitching_caught_stealingdoubleNumber of baserunners caught stealing while the pitcher was on the mound in this game.
stats_pitching_stolen_basesdoubleNumber of stolen bases allowed while the pitcher was pitching in this game.
stats_pitching_stolen_base_percentagecharacterPercentage of stolen base attempts that were successful while the pitcher was on the mound in this game.
stats_pitching_number_of_pitchesdoubleTotal number of pitches thrown by the pitcher in this game.
stats_pitching_innings_pitchedcharacterTotal innings pitched by the pitcher in this game, expressed as a decimal (each out counts as one-third of an inning).
stats_pitching_winsdoubleIndicator of whether the pitcher was credited with the win in this game.
stats_pitching_lossesdoubleIndicator of whether the pitcher was charged with the loss in this game.
stats_pitching_savesdoubleIndicator of whether the pitcher recorded a save in this game.
stats_pitching_save_opportunitiesdoubleNumber of save opportunities the pitcher entered in this game.
stats_pitching_holdsdoubleNumber of holds recorded by the pitcher in this game.
stats_pitching_blown_savesdoubleNumber of blown save opportunities for the pitcher in this game.
stats_pitching_earned_runsdoubleNumber of earned runs allowed by the pitcher in this game.
stats_pitching_batters_faceddoubleTotal number of batters faced by the pitcher in this game.
stats_pitching_outsdoubleTotal number of outs recorded by the pitcher in this game.
stats_pitching_games_pitcheddoubleNumber of pitching appearances for the pitcher in this game (typically 1).
stats_pitching_complete_gamesdoubleIndicator of whether the pitcher threw a complete game in this appearance.
stats_pitching_shutoutsdoubleIndicator of whether the pitcher recorded a complete-game shutout in this game.
stats_pitching_pitches_throwndoubleTotal pitches thrown by the pitcher in this game (may differ from number_of_pitches depending on tracking method).
stats_pitching_ballsdoubleNumber of ball calls recorded against the pitcher in this game.
stats_pitching_strikesdoubleTotal number of strikes thrown by the pitcher in this game.
stats_pitching_strike_percentagecharacterPercentage of all pitches thrown that were strikes in this game.
stats_pitching_hit_batsmendoubleNumber of batters hit by a pitch thrown by the pitcher in this game.
stats_pitching_balksdoubleNumber of balks called against the pitcher in this game.
stats_pitching_wild_pitchesdoubleNumber of wild pitches thrown by the pitcher in this game.
stats_pitching_pickoffsdoubleNumber of pickoffs executed by the pitcher in this game.
stats_pitching_rbidoubleNumber of RBI allowed (runs batted in by opposing batters off this pitcher) in this game.
stats_pitching_games_finisheddoubleIndicator of whether the pitcher was the last pitcher used by their team in this game.
stats_pitching_runs_scored_per9characterTotal runs (including unearned) allowed per nine innings rate for the pitcher in this game.
stats_pitching_home_runs_per9characterHome runs allowed per nine innings rate for the pitcher in this game.
stats_pitching_inherited_runnersdoubleNumber of baserunners already on base when the pitcher entered the game.
stats_pitching_inherited_runners_scoreddoubleNumber of inherited runners who scored while or after the pitcher was pitching in this game.
stats_pitching_catchers_interferencedoubleNumber of catcher's interference calls that occurred while the pitcher was pitching in this game.
stats_pitching_sac_buntsdoubleNumber of sacrifice bunts allowed by the pitcher in this game.
stats_pitching_sac_fliesdoubleNumber of sacrifice flies allowed by the pitcher in this game.
stats_pitching_passed_balldoubleNumber of passed balls that occurred while the pitcher was pitching in this game.
stats_pitching_pop_outsdoubleNumber of outs recorded by the pitcher on infield pop-ups in this game.
stats_pitching_line_outsdoubleNumber of outs recorded by the pitcher on line drives caught in this game.
stats_pitching_notecharacterSupplementary note or annotation attached to the pitcher's boxscore line (e.g., indicating a special circumstance).
stats_batting_notecharacterSupplementary note or annotation attached to the batter's boxscore line (e.g., indicating a special circumstance).

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

Example​

mlb_boxscore(game_pk=716390)

Last validated n/a.

mlb_linescore​

GET /api/v1/game/{gamePk}/linescore — inning-by-inning + current game state.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/game/{game_pk}/linescore

Valid URL: https://statsapi.mlb.com/api/v1/game/716390/linescore

API ParameterPythonPatternRequiredNullableDescription
game_pkgame_pkYgame_pk path parameter.
timecodetimecodeYtimecode 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
numintegerInning number.
ordinal_numcharacterInning ordinal label (e.g. 1st).
home_runsintegerHome runs.
home_hitsintegerHome hits in the inning.
home_errorsintegerHome errors in the inning.
home_left_on_baseintegerHome runners left on base in the inning.
away_runsintegerAway runs scored in the inning.
away_hitsintegerAway hits in the inning.
away_errorsintegerAway errors in the inning.
away_left_on_baseintegerAway runners left on base in the inning.

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

Example​

mlb_linescore(game_pk=716390)

Last validated n/a.

mlb_play_by_play​

GET /api/v1/game/{gamePk}/playByPlay — play-by-play with at-bat detail.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/game/{game_pk}/playByPlay

Valid URL: https://statsapi.mlb.com/api/v1/game/716390/playByPlay

API ParameterPythonPatternRequiredNullableDescription
game_pkgame_pkYgame_pk path parameter.
timecodetimecodeYtimecode 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
pitch_indexcharacterA serialized list of indices identifying individual pitch events that occurred within this at-bat.
action_indexcharacterA serialized list of indices identifying action-type events (e.g., stolen bases, pickoffs) that occurred within the at-bat.
runner_indexcharacterA serialized list of indices identifying baserunner movement events that occurred during or after this play.
runnerscharacterA serialized representation of baserunner movement records for this play, including starting base, ending base, and relevant event types.
play_eventscharacterA serialized representation of the sequence of individual pitch and action events comprising this at-bat.
play_end_timecharacterThe ISO 8601 timestamp marking the conclusion of the entire play (as distinct from a single pitch event) within the game feed.
at_bat_indexintegerZero-based index of the at-bat within the game.
result_typecharacterThe high-level category of the play result as classified by the MLB Stats API (e.g., 'atBat', 'action').
result_eventcharacterThe short categorical label for the play outcome as classified by the MLB Stats API (e.g., 'Strikeout', 'Home Run', 'Walk').
result_event_typecharacterThe snake-cased type identifier for the play outcome used internally by the MLB Stats API (e.g., 'strikeout', 'home_run').
result_descriptioncharacterA human-readable text description of the play result as reported by the MLB Stats API (e.g., 'Strikeout', 'Single to left field').
result_rbiintegerThe number of runs batted in credited to the batter as a result of this play.
result_away_scoreintegerThe away team's cumulative run total at the conclusion of this play.
result_home_scoreintegerThe home team's cumulative run total at the conclusion of this play.
result_is_outlogicalBoolean flag indicating whether the play resulted in the batter being retired (i.e., an out was charged to the batter).
about_at_bat_indexintegerThe sequential index of the at-bat within the game to which this play or pitch event belongs.
about_half_inningcharacterIndicates whether the play occurred in the top or bottom half of the inning (e.g., 'top' or 'bottom').
about_is_top_inninglogicalBoolean flag indicating whether this play occurred in the top half of the inning (true) or bottom half (false).
about_inningintegerThe inning number in which this play or pitch event occurred.
about_start_timecharacterThe ISO 8601 timestamp marking the start of the play event, used for temporal sequencing within the game feed.
about_end_timecharacterThe ISO 8601 timestamp marking the end of the play event, used for temporal sequencing within the game feed.
about_is_completelogicalBoolean flag indicating whether the at-bat or play event has concluded (i.e., reached a terminal result).
about_is_scoring_playlogicalBoolean flag indicating whether this play resulted in one or more runs being scored.
about_has_reviewlogicalBoolean flag indicating whether this play was subject to a manager's challenge or umpire review.
about_has_outlogicalBoolean flag indicating whether this play resulted in at least one out being recorded.
about_captivating_indexintegerA numeric score assigned by the MLB Stats API reflecting how compelling or exciting a given play was, based on leverage and game context.
count_ballsintegerThe ball count in the current at-bat at the time of this pitch or play event.
count_strikesintegerThe strike count in the current at-bat at the time of this pitch or play event.
count_outsintegerThe number of outs recorded in the current half-inning at the time of this pitch or play event.
matchup_batter_idintegerThe MLB Stats API (MLBAM) numeric identifier for the batter in this play's matchup.
matchup_batter_full_namecharacterThe full name of the batter involved in this plate appearance.
matchup_batter_linkcharacterThe MLB Stats API relative URL linking to the batter's player resource for this matchup.
matchup_bat_side_codecharacterA single-character code indicating the batter's handedness for this matchup (e.g., 'L' for left, 'R' for right, 'S' for switch).
matchup_bat_side_descriptioncharacterThe human-readable description of the batter's hitting side for this matchup (e.g., 'Left', 'Right', 'Switch').
matchup_pitcher_idintegerThe MLB Stats API (MLBAM) numeric identifier for the pitcher in this play's matchup.
matchup_pitcher_full_namecharacterThe full name of the pitcher involved in this plate appearance.
matchup_pitcher_linkcharacterThe MLB Stats API relative URL linking to the pitcher's player resource for this matchup.
matchup_pitch_hand_codecharacterA single-character code indicating the pitcher's throwing hand for this matchup (e.g., 'L' for left, 'R' for right).
matchup_pitch_hand_descriptioncharacterThe human-readable description of the pitcher's throwing arm for this matchup (e.g., 'Left', 'Right').
matchup_post_on_first_iddoubleThe MLB Stats API (MLBAM) numeric identifier for the runner on first base after the play concluded.
matchup_post_on_first_full_namecharacterThe full name of the baserunner on first base after the play concluded, if applicable.
matchup_post_on_first_linkcharacterThe MLB Stats API relative URL linking to the player resource of the runner on first base after the play.
matchup_batter_hot_cold_zonescharacterA serialized representation of the batter's hot and cold zone effectiveness data for this matchup context.
matchup_pitcher_hot_cold_zonescharacterA serialized representation of the pitcher's hot and cold zone effectiveness data for this matchup context.
matchup_splits_battercharacterA string describing the batter's situational split relevant to this matchup (e.g., 'vs. Right' or 'vs. Left').
matchup_splits_pitchercharacterA string describing the pitcher's situational split relevant to this matchup (e.g., 'vs. Left' or 'vs. Right').
matchup_splits_men_on_basecharacterA string describing the baserunner configuration applicable to the batter's situational split for this plate appearance.
matchup_post_on_second_iddoubleThe MLB Stats API (MLBAM) numeric identifier for the runner on second base after the play concluded.
matchup_post_on_second_full_namecharacterThe full name of the baserunner on second base after the play concluded, if applicable.
matchup_post_on_second_linkcharacterThe MLB Stats API relative URL linking to the player resource of the runner on second base after the play.
matchup_post_on_third_iddoubleThe MLB Stats API (MLBAM) numeric identifier for the runner on third base after the play concluded.
matchup_post_on_third_full_namecharacterThe full name of the baserunner on third base after the play concluded, if applicable.
matchup_post_on_third_linkcharacterThe MLB Stats API relative URL linking to the player resource of the runner on third base after the play.
review_details_is_overturnedlogicalBoolean flag indicating whether the original on-field call was reversed as a result of the replay review.
review_details_in_progresslogicalBoolean flag indicating whether the umpire review of this play was still ongoing at the time of data capture.
review_details_review_typecharacterThe type of review mechanism applied to this play (e.g., 'managerChallenge', 'umpireReview').
review_details_challenge_team_iddoubleThe MLB Stats API numeric identifier for the team that initiated the manager's challenge review on this play.

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

Example​

mlb_play_by_play(game_pk=716390)

Last validated n/a.

mlb_game_context_metrics​

GET /api/v1/game/{gamePk}/contextMetrics — WP, leverage index, in-game context.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/game/{game_pk}/contextMetrics

Valid URL: https://statsapi.mlb.com/api/v1/game/716390/contextMetrics

API ParameterPythonPatternRequiredNullableDescription
game_pkgame_pkYgame_pk path parameter.
fieldsfieldsYfields query parameter.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame (parser: parse_mlb_api_list); pass return_as_pandas=True for a pandas.DataFrame. return_parsed=False — the raw JSON Dict payload, unparsed.

Example​

mlb_game_context_metrics(game_pk=716390)

Last validated n/a.

mlb_win_probability​

GET /api/v1/game/{gamePk}/winProbability — per-play WP timeline.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/game/{game_pk}/winProbability

Valid URL: https://statsapi.mlb.com/api/v1/game/716390/winProbability

API ParameterPythonPatternRequiredNullableDescription
game_pkgame_pkYgame_pk path 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
pitch_indexcharacterA serialized list of indices identifying individual pitch events within the at-bat for this win-probability row.
action_indexcharacterA serialized list of indices identifying action-type events (stolen bases, pickoffs, etc.) within the at-bat for this win-probability row.
runner_indexcharacterA serialized list of indices identifying baserunner movement events during the play in this win-probability row.
runnerscharacterA serialized representation of baserunner movement records for this play in the win-probability feed, capturing start/end base positions and event types.
play_eventscharacterA serialized representation of the sequence of pitch and action events comprising the at-bat for this win-probability row.
creditscharacterA serialized list of player credit records for this play, linking fielding, pitching, or batting achievements to specific player identifiers.
flagscharacterA serialized representation of situational boolean flags associated with this play (e.g., whether it was a big lead situation or a save opportunity).
home_team_win_probabilitydoubleHome team win probability (percent) entering the at-bat.
away_team_win_probabilitydoubleAway team win probability (percent) entering the at-bat.
home_team_win_probability_addeddoubleChange in home team win probability attributed to the at-bat.
play_end_timecharacterThe ISO 8601 timestamp marking the conclusion of the play associated with this win-probability snapshot.
at_bat_indexintegerZero-based index of the at-bat within the game.
result_typecharacterThe high-level category of the play result in the win-probability feed (e.g., 'atBat', 'action').
result_eventcharacterThe short categorical label for the play outcome in the win-probability feed (e.g., 'Single', 'Home Run', 'Strikeout').
result_event_typecharacterThe snake-cased type identifier for the play outcome in the win-probability feed (e.g., 'single', 'home_run').
result_descriptioncharacterA human-readable text description of the play result as reported in the win-probability game feed.
result_rbiintegerThe number of runs batted in credited to the batter for the play in this win-probability row.
result_away_scoreintegerThe away team's cumulative run total at the conclusion of the play in this win-probability row.
result_home_scoreintegerThe home team's cumulative run total at the conclusion of the play in this win-probability row.
result_is_outlogicalBoolean flag indicating whether the batter was retired on the play recorded in this win-probability row.
about_at_bat_indexintegerThe sequential index of the at-bat within the game to which this win-probability observation belongs.
about_half_inningcharacterIndicates whether the win-probability observation occurred in the top or bottom half of the inning.
about_is_top_inninglogicalBoolean flag indicating whether this win-probability observation occurred in the top half of the inning.
about_inningintegerThe inning number in which this win-probability observation was recorded.
about_start_timecharacterThe ISO 8601 timestamp marking the start of the play event within the win-probability game feed.
about_end_timecharacterThe ISO 8601 timestamp marking the end of the play event within the win-probability game feed.
about_is_completelogicalBoolean flag indicating whether the at-bat associated with this win-probability row has concluded.
about_is_scoring_playlogicalBoolean flag indicating whether this play resulted in one or more runs being scored.
about_has_reviewlogicalBoolean flag indicating whether this play was subject to a manager's challenge or umpire review.
about_has_outlogicalBoolean flag indicating whether this play resulted in at least one out being recorded.
about_captivating_indexintegerA numeric score reflecting how compelling or exciting this plate appearance was, based on leverage and game-state context.
count_ballsintegerThe ball count in the current at-bat at the time this win-probability snapshot was recorded.
count_strikesintegerThe strike count in the current at-bat at the time this win-probability snapshot was recorded.
count_outsintegerThe number of outs in the current half-inning at the time this win-probability snapshot was recorded.
matchup_batter_idintegerThe MLB Stats API (MLBAM) numeric identifier for the batter in this win-probability matchup row.
matchup_batter_full_namecharacterThe full name of the batter whose plate appearance generated this win-probability observation.
matchup_batter_linkcharacterThe MLB Stats API relative URL linking to the batter's player resource for this win-probability row.
matchup_bat_side_codecharacterA single-character code indicating the batter's handedness for this matchup in the win-probability feed (e.g., 'L', 'R', 'S').
matchup_bat_side_descriptioncharacterThe human-readable description of the batter's hitting side for this win-probability matchup row.
matchup_pitcher_idintegerThe MLB Stats API (MLBAM) numeric identifier for the pitcher in this win-probability matchup row.
matchup_pitcher_full_namecharacterThe full name of the pitcher who delivered pitches for this win-probability observation.
matchup_pitcher_linkcharacterThe MLB Stats API relative URL linking to the pitcher's player resource for this win-probability row.
matchup_pitch_hand_codecharacterA single-character code indicating the pitcher's throwing hand for this win-probability matchup (e.g., 'L' or 'R').
matchup_pitch_hand_descriptioncharacterThe human-readable description of the pitcher's throwing arm for this win-probability matchup row.
matchup_post_on_first_iddoubleThe MLB Stats API (MLBAM) numeric identifier for the runner on first base after the play in this win-probability row.
matchup_post_on_first_full_namecharacterThe full name of the runner occupying first base at the conclusion of the play in this win-probability row.
matchup_post_on_first_linkcharacterThe MLB Stats API relative URL linking to the player resource of the runner on first base after the play.
matchup_batter_hot_cold_zonescharacterA serialized representation of the batter's hot and cold zone data applicable to this win-probability matchup.
matchup_pitcher_hot_cold_zonescharacterA serialized representation of the pitcher's hot and cold zone data applicable to this win-probability matchup.
matchup_splits_battercharacterA string describing the batter's situational split for this win-probability matchup (e.g., 'vs. Right').
matchup_splits_pitchercharacterA string describing the pitcher's situational split for this win-probability matchup (e.g., 'vs. Left').
matchup_splits_men_on_basecharacterA string describing the baserunner configuration applicable to the batter's situational split in this win-probability row.
leverage_indexdoubleLeverage index quantifying the importance of the at-bat situation.
drama_indexdoubleA numeric score quantifying the dramatic significance of this play within the game, based on win-probability swing and game leverage.
matchup_post_on_second_iddoubleThe MLB Stats API (MLBAM) numeric identifier for the runner on second base after the play in this win-probability row.
matchup_post_on_second_full_namecharacterThe full name of the runner occupying second base at the conclusion of the play in this win-probability row.
matchup_post_on_second_linkcharacterThe MLB Stats API relative URL linking to the player resource of the runner on second base after the play.
matchup_post_on_third_iddoubleThe MLB Stats API (MLBAM) numeric identifier for the runner on third base after the play in this win-probability row.
matchup_post_on_third_full_namecharacterThe full name of the runner occupying third base at the conclusion of the play in this win-probability row.
matchup_post_on_third_linkcharacterThe MLB Stats API relative URL linking to the player resource of the runner on third base after the play.
review_details_is_overturnedlogicalBoolean flag indicating whether the original on-field ruling was reversed following the replay review for this play.
review_details_in_progresslogicalBoolean flag indicating whether a replay review of this play was still underway at the time of data capture.
review_details_review_typecharacterThe type of review mechanism applied to this play in the win-probability feed (e.g., 'managerChallenge', 'umpireReview').
review_details_challenge_team_iddoubleThe MLB Stats API numeric identifier for the team that initiated a replay challenge on this win-probability play.

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

Example​

mlb_win_probability(game_pk=716390)

Last validated n/a.

mlb_game_content​

GET /api/v1/game/{gamePk}/content — articles, highlights, editorial content.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/game/{game_pk}/content

Valid URL: https://statsapi.mlb.com/api/v1/game/716390/content

API ParameterPythonPatternRequiredNullableDescription
game_pkgame_pkYgame_pk path parameter.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame (parser: parse_mlb_api_list); pass return_as_pandas=True for a pandas.DataFrame. return_parsed=False — the raw JSON Dict payload, unparsed.

Example​

mlb_game_content(game_pk=716390)

Last validated n/a.

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

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_statuscharacterAll-star status flag.
idintegerId.
namecharacterDisplay name.
linkcharacterAPI link to the game feed.
seasonintegerSeason year.
team_codecharacterInternal team code.
file_codecharacterFile code abbreviation.
abbreviationcharacterShort abbreviation.
team_namecharacterTeam name.
location_namecharacterTeam location (city).
first_year_of_playcharacterFirst year the franchise played.
short_namecharacterShort display name.
franchise_namecharacterFranchise name.
club_namecharacterClub name.
activelogicalWhether the player is currently active.
spring_league_idintegerSpring league MLBAM ID.
spring_league_namecharacterSpring league name.
spring_league_linkcharacterAPI link to the spring league.
spring_league_abbreviationcharacterSpring league abbreviation.
venue_idintegerMLBAM venue ID.
venue_namecharacterVenue name.
venue_linkcharacterAPI link to the venue.
spring_venue_idintegerSpring training venue MLBAM ID.
spring_venue_linkcharacterAPI link to the spring venue.
league_idintegerLeague MLBAM ID.
league_namecharacterLeague name.
league_linkcharacterAPI link to the league.
division_idintegerDivision MLBAM ID.
division_namecharacterDivision name.
division_linkcharacterAPI link to the division.
sport_idintegerSport MLBAM ID.
sport_linkcharacterAPI link to the sport.
sport_namecharacterSport name (e.g., Major League Baseball).

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

Example​

mlb_team(team_id=10)

Last validated n/a.

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

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_numbercharacterJersey number worn (often blank for non-uniformed roles).
person_idintegerMLB player ID.
person_full_namecharacterPlayer full name.
person_linkcharacterAPI relative link to the person.
position_codecharacterNumeric scorekeeping position code.
position_namecharacterFull position name (e.g. 'Point Guard', 'Goalkeeper').
position_typecharacterPosition category (e.g. 'Pitcher', 'Infielder').
position_abbreviationcharacterPosition abbreviation.
status_codecharacterStatus code identifier (e.g. 'S', 'P', 'I', 'F').
status_descriptioncharacterRoster status description (e.g. 'Active').

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

Example​

mlb_team_roster(team_id=10)

Last validated n/a.

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

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
idintegerId.
full_namecharacterPlayer's full name.
linkcharacterAPI link to the game feed.
first_namecharacterPlayer first name.
last_namecharacterPlayer last name.
primary_numbercharacterPlayer uniform number.
birth_datecharacterDate of birth (YYYY-MM-DD).
current_ageintegerCurrent age in years.
birth_citycharacterCity of birth.
birth_countrycharacterCountry of birth.
heightcharacterHeight (feet and inches).
weightintegerWeight in pounds.
activelogicalWhether the player is currently active.
use_namecharacterPreferred first name.
use_last_namecharacterPreferred last name.
middle_namecharacterPlayer middle name.
boxscore_namecharacterName as shown in box scores.
nick_namecharacterPlayer nickname.
gendercharacterPlayer gender.
is_playerlogicalWhether the person is a player.
is_verifiedlogicalWhether the player profile is verified.
pronunciationcharacterPhonetic name pronunciation.
mlb_debut_datecharacterMLB debut date (YYYY-MM-DD).
name_first_lastcharacterName in first-last order.
name_slugcharacterURL-friendly name slug.
first_last_namecharacterFirst and last name.
last_first_namecharacterName in last, first order.
last_init_namecharacterLast name with first initial.
init_last_namecharacterFirst initial with last name.
full_fml_namecharacterFull name (first-middle-last).
full_lfm_namecharacterFull name (last-first-middle).
strike_zone_topdoubleTop of the player's strike zone (feet).
strike_zone_bottomdoubleBottom of the player's strike zone (feet).
alumni_last_seasoncharacterLast season the player was with the team.
primary_position_codecharacterPrimary position code.
primary_position_namecharacterPrimary fielding position name.
primary_position_typecharacterPrimary position type (e.g. Infielder).
primary_position_abbreviationcharacterPrimary position abbreviation.
bat_side_codecharacterBatting side code (L/R/S).
bat_side_descriptioncharacterBatting side description.
pitch_hand_codecharacterThrowing hand code (L/R).
pitch_hand_descriptioncharacterThrowing hand description.
birth_state_provincecharacterState or province of birth.
draft_yeardoubleYear the player was drafted.
last_played_datecharacterDate of last MLB game played.
name_matrilinealcharacterMaternal family name.

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

Example​

mlb_team_alumni(team_id=10)

Last validated n/a.

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

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_statuscharacterAll-star status flag.
idintegerId.
namecharacterDisplay name.
linkcharacterAPI link to the game feed.
seasonintegerSeason year.
team_codecharacterInternal team code.
file_codecharacterFile code abbreviation.
abbreviationcharacterShort abbreviation.
team_namecharacterTeam name.
location_namecharacterTeam location (city).
first_year_of_playcharacterFirst year the franchise played.
short_namecharacterShort display name.
franchise_namecharacterFranchise name.
club_namecharacterClub name.
activelogicalWhether the player is currently active.
spring_league_iddoubleSpring league MLBAM ID.
spring_league_namecharacterSpring league name.
spring_league_linkcharacterAPI link to the spring league.
spring_league_abbreviationcharacterSpring league abbreviation.
venue_idintegerMLBAM venue ID.
venue_namecharacterVenue name.
venue_linkcharacterAPI link to the venue.
spring_venue_iddoubleSpring training venue MLBAM ID.
spring_venue_linkcharacterAPI link to the spring venue.
league_iddoubleLeague MLBAM ID.
league_namecharacterLeague name.
league_linkcharacterAPI link to the league.
division_iddoubleDivision MLBAM ID.
division_namecharacterDivision name.
division_linkcharacterAPI link to the division.
sport_idintegerSport MLBAM ID.
sport_linkcharacterAPI link to the sport.
sport_namecharacterSport name (e.g., Major League Baseball).
parent_org_namecharacterParent organization name.
parent_org_iddoubleParent organization MLBAM ID.

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

Example​

mlb_team_affiliates()

Last validated n/a.

mlb_people​

GET /api/v1/people?personIds=... — bulk person lookup by MLBAM id.

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

Valid URL: https://statsapi.mlb.com/api/v1/people

API ParameterPythonPatternRequiredNullableDescription
personIdsperson_idsYpersonIds 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
idintegerId.
full_namecharacterPlayer's full name.
linkcharacterAPI link to the game feed.
first_namecharacterPlayer first name.
last_namecharacterPlayer last name.
primary_numbercharacterPlayer uniform number.
birth_datecharacterDate of birth (YYYY-MM-DD).
current_ageintegerCurrent age in years.
birth_citycharacterCity of birth.
birth_countrycharacterCountry of birth.
heightcharacterHeight (feet and inches).
weightintegerWeight in pounds.
activelogicalWhether the player is currently active.
use_namecharacterPreferred first name.
use_last_namecharacterPreferred last name.
boxscore_namecharacterName as shown in box scores.
nick_namecharacterPlayer nickname.
gendercharacterPlayer gender.
is_playerlogicalWhether the person is a player.
is_verifiedlogicalWhether the player profile is verified.
pronunciationcharacterPhonetic name pronunciation.
mlb_debut_datecharacterMLB debut date (YYYY-MM-DD).
name_first_lastcharacterName in first-last order.
name_slugcharacterURL-friendly name slug.
first_last_namecharacterFirst and last name.
last_first_namecharacterName in last, first order.
last_init_namecharacterLast name with first initial.
init_last_namecharacterFirst initial with last name.
full_fml_namecharacterFull name (first-middle-last).
full_lfm_namecharacterFull name (last-first-middle).
strike_zone_topdoubleTop of the player's strike zone (feet).
strike_zone_bottomdoubleBottom of the player's strike zone (feet).
primary_position_codecharacterPrimary position code.
primary_position_namecharacterPrimary fielding position name.
primary_position_typecharacterPrimary position type (e.g. Infielder).
primary_position_abbreviationcharacterPrimary position abbreviation.
bat_side_codecharacterBatting side code (L/R/S).
bat_side_descriptioncharacterBatting side description.
pitch_hand_codecharacterThrowing hand code (L/R).
pitch_hand_descriptioncharacterThrowing hand description.
birth_state_provincecharacterState or province of birth.
middle_namecharacterPlayer middle name.
draft_yeardoubleYear the player was drafted.

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

Example​

mlb_people()

Last validated n/a.

mlb_person​

GET /api/v1/people/{personId} — single person detail.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/people/{person_id}

Valid URL: https://statsapi.mlb.com/api/v1/people/660271

API ParameterPythonPatternRequiredNullableDescription
person_idperson_idYperson_id path parameter.
seasonseasonYSeason year (e.g. 2024).
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
idintegerId.
full_namecharacterPlayer's full name.
linkcharacterAPI link to the game feed.
first_namecharacterPlayer first name.
last_namecharacterPlayer last name.
primary_numbercharacterPlayer uniform number.
birth_datecharacterDate of birth (YYYY-MM-DD).
current_ageintegerCurrent age in years.
birth_citycharacterCity of birth.
birth_countrycharacterCountry of birth.
heightcharacterHeight (feet and inches).
weightintegerWeight in pounds.
activelogicalWhether the player is currently active.
use_namecharacterPreferred first name.
use_last_namecharacterPreferred last name.
boxscore_namecharacterName as shown in box scores.
nick_namecharacterPlayer nickname.
gendercharacterPlayer gender.
is_playerlogicalWhether the person is a player.
is_verifiedlogicalWhether the player profile is verified.
pronunciationcharacterPhonetic name pronunciation.
mlb_debut_datecharacterMLB debut date (YYYY-MM-DD).
name_first_lastcharacterName in first-last order.
name_slugcharacterURL-friendly name slug.
first_last_namecharacterFirst and last name.
last_first_namecharacterName in last, first order.
last_init_namecharacterLast name with first initial.
init_last_namecharacterFirst initial with last name.
full_fml_namecharacterFull name (first-middle-last).
full_lfm_namecharacterFull name (last-first-middle).
strike_zone_topdoubleTop of the player's strike zone (feet).
strike_zone_bottomdoubleBottom of the player's strike zone (feet).
primary_position_codecharacterPrimary position code.
primary_position_namecharacterPrimary fielding position name.
primary_position_typecharacterPrimary position type (e.g. Infielder).
primary_position_abbreviationcharacterPrimary position abbreviation.
bat_side_codecharacterBatting side code (L/R/S).
bat_side_descriptioncharacterBatting side description.
pitch_hand_codecharacterThrowing hand code (L/R).
pitch_hand_descriptioncharacterThrowing hand description.

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

Example​

mlb_person(person_id=660271)

Last validated n/a.

mlb_person_game_stats​

GET /api/v1/people/{personId}/stats/game/{gamePk} — one player, one game.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/people/{person_id}/stats/game/{game_pk}

Valid URL: https://statsapi.mlb.com/api/v1/people/660271/stats/game/716390

API ParameterPythonPatternRequiredNullableDescription
person_idperson_idYperson_id path parameter.
game_pkgame_pkYgame_pk path 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_splitsdoubleTotal number of splits in the leaderboard.
exemptionscharacterSerialized list of statistical exemptions or special-case flags applied to this player's game-log splits.
splitscharacterSplits.
type_display_namecharacterStat type display name.
group_display_namecharacterStat group display name.

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

Example​

mlb_person_game_stats(person_id=660271, game_pk=716390)

Last validated n/a.

mlb_sport_players​

GET /api/v1/sports/{sportId}/players — every player in a sport for a season.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/sports/{sport_id}/players

Valid URL: https://statsapi.mlb.com/api/v1/sports

API ParameterPythonPatternRequiredNullableDescription
sport_idsport_idYsport_id path parameter.
seasonseasonYSeason year (e.g. 2024).
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
idintegerId.
full_namecharacterPlayer's full name.
linkcharacterAPI link to the game feed.
first_namecharacterPlayer first name.
last_namecharacterPlayer last name.
primary_numbercharacterPlayer uniform number.
birth_datecharacterDate of birth (YYYY-MM-DD).
current_ageintegerCurrent age in years.
birth_citycharacterCity of birth.
birth_state_provincecharacterState or province of birth.
birth_countrycharacterCountry of birth.
heightcharacterHeight (feet and inches).
weightintegerWeight in pounds.
activelogicalWhether the player is currently active.
use_namecharacterPreferred first name.
use_last_namecharacterPreferred last name.
middle_namecharacterPlayer middle name.
boxscore_namecharacterName as shown in box scores.
gendercharacterPlayer gender.
is_playerlogicalWhether the person is a player.
is_verifiedlogicalWhether the player profile is verified.
draft_yeardoubleYear the player was drafted.
mlb_debut_datecharacterMLB debut date (YYYY-MM-DD).
name_first_lastcharacterName in first-last order.
name_slugcharacterURL-friendly name slug.
first_last_namecharacterFirst and last name.
last_first_namecharacterName in last, first order.
last_init_namecharacterLast name with first initial.
init_last_namecharacterFirst initial with last name.
full_fml_namecharacterFull name (first-middle-last).
full_lfm_namecharacterFull name (last-first-middle).
strike_zone_topdoubleTop of the player's strike zone (feet).
strike_zone_bottomdoubleBottom of the player's strike zone (feet).
current_team_idintegerCurrent team MLBAM ID.
current_team_namecharacterCurrent team name.
current_team_linkcharacterAPI link to the current team.
primary_position_codecharacterPrimary position code.
primary_position_namecharacterPrimary fielding position name.
primary_position_typecharacterPrimary position type (e.g. Infielder).
primary_position_abbreviationcharacterPrimary position abbreviation.
bat_side_codecharacterBatting side code (L/R/S).
bat_side_descriptioncharacterBatting side description.
pitch_hand_codecharacterThrowing hand code (L/R).
pitch_hand_descriptioncharacterThrowing hand description.
name_matrilinealcharacterMaternal family name.
nick_namecharacterPlayer nickname.
pronunciationcharacterPhonetic name pronunciation.
last_played_datecharacterDate of last MLB game played.
name_titlecharacterName title.
name_suffixcharacterName suffix (e.g. Jr., Sr., III).

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

Example​

mlb_sport_players()

Last validated n/a.

mlb_sports​

GET /api/v1/sports — list known sports (MLB, MiLB, KBO, NPB, …).

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

Valid URL: https://statsapi.mlb.com/api/v1/sports

API ParameterPythonPatternRequiredNullableDescription
sportIdsport_idYsportId 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
idintegerId.
codecharacterFielder detail type code.
linkcharacterAPI link to the game feed.
namecharacterDisplay name.
abbreviationcharacterShort abbreviation.
sort_orderintegerDisplay sort order for the sport.
active_statuslogicalWhether the sport/level is active.

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

Example​

mlb_sports()

Last validated n/a.

mlb_leagues​

GET /api/v1/leagues — list leagues.

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

Valid URL: https://statsapi.mlb.com/api/v1/leagues

API ParameterPythonPatternRequiredNullableDescription
sportIdsport_idYsportId query parameter.
seasonseasonYSeason year (e.g. 2024).
leagueIdsleague_idsYleagueIds 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
idintegerId.
namecharacterDisplay name.
linkcharacterAPI link to the game feed.
abbreviationcharacterShort abbreviation.
name_shortcharacterShort name of player (First Initial, Last Name)
season_statecharacterA string describing the current phase of the league's season (e.g., 'inProgress', 'offseason', 'preseason').
has_wild_cardlogicalBoolean flag indicating whether this league includes a wild card playoff format for postseason eligibility.
has_split_seasonlogicalBoolean flag indicating whether this league divides its season into two halves with separate standings (as used historically in some minor leagues).
num_gamesdoubleThe total number of regular-season games scheduled per team in this league for the given season.
has_playoff_pointslogicalBoolean flag indicating whether this league uses a playoff points system to determine postseason seeding.
num_teamsdoubleNumber of teams the player appeared for.
num_wildcard_teamsdoubleThe number of wild card berths available for postseason entry in this league for the given season.
seasoncharacterSeason year.
org_codecharacterThe organizational code identifying the parent body (e.g., 'MLB') governing this league within the MLB Stats API hierarchy.
conferences_in_uselogicalWhether conferences were in use that season.
divisions_in_uselogicalWhether divisions were in use that season.
sort_orderintegerDisplay sort order for the sport.
activelogicalWhether the player is currently active.
season_date_info_season_idcharacterSeason identifier for the date info block.
season_date_info_pre_season_start_datecharacterPreseason start date (YYYY-MM-DD).
season_date_info_pre_season_end_datecharacterPreseason end date (YYYY-MM-DD).
season_date_info_season_start_datecharacterSeason start date (YYYY-MM-DD).
season_date_info_spring_start_datecharacterSpring training start date (YYYY-MM-DD).
season_date_info_spring_end_datecharacterSpring training end date (YYYY-MM-DD).
season_date_info_regular_season_start_datecharacterRegular season start date (YYYY-MM-DD).
season_date_info_last_date1st_halfcharacterLast date of the first half (YYYY-MM-DD).
season_date_info_all_star_datecharacterAll-Star Game date (YYYY-MM-DD).
season_date_info_first_date2nd_halfcharacterFirst date of the second half (YYYY-MM-DD).
season_date_info_regular_season_end_datecharacterRegular season end date (YYYY-MM-DD).
season_date_info_post_season_start_datecharacterPostseason start date (YYYY-MM-DD).
season_date_info_post_season_end_datecharacterPostseason end date (YYYY-MM-DD).
season_date_info_season_end_datecharacterSeason end date (YYYY-MM-DD).
season_date_info_offseason_start_datecharacterOffseason start date (YYYY-MM-DD).
season_date_info_off_season_end_datecharacterOffseason end date (YYYY-MM-DD).
season_date_info_season_level_gameday_typecharacterSeason-level Gameday data type code.
season_date_info_game_level_gameday_typecharacterGame-level Gameday data type code.
season_date_info_qualifier_plate_appearancesdoublePlate appearances per game needed to qualify.
season_date_info_qualifier_outs_pitcheddoubleOuts pitched per game needed to qualify.
sport_iddoubleSport MLBAM ID.
sport_linkcharacterAPI link to the sport.

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

Example​

mlb_leagues()

Last validated n/a.

mlb_season​

GET /api/v1/seasons/{seasonId} — single season detail.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/seasons/{season_id}

Valid URL: https://statsapi.mlb.com/api/v1/seasons/X

API ParameterPythonPatternRequiredNullableDescription
season_idseason_idYseason_id path parameter.
sportIdsport_idYsportId 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
season_idcharacterSeason year identifier.
has_wildcardlogicalWhether the season has a wild card round.
pre_season_start_datecharacterPre-season start date.
pre_season_end_datecharacterPre-season end date.
season_start_datecharacterSeason start date.
spring_start_datecharacterSpring training start date.
spring_end_datecharacterSpring training end date.
regular_season_start_datecharacterRegular season start date.
last_date1st_halfcharacterLast date of the first half.
all_star_datecharacterAll-Star Game date.
first_date2nd_halfcharacterFirst date of the second half.
regular_season_end_datecharacterRegular season end date.
post_season_start_datecharacterPost-season start date.
post_season_end_datecharacterPost-season end date.
season_end_datecharacterSeason end date.
offseason_start_datecharacterOff-season start date.
off_season_end_datecharacterOff-season end date.
season_level_gameday_typecharacterSeason-level Gameday data feed type.
game_level_gameday_typecharacterGame-level Gameday data feed type.
qualifier_plate_appearancesdoublePlate appearances per team game to qualify.
qualifier_outs_pitcheddoubleOuts pitched per team game to qualify.

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

Example​

mlb_season(season_id='X')

Last validated n/a.

mlb_venues​

GET /api/v1/venues — list venues.

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

Valid URL: https://statsapi.mlb.com/api/v1/venues

API ParameterPythonPatternRequiredNullableDescription
seasonseasonYSeason year (e.g. 2024).
sportIdssport_idsYsportIds query parameter.
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
idintegerId.
namecharacterDisplay name.
linkcharacterAPI link to the game feed.
activelogicalWhether the player is currently active.
seasoncharacterSeason year.

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

Example​

mlb_venues()

Last validated n/a.

mlb_venue​

GET /api/v1/venues/{venueId} — single venue detail.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/venues/{venue_id}

Valid URL: https://statsapi.mlb.com/api/v1/venues/15

API ParameterPythonPatternRequiredNullableDescription
venue_idvenue_idYvenue_id path 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
idintegerId.
namecharacterDisplay name.
linkcharacterAPI link to the game feed.
activelogicalWhether the player is currently active.
seasoncharacterSeason year.

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

Example​

mlb_venue(venue_id=15)

Last validated n/a.

mlb_meta​

GET /api/v1/{metaType} — enum lookup (the API's self-describing surface).

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

Valid URL: https://statsapi.mlb.com/api/v1/leagueLeaderTypes

API ParameterPythonPatternRequiredNullableDescription
meta_typemeta_typeYmeta_type path parameter.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame (parser: parse_mlb_api_list); pass return_as_pandas=True for a pandas.DataFrame. return_parsed=False — the raw JSON Dict payload, unparsed.

Example​

mlb_meta(meta_type='leagueLeaderTypes')

Last validated n/a.

mlb_awards​

GET /api/v1/awards — list award IDs (call with no params to enumerate).

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

Valid URL: https://statsapi.mlb.com/api/v1/awards

API ParameterPythonPatternRequiredNullableDescription
sportIdsport_idYsportId 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
idcharacterId.
namecharacterDisplay name.
descriptioncharacterLong-form description text.
sort_orderdoubleDisplay sort order for the sport.
activelogicalWhether the player is currently active.
sport_iddoubleSport MLBAM ID.
sport_linkcharacterAPI link to the sport.
league_iddoubleLeague MLBAM ID.
league_linkcharacterAPI link to the league.
notescharacterNotes.

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

Example​

mlb_awards()

Last validated n/a.

mlb_award_recipients​

GET /api/v1/awards/{awardId}/recipients — historical winners of one award.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/awards/{award_id}/recipients

Valid URL: https://statsapi.mlb.com/api/v1/awards/MLBHOF/recipients

API ParameterPythonPatternRequiredNullableDescription
award_idaward_idYaward_id path parameter.
seasonseasonYSeason year (e.g. 2024).
sportIdsport_idYsportId query parameter.
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
idcharacterId.
namecharacterDisplay name.
datecharacterDate in YYYY-MM-DD format.
seasoncharacterSeason year.
team_idintegerUnique ESPN team identifier.
team_linkcharacterAPI link to the team.
player_idintegerMLBAM player ID.
player_linkcharacterAPI relative link to the player.
player_primary_position_codecharacterRecipient primary fielding position code.
player_primary_position_namecharacterRecipient primary fielding position name.
player_primary_position_typecharacterParticipant primary position type (e.g. 'Hitter').
player_primary_position_abbreviationcharacterParticipant primary position abbreviation (e.g. 'DH').
player_name_first_lastcharacterParticipant name in first-last order.
votesdoubleNumber of votes received.

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

Example​

mlb_award_recipients(award_id='MLBHOF')

Last validated n/a.

mlb_draft​

GET /api/v1/draft/{year} — draft results for a year (optionally one round).

Endpoint URL: GET https://statsapi.mlb.com/api/v1/draft/{year}

Valid URL: https://statsapi.mlb.com/api/v1/draft/2024

API ParameterPythonPatternRequiredNullableDescription
yearyearYyear path parameter.
roundround_Yround query parameter.
teamIdteam_idYteamId query parameter.
playerIdplayer_idYplayerId query parameter.
limitlimitYMaximum number of items to return.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame (parser: parse_mlb_api_list); pass return_as_pandas=True for a pandas.DataFrame. return_parsed=False — the raw JSON Dict payload, unparsed.

Example​

mlb_draft(year=2024)

Last validated n/a.

mlb_umpires​

GET /api/v1/jobs/umpires — current umpire crew assignments.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/jobs/umpires

Valid URL: https://statsapi.mlb.com/api/v1/jobs/umpires

API ParameterPythonPatternRequiredNullableDescription

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_numbercharacterJersey number worn (often blank for non-uniformed roles).
jobcharacterJob title (e.g. 'Umpire').
job_idcharacterJob code identifier.
titlecharacterSpecific role title for the assignment.
person_idintegerMLB player ID.
person_full_namecharacterPlayer full name.
person_linkcharacterAPI relative link to the person.

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

Example​

mlb_umpires()

Last validated n/a.

mlb_conferences​

View all PCL conferences.

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

Valid URL: https://statsapi.mlb.com/api/v1/conferences

API ParameterPythonPatternRequiredNullableDescription
conferenceIdconference_idYconferenceId query parameter.
seasonseasonYSeason year (e.g. 2024).
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
idintegerId.
namecharacterDisplay name.
linkcharacterAPI link to the game feed.
abbreviationcharacterShort abbreviation.
has_wildcardlogicalWhether the season has a wild card round.
name_shortcharacterShort name of player (First Initial, Last Name)
league_idintegerLeague MLBAM ID.
league_linkcharacterAPI link to the league.
sport_idintegerSport MLBAM ID.
sport_linkcharacterAPI link to the sport.

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

Example​

mlb_conferences()

Last validated n/a.

mlb_conference​

View PCL conferences by conferenceId.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/conferences/{conference_id}

Valid URL: https://statsapi.mlb.com/api/v1/conferences/301

API ParameterPythonPatternRequiredNullableDescription
conference_idconference_idYconference_id path parameter.
seasonseasonYSeason year (e.g. 2024).
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
idintegerId.
namecharacterDisplay name.
linkcharacterAPI link to the game feed.
abbreviationcharacterShort abbreviation.
has_wildcardlogicalWhether the season has a wild card round.
name_shortcharacterShort name of player (First Initial, Last Name)
league_idintegerLeague MLBAM ID.
league_linkcharacterAPI link to the league.
sport_idintegerSport MLBAM ID.
sport_linkcharacterAPI link to the sport.

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

Example​

mlb_conference(conference_id=301)

Last validated n/a.

mlb_draft_latest​

View latest player drafted, endpoint best used when draft is currently open.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/draft/{year}/latest

Valid URL: https://statsapi.mlb.com/api/v1/draft/2023/latest

API ParameterPythonPatternRequiredNullableDescription
yearyearYyear path 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
numberintegerWeek number as returned by the API.
next_upcharacterIndicates whether this draft slot is the next pick to be made in the current draft.
pick_pick_roundcharacterDraft round in which this pick was made (e.g., '1', '2', 'CB-A' for competitive balance).
pick_pick_numberintegerOverall pick number of this selection counting sequentially across all rounds of the draft.
pick_display_pick_numberintegerThe formatted overall pick number displayed publicly for this draft selection.
pick_round_pick_numberintegerPick number within the specific draft round (i.e., the Nth pick in that round).
pick_signing_bonuscharacterReported or slotted signing bonus amount associated with this draft pick.
pick_home_citycharacterCity of the draftee's listed home address at the time of the draft.
pick_home_statecharacterState or province of the draftee's listed home address at the time of the draft.
pick_home_countrycharacterCountry of the draftee's listed home address at the time of the draft.
pick_school_namecharacterName of the high school or college the draftee attended before being drafted.
pick_school_school_classcharacterAcademic class or level of the draftee at their school (e.g., High School, Junior, Senior).
pick_school_citycharacterCity of the high school or college the draftee attended before being drafted.
pick_school_countrycharacterCountry of the school the draftee attended.
pick_school_statecharacterState of the school the draftee attended.
pick_headshot_linkcharacterURL to the headshot image of the drafted player on the MLB Stats API CDN.
pick_person_idintegerUnique MLB Stats API (MLBAM) identifier for the drafted player.
pick_person_full_namecharacterPlayer's complete display name as used throughout the MLB Stats API.
pick_person_linkcharacterRelative URL path to the player's resource in the MLB Stats API.
pick_person_first_namecharacterThe player's legal or preferred first name.
pick_person_last_namecharacterThe player's legal or preferred last name.
pick_person_birth_datecharacterDate of birth of the drafted player in ISO 8601 format.
pick_person_current_ageintegerAge of the drafted player in years at the time of the data retrieval.
pick_person_birth_citycharacterCity where the drafted player was born.
pick_person_birth_state_provincecharacterState or province where the drafted player was born.
pick_person_birth_countrycharacterCountry where the drafted player was born.
pick_person_heightcharacterPlayer's height in feet-and-inches notation (e.g., 6' 2").
pick_person_weightintegerPlayer's weight in pounds as recorded by the MLB Stats API.
pick_person_activelogicalBoolean flag indicating whether the drafted player is currently on an active MLB roster.
pick_person_primary_position_codecharacterNumeric or short code identifying the player's primary fielding position.
pick_person_primary_position_namecharacterFull name of the player's primary fielding position (e.g., Shortstop, Center Field).
pick_person_primary_position_typecharacterBroad classification of the player's position role (e.g., Pitcher, Infielder, Outfielder).
pick_person_primary_position_abbreviationcharacterShort abbreviation for the player's primary fielding position (e.g., SS, CF, SP).
pick_person_use_namecharacterThe first name or nickname the player prefers to use publicly.
pick_person_use_last_namecharacterThe last name the player prefers to use publicly, which may differ from the legal last name.
pick_person_middle_namecharacterThe player's middle name as recorded by the MLB Stats API.
pick_person_boxscore_namecharacterAbbreviated name format used for the player on official MLB box scores.
pick_person_gendercharacterRecorded gender of the drafted player.
pick_person_is_playerlogicalBoolean flag indicating whether this person is classified as an active player in the MLB Stats API.
pick_person_is_verifiedlogicalBoolean flag indicating whether the player's profile has been verified by MLB.
pick_person_draft_yearintegerThe MLB draft year in which this player was originally selected.
pick_person_bat_side_codecharacterSingle-letter code for the player's batting handedness (e.g., R, L, S for switch).
pick_person_bat_side_descriptioncharacterFull description of the player's batting side (e.g., Right, Left, Switch).
pick_person_pitch_hand_codecharacterSingle-letter code for the player's pitching handedness (e.g., R, L, S).
pick_person_pitch_hand_descriptioncharacterFull description of the player's pitching hand (e.g., Right, Left, Switch).
pick_person_name_first_lastcharacterPlayer's display name in first-last format, typically matching the broadcast name.
pick_person_name_slugcharacterURL-safe slug derived from the player's name for use in web links.
pick_person_first_last_namecharacterPlayer's name formatted as first name followed by last name.
pick_person_last_first_namecharacterPlayer's name formatted as last name followed by first name.
pick_person_last_init_namecharacterPlayer's name formatted as last name followed by first initial.
pick_person_init_last_namecharacterPlayer's name formatted as first initial followed by last name (e.g., J. Smith).
pick_person_full_fml_namecharacterPlayer's full name in first-middle-last order as recorded by the MLB Stats API.
pick_person_full_lfm_namecharacterPlayer's full name in last-first-middle order as recorded by the MLB Stats API.
pick_person_strike_zone_topdoubleUpper boundary of the player's personalized strike zone in feet from the ground.
pick_person_strike_zone_bottomdoubleLower boundary of the player's personalized strike zone in feet from the ground.
pick_person_xref_idscharacterSerialized cross-reference identifiers linking the player to external data systems.
pick_team_spring_league_idintegerMLB Stats API identifier for the team's spring training league.
pick_team_spring_league_namecharacterFull name of the spring training league the team belongs to.
pick_team_spring_league_linkcharacterRelative URL path to the spring training league resource in the MLB Stats API.
pick_team_spring_league_abbreviationcharacterAbbreviation for the spring training league the team participates in (e.g., Cactus, Grapefruit).
pick_team_all_star_statuscharacterAll-Star game affiliation status of the team (e.g., American League, National League).
pick_team_idintegerUnique MLB Stats API identifier for the team that made this draft pick.
pick_team_namecharacterFull official name of the MLB team that made this pick (e.g., New York Yankees).
pick_team_linkcharacterRelative URL path to the team resource in the MLB Stats API.
pick_team_seasonintegerMLB season year for which this team's metadata snapshot applies.
pick_team_venue_idintegerMLB Stats API identifier for the team's regular-season home ballpark.
pick_team_venue_namecharacterName of the team's regular-season home ballpark (e.g., Yankee Stadium).
pick_team_venue_linkcharacterRelative URL path to the team's regular-season home venue in the MLB Stats API.
pick_team_spring_venue_idintegerMLB Stats API identifier for the team's spring training ballpark.
pick_team_spring_venue_linkcharacterRelative URL path to the spring training venue resource in the MLB Stats API.
pick_team_team_codecharacterShort internal code used by MLB to identify the team in system contexts.
pick_team_file_codecharacterLowercase file-system-safe code used internally by MLB to identify the team.
pick_team_abbreviationcharacterStandard two- or three-letter abbreviation for the MLB team that made this pick.
pick_team_team_namecharacterThe nickname portion of the team's full name (e.g., Yankees, Dodgers).
pick_team_location_namecharacterGeographic location name (city/metro) associated with the team (e.g., New York).
pick_team_first_year_of_playcharacterYear in which the selecting franchise first played as an MLB team.
pick_team_league_idintegerMLB Stats API identifier for the league (American or National) of the selecting team.
pick_team_league_namecharacterFull name of the league the selecting team belongs to (e.g., American League).
pick_team_league_linkcharacterRelative URL path to the league resource in the MLB Stats API.
pick_team_division_idintegerMLB Stats API identifier for the division the selecting team belongs to.
pick_team_division_namecharacterFull name of the division the selecting team belongs to (e.g., AL East).
pick_team_division_linkcharacterRelative URL path to the division resource in the MLB Stats API.
pick_team_sport_idintegerMLB Stats API identifier for the sport classification (MLB = 1).
pick_team_sport_linkcharacterRelative URL path to the sport resource in the MLB Stats API.
pick_team_sport_namecharacterFull name of the sport classification for the team (e.g., Major League Baseball).
pick_team_short_namecharacterShortened version of the team name used in space-constrained display contexts.
pick_team_franchise_namecharacterHistorical franchise name that persists across any team relocations or renames.
pick_team_club_namecharacterInformal club or nickname portion of the team's full name (e.g., Yankees, Red Sox).
pick_team_activelogicalBoolean flag indicating whether the selecting MLB franchise is currently active.
pick_draft_type_codecharacterShort code identifying the type of draft (e.g., amateur, Rule 5) for this pick.
pick_draft_type_descriptioncharacterHuman-readable description of the draft type associated with this pick.
pick_is_draftedlogicalBoolean flag indicating whether this draft slot has been filled with an actual selection.
pick_is_passlogicalBoolean flag indicating whether the selecting team passed on this pick rather than making a selection.
pick_yearcharacterMLB draft year for which this pick record applies.

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

Example​

mlb_draft_latest(year=2023)

Last validated n/a.

mlb_game_timestamps​

Retrieve all of the play timecodes for a game in GUMBO feed.

Endpoint URL: GET https://statsapi.mlb.com/api/v1.1/game/{game_pk}/feed/live/timestamps

Valid URL: https://statsapi.mlb.com/api/v1.1/game/716390/feed/live/timestamps

API ParameterPythonPatternRequiredNullableDescription
game_pkgame_pkYgame_pk path 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
timecodecharacterA timestamp string representing a specific point in time used to query the MLB Stats API for game state changes.

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

Example​

mlb_game_timestamps(game_pk=716390)

Last validated n/a.

mlb_game_changes​

View corrected non Statcast information for games

Endpoint URL: GET https://statsapi.mlb.com/api/v1/game/changes

Valid URL: https://statsapi.mlb.com/api/v1/game/changes?updatedSince=2023-09-01T00%3A00%3A00Z&sportId=1

API ParameterPythonPatternRequiredNullableDescription
updatedSinceupdated_sinceYupdatedSince query parameter.
sportIdsport_idYsportId 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
schedule_datecharacterThe calendar date for which schedule changes are being reported, identifying when rescheduled or suspended games occurred.
game_pkintegerUnique game identifier.
game_guidcharacterGlobally unique game identifier (GUID).
linkcharacterAPI link to the game feed.
game_typecharacterGame type code (R, P, etc.).
seasoncharacterSeason year.
game_datecharacterGame date (YYYY-MM-DD).
official_datecharacterOfficial game date (YYYY-MM-DD).
is_tielogicalWhether the game ended in a tie.
game_numberintegerGame number within a doubleheader.
public_facinglogicalWhether the game is public-facing.
double_headercharacterDoubleheader indicator ('N', 'S', 'Y').
gameday_typecharacterGameday data feed type.
tiebreakercharacterWhether the game is a tiebreaker.
calendar_event_idcharacterCalendar event identifier.
season_displaycharacterDisplay string for the season.
day_nightcharacterDay or night game indicator.
scheduled_inningsintegerScheduled number of innings.
reverse_home_away_statuslogicalWhether home/away teams are reversed.
inning_break_lengthintegerLength of inning breaks in seconds.
games_in_seriesdoubleNumber of games in the series.
series_game_numberdoubleGame number within the series.
series_descriptioncharacterDescription of the series.
record_sourcecharacterSource of the schedule record.
if_necessarycharacterWhether the game is played only if necessary.
if_necessary_descriptioncharacterDescription of the if-necessary status.
status_abstract_game_statecharacterAbstract game state (e.g. 'Final').
status_coded_game_statecharacterCoded game state.
status_detailed_statecharacterDetailed game state.
status_status_codecharacterStatus code for the game.
status_start_time_tbdlogicalWhether the start time is TBD.
status_abstract_game_codecharacterAbstract game state code.
teams_away_team_idintegerAway team MLBAM ID.
teams_away_team_namecharacterAway team name.
teams_away_team_linkcharacterAPI link to the away team.
teams_away_league_record_winsintegerAway team league-record wins.
teams_away_league_record_lossesintegerAway team league-record losses.
teams_away_league_record_tiesintegerAway team league-record ties.
teams_away_league_record_pctcharacterAway team winning percentage.
teams_away_scoreintegerAway team score.
teams_away_is_winnerlogicalWhether the away team won.
teams_away_split_squadlogicalWhether the away team is a split squad.
teams_away_series_numberdoubleAway team's series number.
teams_home_team_idintegerHome team MLBAM ID.
teams_home_team_namecharacterHome team name.
teams_home_team_linkcharacterAPI link to the home team.
teams_home_league_record_winsintegerHome team league-record wins.
teams_home_league_record_lossesintegerHome team league-record losses.
teams_home_league_record_tiesintegerHome team league-record ties.
teams_home_league_record_pctcharacterHome team winning percentage.
teams_home_scoreintegerHome team score.
teams_home_is_winnerlogicalWhether the home team won.
teams_home_split_squadlogicalWhether the home team is a split squad.
teams_home_series_numberdoubleHome team's series number.
venue_idintegerMLBAM venue ID.
venue_namecharacterVenue name.
venue_linkcharacterAPI link to the venue.
content_linkcharacterAPI link to the game content.
rescheduled_fromcharacterOriginal date-time the game was rescheduled from.
rescheduled_from_datecharacterOriginal date the game was rescheduled from.
descriptioncharacterLong-form description text.
status_reasoncharacterReason for the game status (e.g. 'Rain').
resumed_fromcharacterOriginal date-time if the game was resumed.
resumed_from_datecharacterOriginal date if the game was resumed.

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

Example​

mlb_game_changes(sport_id=1, updated_since='2023-09-01T00:00:00Z')

Last validated n/a.

mlb_analytics_games​

View timestamps of most recent data corrections made to games.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/game/analytics/game

Valid URL: https://statsapi.mlb.com/api/v1/game/analytics/game

API ParameterPythonPatternRequiredNullableDescription
gameModeIdgame_mode_idYgameModeId query parameter.
timecodetimecodeYtimecode query parameter.
limitlimitYMaximum number of items to return.
sortBysort_byYsortBy query parameter.
isNonStatcastis_non_statcastYisNonStatcast query parameter.
offsetoffsetYoffset query parameter.
fieldsfieldsYfields query parameter.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame (parser: parse_mlb_api_list); pass return_as_pandas=True for a pandas.DataFrame. return_parsed=False — the raw JSON Dict payload, unparsed.

Example​

mlb_analytics_games()

Last validated n/a.

mlb_analytics_guids​

View timestamps of most recent data corrections made to GUIDs.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/game/analytics/guids

Valid URL: https://statsapi.mlb.com/api/v1/game/analytics/guids

API ParameterPythonPatternRequiredNullableDescription
gameModeIdgame_mode_idYgameModeId query parameter.
timecodetimecodeYtimecode query parameter.
limitlimitYMaximum number of items to return.
sortBysort_byYsortBy query parameter.
isNonStatcastis_non_statcastYisNonStatcast query parameter.
offsetoffsetYoffset query parameter.
fieldsfieldsYfields query parameter.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame (parser: parse_mlb_api_list); pass return_as_pandas=True for a pandas.DataFrame. return_parsed=False — the raw JSON Dict payload, unparsed.

Example​

mlb_analytics_guids()

Last validated n/a.

mlb_game_guids​

View Statcast data for a specific game.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/game/{game_pk}/guids

Valid URL: https://statsapi.mlb.com/api/v1/game/716390/guids

API ParameterPythonPatternRequiredNullableDescription
game_pkgame_pkYgame_pk path parameter.
gameModeIdgame_mode_idYgameModeId query parameter.
updatedSinceupdated_sinceYupdatedSince query parameter.
isPitchis_pitchYisPitch query parameter.
isHitis_hitYisHit query parameter.
isPickoffis_pickoffYisPickoff query parameter.
hydratehydrateYhydrate query parameter.
parsed/rawparsed_rawYparsed/raw query parameter.
fieldsfieldsYfields query parameter.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame (parser: parse_mlb_api_list); pass return_as_pandas=True for a pandas.DataFrame. return_parsed=False — the raw JSON Dict payload, unparsed.

Example​

mlb_game_guids(game_pk=716390)

Last validated n/a.

mlb_play_analytics​

View Statcast data for a specific play.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/game/{game_pk}/{guid}/analytics

Valid URL: https://statsapi.mlb.com/api/v1/game/716390/90groovy-2438-test-guid-placeholder0/analytics

API ParameterPythonPatternRequiredNullableDescription
game_pkgame_pkYgame_pk path parameter.
guidguidYguid path parameter.
hydratehydrateYhydrate query parameter.
fieldsfieldsYfields query parameter.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame (parser: parse_mlb_api_list); pass return_as_pandas=True for a pandas.DataFrame. return_parsed=False — the raw JSON Dict payload, unparsed.

Example​

mlb_play_analytics(game_pk=716390, guid='90groovy-2438-test-guid-placeholder0')

Last validated n/a.

mlb_play_context_metrics_averages​

View Statcast contextMetrics data for a specific play.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/game/{game_pk}/{guid}/contextMetricsAverages

Valid URL: https://statsapi.mlb.com/api/v1/game/716390/90groovy-2438-test-guid-placeholder0/contextMetricsAverages

API ParameterPythonPatternRequiredNullableDescription
game_pkgame_pkYgame_pk path parameter.
guidguidYguid path parameter.
fieldsfieldsYfields query parameter.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame (parser: parse_mlb_api_list); pass return_as_pandas=True for a pandas.DataFrame. return_parsed=False — the raw JSON Dict payload, unparsed.

Example​

mlb_play_context_metrics_averages(game_pk=716390, guid='90groovy-2438-test-guid-placeholder0')

Last validated n/a.

mlb_game_color​

View game color commentary info.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/game/{game_pk}/feed/color

Valid URL: https://statsapi.mlb.com/api/v1/game/716390/feed/color

API ParameterPythonPatternRequiredNullableDescription
game_pkgame_pkYgame_pk path parameter.
timecodetimecodeYtimecode query parameter.
fieldsfieldsYfields query parameter.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame (parser: parse_mlb_api_list); pass return_as_pandas=True for a pandas.DataFrame. return_parsed=False — the raw JSON Dict payload, unparsed.

Example​

mlb_game_color(game_pk=716390)

Last validated n/a.

mlb_game_color_diff​

View game color feed.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/game/{game_pk}/feed/color/diffPatch

Valid URL: https://statsapi.mlb.com/api/v1/game/716390/feed/color/diffPatch

API ParameterPythonPatternRequiredNullableDescription
game_pkgame_pkYgame_pk path parameter.
startTimecodestart_timecodeYstartTimecode query parameter.
endTimecodeend_timecodeYendTimecode query parameter.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame (parser: parse_mlb_api_list); pass return_as_pandas=True for a pandas.DataFrame. return_parsed=False — the raw JSON Dict payload, unparsed.

Example​

mlb_game_color_diff(game_pk=716390)

Last validated n/a.

mlb_game_color_timestamps​

View all of the color timecodes for a game.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/game/{game_pk}/feed/color/timestamps

Valid URL: https://statsapi.mlb.com/api/v1/game/716390/feed/color/timestamps

API ParameterPythonPatternRequiredNullableDescription
game_pkgame_pkYgame_pk path parameter.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame (parser: parse_mlb_api_timecodes); pass return_as_pandas=True for a pandas.DataFrame. return_parsed=False — the raw JSON Dict payload, unparsed.

Example​

mlb_game_color_timestamps(game_pk=716390)

Last validated n/a.

mlb_game_pace​

View time of game info.

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

Valid URL: https://statsapi.mlb.com/api/v1/gamePace?season=2023

API ParameterPythonPatternRequiredNullableDescription
seasonseasonYSeason year (e.g. 2024).
teamIdsteam_idsYteamIds query parameter.
leagueIdsleague_idsYleagueIds query parameter.
leagueListIdleague_list_idYleagueListId query parameter.
sportIdsport_idYsportId query parameter.
gameTypegame_typeYgameType query parameter.
startDatestart_dateYstartDate query parameter.
endDateend_dateYendDate query parameter.
venueIdsvenue_idsYvenueIds query parameter.
orgTypeorg_typeYorgType query parameter.
includeChildreninclude_childrenYincludeChildren 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
hits_per9_inndoubleAverage number of hits allowed per nine innings across all games in the sample period.
runs_per9_inndoubleAverage number of runs scored per nine innings across all games in the sample period.
pitches_per9_inndoubleAverage number of pitches thrown per nine innings across all games in the sample period.
plate_appearances_per9_inndoubleAverage number of plate appearances occurring per nine innings across all games in the sample period.
hits_per_gamedoubleHits per game.
runs_per_gamedoubleRuns per game.
innings_played_per_gamedoubleInnings played per game.
pitches_per_gamedoublePitches per game.
pitchers_per_gamedoublePitchers used per game.
plate_appearances_per_gamedoublePlate appearances per game.
total_game_timecharacterTotal game time (HHH:MM:SS).
total_innings_playeddoubleTotal innings played.
total_hitsintegerTotal hits.
total_runsintegerTotal runs.
total_plate_appearancesintegerTotal plate appearances.
total_pitchersintegerTotal pitchers used.
total_pitchesintegerTotal pitches thrown.
total_gamesintegerTotal games on the date.
total7_inn_gamesintegerTotal number of seven-inning games played (including doubleheader games).
total9_inn_gamesdoubleTotal number of nine-inning games played in the sample period.
total_extra_inn_gamesintegerTotal extra-inning games.
time_per_gamecharacterAverage time per game (HH:MM:SS).
time_per_pitchcharacterAverage time per pitch (HH:MM:SS).
time_per_hitcharacterAverage time per hit (HH:MM:SS).
time_per_runcharacterAverage time per run (HH:MM:SS).
time_per_plate_appearancecharacterAverage time per plate appearance (HH:MM:SS).
time_per9_inncharacterAverage elapsed clock time per nine-inning game formatted as hours and minutes.
time_per77_plate_appearancescharacterAverage time per 77 plate appearances, used as a normalized pace benchmark by MLB.
total_extra_inn_timecharacterTotal extra-inning time (HHH:MM:SS).
time_per7_inn_game_without_extra_inncharacterAverage elapsed clock time per seven-inning game excluding games that went to extra innings.
total9_inn_games_completed_earlyintegerNumber of nine-inning games that were called or suspended before completing nine full innings.
total9_inn_games_without_extra_inndoubleNumber of nine-inning games completed without requiring extra innings.
total9_inn_games_scheduledintegerTotal number of nine-inning games that were scheduled in the sample period.
hits_per_rundoubleHits per run.
pitches_per_pitcherdoublePitches per pitcher.
seasoncharacterSeason year.
sport_idintegerSport MLBAM ID.
sport_codecharacterShort sport code (e.g. 'mlb', 'aaa').
sport_linkcharacterAPI link to the sport.
pr_portal_calculated_fields_total7_inn_gamesintegerCalculated total count of seven-inning games as tallied by the MLB Stats API pace portal.
pr_portal_calculated_fields_total9_inn_gamesdoubleCalculated total count of nine-inning games as tallied by the MLB Stats API pace portal.
pr_portal_calculated_fields_total_extra_inn_gamesintegerPortal-calculated total extra-inning games.
pr_portal_calculated_fields_time_per7_inn_gamecharacterCalculated average game time per seven-inning game as produced by the MLB Stats API pace portal.
pr_portal_calculated_fields_time_per9_inn_gamecharacterCalculated average game time per nine-inning game as produced by the MLB Stats API pace portal.
pr_portal_calculated_fields_time_per_extra_inn_gamecharacterPortal-calculated time per extra-inning game.
time_per7_inn_gamecharacterAverage elapsed clock time per seven-inning game formatted as hours and minutes.
total7_inn_games_scheduleddoubleTotal number of seven-inning games that were scheduled in the sample period.
total7_inn_games_without_extra_inndoubleNumber of seven-inning games completed without requiring extra innings.
total7_inn_games_completed_earlydoubleNumber of seven-inning games that were called or completed before the full seven innings were played.

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

Example​

mlb_game_pace(season='2023')

Last validated n/a.

mlb_high_low​

View high/low stats by player or team.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/highLow/{org_type}

Valid URL: https://statsapi.mlb.com/api/v1/highLow/player?statGroup=hitting&sortStat=homeRuns&season=2023

API ParameterPythonPatternRequiredNullableDescription
org_typeorg_typeYorg_type path parameter.
statGroupstat_groupYstatGroup query parameter.
sortStatsort_statYsortStat query parameter.
seasonseasonYSeason year (e.g. 2024).
gameTypegame_typeYgameType query parameter.
teamIdteam_idYteamId query parameter.
leagueIdleague_idYleagueId query parameter.
sportIdssport_idsYsportIds 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
total_splitsintegerTotal number of splits in the leaderboard.
exemptionscharacterSerialized list of exemption codes or player IDs excluded from the high/low statistical split calculation.
splitscharacterSplits.
splits_tied_with_offsetcharacterPlayers tied at the offset boundary.
splits_tied_with_limitcharacterPlayers tied at the limit boundary.
seasoncharacterSeason year.
combined_statslogicalWhether the stat combines multiple split sources.
group_display_namecharacterStat group display name.
game_type_idcharacterGame type code (e.g., R for regular season).
game_type_descriptioncharacterGame type description.
sort_stat_namecharacterSnake-case name of the sorted statistic (e.g. 'at_bats').
sort_stat_lookup_paramcharacterAPI lookup parameter for the sorted statistic (e.g. 'atBats').
sort_stat_is_countinglogicalWhether the sorted statistic is a counting stat.
sort_stat_labelcharacterHuman-readable label of the sorted statistic (e.g. 'At bats').
sort_stat_stat_groupscharacterSerialized list of statistical group identifiers (e.g., hitting, pitching) used to filter this high/low query.
sort_stat_org_typescharacterSerialized list of organization types (e.g., MLB, MiLB) in scope for this high/low stat sort.
sort_stat_high_low_typescharacterSerialized list of high/low result type codes (e.g., high, low) applicable to this stat leader query.
sort_stat_streak_levelscharacterSerialized list of streak level codes defining the streak lengths tracked in this high/low query.

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

Example​

mlb_high_low(org_type='player', stat_group='hitting', sort_stat='homeRuns', season='2023')

Last validated n/a.

mlb_home_run_derby​

View a home run derby object based on gamePk.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/homeRunDerby/{game_pk}

Valid URL: https://statsapi.mlb.com/api/v1/homeRunDerby/511101

API ParameterPythonPatternRequiredNullableDescription
game_pkgame_pkYgame_pk path 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
idintegerId.
full_namecharacterPlayer's full name.
linkcharacterAPI link to the game feed.
first_namecharacterPlayer first name.
last_namecharacterPlayer last name.
primary_numbercharacterPlayer uniform number.
birth_datecharacterDate of birth (YYYY-MM-DD).
current_ageintegerCurrent age in years.
birth_citycharacterCity of birth.
birth_state_provincecharacterState or province of birth.
birth_countrycharacterCountry of birth.
heightcharacterHeight (feet and inches).
weightintegerWeight in pounds.
activelogicalWhether the player is currently active.
use_namecharacterPreferred first name.
use_last_namecharacterPreferred last name.
middle_namecharacterPlayer middle name.
boxscore_namecharacterName as shown in box scores.
nick_namecharacterPlayer nickname.
gendercharacterPlayer gender.
is_playerlogicalWhether the person is a player.
is_verifiedlogicalWhether the player profile is verified.
draft_yeardoubleYear the player was drafted.
pronunciationcharacterPhonetic name pronunciation.
statscharacterStats.
mlb_debut_datecharacterMLB debut date (YYYY-MM-DD).
name_first_lastcharacterName in first-last order.
name_slugcharacterURL-friendly name slug.
first_last_namecharacterFirst and last name.
last_first_namecharacterName in last, first order.
last_init_namecharacterLast name with first initial.
init_last_namecharacterFirst initial with last name.
full_fml_namecharacterFull name (first-middle-last).
full_lfm_namecharacterFull name (last-first-middle).
strike_zone_topdoubleTop of the player's strike zone (feet).
strike_zone_bottomdoubleBottom of the player's strike zone (feet).
current_team_spring_league_iddoubleThe MLB Stats API numeric identifier for the spring training league of the player's current team.
current_team_spring_league_namecharacterThe full name of the spring training league (e.g., 'Cactus League') for the player's current team.
current_team_spring_league_linkcharacterThe MLB Stats API relative URL linking to the spring training league resource for the player's current team.
current_team_spring_league_abbreviationcharacterThe abbreviation for the Cactus League or Grapefruit League in which the player's current team participates during spring training.
current_team_all_star_statuscharacterThe All-Star designation status of the player's current team (e.g., which league's All-Star pool the team belongs to).
current_team_idintegerCurrent team MLBAM ID.
current_team_namecharacterCurrent team name.
current_team_linkcharacterAPI link to the current team.
current_team_seasonintegerThe MLB season year for which the player's current team metadata is reported.
current_team_venue_idintegerThe MLB Stats API numeric identifier for the regular-season home ballpark of the player's current team.
current_team_venue_namecharacterThe official name of the regular-season home ballpark for the player's current team.
current_team_venue_linkcharacterThe MLB Stats API relative URL linking to the regular-season venue resource for the player's current team.
current_team_spring_venue_iddoubleThe MLB Stats API numeric identifier for the spring training ballpark used by the player's current team.
current_team_spring_venue_linkcharacterThe MLB Stats API relative URL linking to the spring training venue resource for the player's current team.
current_team_team_codecharacterThe three-letter internal team code used by MLB in legacy data systems and some API references.
current_team_file_codecharacterThe lowercase alphabetic file code used by MLB for identifying the team in media and data assets.
current_team_abbreviationcharacterThe standard two- or three-letter abbreviation for the player's current MLB team (e.g., 'NYY', 'LAD').
current_team_team_namecharacterThe full official name of the player's current team, including both city and nickname.
current_team_location_namecharacterThe city or metropolitan area name associated with the player's current team.
current_team_first_year_of_playcharacterThe calendar year in which the player's current franchise first played MLB games.
current_team_league_idintegerThe MLB Stats API numeric identifier for the league (American League or National League) of the player's current team.
current_team_league_namecharacterThe full name of the league (e.g., 'American League') in which the player's current team competes.
current_team_league_linkcharacterThe MLB Stats API relative URL linking to the league resource for the player's current team.
current_team_division_iddoubleThe MLB Stats API numeric identifier for the division in which the player's current team competes.
current_team_division_namecharacterThe full name of the division in which the player's current team competes (e.g., 'American League East').
current_team_division_linkcharacterThe MLB Stats API relative URL linking to the division resource for the player's current team.
current_team_sport_idintegerThe MLB Stats API numeric identifier for the sport classification (e.g., 1 for MLB) of the player's current team.
current_team_sport_linkcharacterThe MLB Stats API relative URL linking to the sport resource associated with the player's current team.
current_team_sport_namecharacterThe name of the sport classification for the player's current team (e.g., 'Major League Baseball').
current_team_short_namecharacterA shortened display name for the player's current team, often used in space-constrained UI contexts.
current_team_franchise_namecharacterThe historical franchise name for the player's current team, which may differ from the current team name for relocated clubs.
current_team_club_namecharacterThe short club nickname for the player's current team, typically the city-less portion of the franchise name.
current_team_activelogicalBoolean flag indicating whether the player's current team is an active MLB franchise.
primary_position_codecharacterPrimary position code.
primary_position_namecharacterPrimary fielding position name.
primary_position_typecharacterPrimary position type (e.g. Infielder).
primary_position_abbreviationcharacterPrimary position abbreviation.
bat_side_codecharacterBatting side code (L/R/S).
bat_side_descriptioncharacterBatting side description.
pitch_hand_codecharacterThrowing hand code (L/R).
pitch_hand_descriptioncharacterThrowing hand description.
last_played_datecharacterDate of last MLB game played.
name_matrilinealcharacterMaternal family name.
current_team_parent_org_namecharacterThe name of the parent major-league organization for the player's current team.
current_team_parent_org_iddoubleThe MLB Stats API numeric identifier for the parent organization (major-league affiliate) of the player's current team.

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

Example​

mlb_home_run_derby(game_pk=511101)

Last validated n/a.

mlb_home_run_derby_bracket​

View a home run derby object based on bracket.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/homeRunDerby/{game_pk}/bracket

Valid URL: https://statsapi.mlb.com/api/v1/homeRunDerby/511101/bracket

API ParameterPythonPatternRequiredNullableDescription
game_pkgame_pkYgame_pk path 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
idintegerId.
full_namecharacterPlayer's full name.
linkcharacterAPI link to the game feed.
first_namecharacterPlayer first name.
last_namecharacterPlayer last name.
primary_numbercharacterPlayer uniform number.
birth_datecharacterDate of birth (YYYY-MM-DD).
current_ageintegerCurrent age in years.
birth_citycharacterCity of birth.
birth_state_provincecharacterState or province of birth.
birth_countrycharacterCountry of birth.
heightcharacterHeight (feet and inches).
weightintegerWeight in pounds.
activelogicalWhether the player is currently active.
use_namecharacterPreferred first name.
use_last_namecharacterPreferred last name.
middle_namecharacterPlayer middle name.
boxscore_namecharacterName as shown in box scores.
nick_namecharacterPlayer nickname.
gendercharacterPlayer gender.
is_playerlogicalWhether the person is a player.
is_verifiedlogicalWhether the player profile is verified.
draft_yeardoubleYear the player was drafted.
pronunciationcharacterPhonetic name pronunciation.
statscharacterStats.
mlb_debut_datecharacterMLB debut date (YYYY-MM-DD).
name_first_lastcharacterName in first-last order.
name_slugcharacterURL-friendly name slug.
first_last_namecharacterFirst and last name.
last_first_namecharacterName in last, first order.
last_init_namecharacterLast name with first initial.
init_last_namecharacterFirst initial with last name.
full_fml_namecharacterFull name (first-middle-last).
full_lfm_namecharacterFull name (last-first-middle).
strike_zone_topdoubleTop of the player's strike zone (feet).
strike_zone_bottomdoubleBottom of the player's strike zone (feet).
current_team_spring_league_iddoubleMLB Stats API identifier for the spring training league of the participant's current team.
current_team_spring_league_namecharacterFull name of the spring training league the participant's team belongs to.
current_team_spring_league_linkcharacterRelative URL path to the spring training league resource in the MLB Stats API.
current_team_spring_league_abbreviationcharacterAbbreviation for the spring training league the participant's team belongs to (e.g., Cactus, Grapefruit).
current_team_all_star_statuscharacterAll-Star game league affiliation of the participant's current team (e.g., American League, National League).
current_team_idintegerCurrent team MLBAM ID.
current_team_namecharacterCurrent team name.
current_team_linkcharacterAPI link to the current team.
current_team_seasonintegerMLB season year for which the participant's current team metadata snapshot applies.
current_team_venue_idintegerMLB Stats API identifier for the participant's current team's regular-season home ballpark.
current_team_venue_namecharacterName of the participant's current team's regular-season home ballpark.
current_team_venue_linkcharacterRelative URL path to the current team's home venue resource in the MLB Stats API.
current_team_spring_venue_iddoubleMLB Stats API identifier for the spring training ballpark used by the participant's team.
current_team_spring_venue_linkcharacterRelative URL path to the spring training venue resource in the MLB Stats API.
current_team_team_codecharacterShort internal code used by MLB to identify the participant's current team in system contexts.
current_team_file_codecharacterLowercase file-system-safe code used by MLB to identify the participant's current team.
current_team_abbreviationcharacterStandard two- or three-letter abbreviation for the Home Run Derby participant's current MLB team.
current_team_team_namecharacterThe nickname portion of the participant's current team name (e.g., Red Sox, Braves).
current_team_location_namecharacterCity or metropolitan area name associated with the participant's current team.
current_team_first_year_of_playcharacterYear in which the participant's current franchise first played as an MLB team.
current_team_league_idintegerMLB Stats API identifier for the league (American or National) of the participant's current team.
current_team_league_namecharacterFull name of the league the participant's current team belongs to (e.g., National League).
current_team_league_linkcharacterRelative URL path to the league resource for the participant's current team in the MLB Stats API.
current_team_division_iddoubleMLB Stats API identifier for the division the participant's current team belongs to.
current_team_division_namecharacterFull name of the division the participant's current team belongs to (e.g., AL East).
current_team_division_linkcharacterRelative URL path to the participant's current team's division resource in the MLB Stats API.
current_team_sport_idintegerMLB Stats API identifier for the sport classification of the participant's current team (MLB = 1).
current_team_sport_linkcharacterRelative URL path to the sport resource for the participant's current team in the MLB Stats API.
current_team_sport_namecharacterFull sport classification name for the participant's current team (e.g., Major League Baseball).
current_team_short_namecharacterShortened display name of the participant's current team for space-constrained contexts.
current_team_franchise_namecharacterHistorical franchise name for the participant's team, persisting across relocations.
current_team_club_namecharacterInformal nickname portion of the participant's current team name (e.g., Yankees, Dodgers).
current_team_activelogicalBoolean flag indicating whether the participant's current franchise is an active MLB organization.
primary_position_codecharacterPrimary position code.
primary_position_namecharacterPrimary fielding position name.
primary_position_typecharacterPrimary position type (e.g. Infielder).
primary_position_abbreviationcharacterPrimary position abbreviation.
bat_side_codecharacterBatting side code (L/R/S).
bat_side_descriptioncharacterBatting side description.
pitch_hand_codecharacterThrowing hand code (L/R).
pitch_hand_descriptioncharacterThrowing hand description.
last_played_datecharacterDate of last MLB game played.
name_matrilinealcharacterMaternal family name.
current_team_parent_org_namecharacterName of the parent MLB organization for the participant's current team.
current_team_parent_org_iddoubleMLB Stats API identifier for the parent MLB organization of the participant's current team, relevant for minor league affiliates.

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

Example​

mlb_home_run_derby_bracket(game_pk=511101)

Last validated n/a.

mlb_home_run_derby_pool​

View a home run derby object based on pool.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/homeRunDerby/{game_pk}/pool

Valid URL: https://statsapi.mlb.com/api/v1/homeRunDerby/511101/pool

API ParameterPythonPatternRequiredNullableDescription
game_pkgame_pkYgame_pk path 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
idintegerId.
full_namecharacterPlayer's full name.
linkcharacterAPI link to the game feed.
first_namecharacterPlayer first name.
last_namecharacterPlayer last name.
primary_numbercharacterPlayer uniform number.
birth_datecharacterDate of birth (YYYY-MM-DD).
current_ageintegerCurrent age in years.
birth_citycharacterCity of birth.
birth_state_provincecharacterState or province of birth.
birth_countrycharacterCountry of birth.
heightcharacterHeight (feet and inches).
weightintegerWeight in pounds.
activelogicalWhether the player is currently active.
use_namecharacterPreferred first name.
use_last_namecharacterPreferred last name.
middle_namecharacterPlayer middle name.
boxscore_namecharacterName as shown in box scores.
nick_namecharacterPlayer nickname.
gendercharacterPlayer gender.
is_playerlogicalWhether the person is a player.
is_verifiedlogicalWhether the player profile is verified.
draft_yeardoubleYear the player was drafted.
pronunciationcharacterPhonetic name pronunciation.
statscharacterStats.
mlb_debut_datecharacterMLB debut date (YYYY-MM-DD).
name_first_lastcharacterName in first-last order.
name_slugcharacterURL-friendly name slug.
first_last_namecharacterFirst and last name.
last_first_namecharacterName in last, first order.
last_init_namecharacterLast name with first initial.
init_last_namecharacterFirst initial with last name.
full_fml_namecharacterFull name (first-middle-last).
full_lfm_namecharacterFull name (last-first-middle).
strike_zone_topdoubleTop of the player's strike zone (feet).
strike_zone_bottomdoubleBottom of the player's strike zone (feet).
current_team_spring_league_iddoubleThe MLB Stats API numeric identifier for the spring training league of the pool participant's current team.
current_team_spring_league_namecharacterThe full name of the spring training league for the pool participant's current team.
current_team_spring_league_linkcharacterThe MLB Stats API relative URL linking to the spring training league resource for the pool participant's current team.
current_team_spring_league_abbreviationcharacterThe abbreviation for the spring training league in which the pool participant's current team plays during spring training.
current_team_all_star_statuscharacterThe All-Star designation status of the pool participant's current team (e.g., which league's All-Star pool the team belongs to).
current_team_idintegerCurrent team MLBAM ID.
current_team_namecharacterCurrent team name.
current_team_linkcharacterAPI link to the current team.
current_team_seasonintegerThe MLB season year for which the pool participant's current team metadata is reported.
current_team_venue_idintegerThe MLB Stats API numeric identifier for the regular-season home ballpark of the pool participant's current team.
current_team_venue_namecharacterThe official name of the regular-season home ballpark for the pool participant's current team.
current_team_venue_linkcharacterThe MLB Stats API relative URL linking to the regular-season venue resource for the pool participant's current team.
current_team_spring_venue_iddoubleThe MLB Stats API numeric identifier for the spring training ballpark used by the pool participant's current team.
current_team_spring_venue_linkcharacterThe MLB Stats API relative URL linking to the spring training venue resource for the pool participant's current team.
current_team_team_codecharacterThe three-letter internal team code used by MLB for the pool participant's team in legacy data systems.
current_team_file_codecharacterThe lowercase alphabetic file code used by MLB for identifying the pool participant's team in media and data assets.
current_team_abbreviationcharacterThe standard two- or three-letter abbreviation for the Home Run Derby pool participant's current MLB team.
current_team_team_namecharacterThe full official name of the pool participant's current team, including both city and nickname.
current_team_location_namecharacterThe city or metropolitan area name associated with the pool participant's current team.
current_team_first_year_of_playcharacterThe calendar year in which the pool participant's current franchise first played MLB games.
current_team_league_idintegerThe MLB Stats API numeric identifier for the league of the pool participant's current team.
current_team_league_namecharacterThe full name of the league (e.g., 'National League') in which the pool participant's current team competes.
current_team_league_linkcharacterThe MLB Stats API relative URL linking to the league resource for the pool participant's current team.
current_team_division_iddoubleThe MLB Stats API numeric identifier for the division in which the pool participant's current team competes.
current_team_division_namecharacterThe full name of the division in which the pool participant's current team competes (e.g., 'National League West').
current_team_division_linkcharacterThe MLB Stats API relative URL linking to the division resource for the pool participant's current team.
current_team_sport_idintegerThe MLB Stats API numeric identifier for the sport classification of the pool participant's current team.
current_team_sport_linkcharacterThe MLB Stats API relative URL linking to the sport resource associated with the pool participant's current team.
current_team_sport_namecharacterThe name of the sport classification for the pool participant's current team (e.g., 'Major League Baseball').
current_team_short_namecharacterA shortened display name for the pool participant's current team, often used in space-constrained UI contexts.
current_team_franchise_namecharacterThe historical franchise name for the pool participant's current team, which may differ from the current team name for relocated clubs.
current_team_club_namecharacterThe short club nickname for the pool participant's current team, typically the city-less portion of the franchise name.
current_team_activelogicalBoolean flag indicating whether the pool participant's current team is an active MLB franchise.
primary_position_codecharacterPrimary position code.
primary_position_namecharacterPrimary fielding position name.
primary_position_typecharacterPrimary position type (e.g. Infielder).
primary_position_abbreviationcharacterPrimary position abbreviation.
bat_side_codecharacterBatting side code (L/R/S).
bat_side_descriptioncharacterBatting side description.
pitch_hand_codecharacterThrowing hand code (L/R).
pitch_hand_descriptioncharacterThrowing hand description.
last_played_datecharacterDate of last MLB game played.
name_matrilinealcharacterMaternal family name.
current_team_parent_org_namecharacterThe name of the parent major-league organization for the pool participant's current team.
current_team_parent_org_iddoubleThe MLB Stats API numeric identifier for the parent organization of the pool participant's current team.

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

Example​

mlb_home_run_derby_pool(game_pk=511101)

Last validated n/a.

mlb_all_star_ballot​

View All-Star Ballots per league.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/league/{league_id}/allStarBallot

Valid URL: https://statsapi.mlb.com/api/v1/league/103/allStarBallot?season=2023

API ParameterPythonPatternRequiredNullableDescription
league_idleague_idYleague_id path parameter.
seasonseasonYSeason year (e.g. 2024).
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
idintegerId.
full_namecharacterPlayer's full name.
linkcharacterAPI link to the game feed.
first_namecharacterPlayer first name.
last_namecharacterPlayer last name.
primary_numbercharacterPlayer uniform number.
birth_datecharacterDate of birth (YYYY-MM-DD).
current_ageintegerCurrent age in years.
birth_citycharacterCity of birth.
birth_countrycharacterCountry of birth.
heightcharacterHeight (feet and inches).
weightintegerWeight in pounds.
activelogicalWhether the player is currently active.
use_namecharacterPreferred first name.
use_last_namecharacterPreferred last name.
middle_namecharacterPlayer middle name.
boxscore_namecharacterName as shown in box scores.
nick_namecharacterPlayer nickname.
gendercharacterPlayer gender.
name_matrilinealcharacterMaternal family name.
is_playerlogicalWhether the person is a player.
is_verifiedlogicalWhether the player profile is verified.
pronunciationcharacterPhonetic name pronunciation.
last_played_datecharacterDate of last MLB game played.
mlb_debut_datecharacterMLB debut date (YYYY-MM-DD).
name_first_lastcharacterName in first-last order.
name_slugcharacterURL-friendly name slug.
first_last_namecharacterFirst and last name.
last_first_namecharacterName in last, first order.
last_init_namecharacterLast name with first initial.
init_last_namecharacterFirst initial with last name.
full_fml_namecharacterFull name (first-middle-last).
full_lfm_namecharacterFull name (last-first-middle).
strike_zone_topdoubleTop of the player's strike zone (feet).
strike_zone_bottomdoubleBottom of the player's strike zone (feet).
primary_position_codecharacterPrimary position code.
primary_position_namecharacterPrimary fielding position name.
primary_position_typecharacterPrimary position type (e.g. Infielder).
primary_position_abbreviationcharacterPrimary position abbreviation.
bat_side_codecharacterBatting side code (L/R/S).
bat_side_descriptioncharacterBatting side description.
pitch_hand_codecharacterThrowing hand code (L/R).
pitch_hand_descriptioncharacterThrowing hand description.
birth_state_provincecharacterState or province of birth.
draft_yeardoubleYear the player was drafted.
name_titlecharacterName title.
name_suffixcharacterName suffix (e.g. Jr., Sr., III).

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

Example​

mlb_all_star_ballot(league_id='103', season='2023')

Last validated n/a.

mlb_all_star_write_ins​

View All-Star Write-ins per league.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/league/{league_id}/allStarWriteIns

Valid URL: https://statsapi.mlb.com/api/v1/league/103/allStarWriteIns?season=2023

API ParameterPythonPatternRequiredNullableDescription
league_idleague_idYleague_id path parameter.
seasonseasonYSeason year (e.g. 2024).
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
idintegerId.
full_namecharacterPlayer's full name.
linkcharacterAPI link to the game feed.
first_namecharacterPlayer first name.
last_namecharacterPlayer last name.
birth_datecharacterDate of birth (YYYY-MM-DD).
current_ageintegerCurrent age in years.
birth_citycharacterCity of birth.
birth_state_provincecharacterState or province of birth.
birth_countrycharacterCountry of birth.
heightcharacterHeight (feet and inches).
weightintegerWeight in pounds.
activelogicalWhether the player is currently active.
use_namecharacterPreferred first name.
use_last_namecharacterPreferred last name.
boxscore_namecharacterName as shown in box scores.
gendercharacterPlayer gender.
is_playerlogicalWhether the person is a player.
is_verifiedlogicalWhether the player profile is verified.
pronunciationcharacterPhonetic name pronunciation.
mlb_debut_datecharacterMLB debut date (YYYY-MM-DD).
name_first_lastcharacterName in first-last order.
name_slugcharacterURL-friendly name slug.
first_last_namecharacterFirst and last name.
last_first_namecharacterName in last, first order.
last_init_namecharacterLast name with first initial.
init_last_namecharacterFirst initial with last name.
full_fml_namecharacterFull name (first-middle-last).
full_lfm_namecharacterFull name (last-first-middle).
strike_zone_topdoubleTop of the player's strike zone (feet).
strike_zone_bottomdoubleBottom of the player's strike zone (feet).
bat_side_codecharacterBatting side code (L/R/S).
bat_side_descriptioncharacterBatting side description.
pitch_hand_codecharacterThrowing hand code (L/R).
pitch_hand_descriptioncharacterThrowing hand description.
primary_numbercharacterPlayer uniform number.
draft_yeardoubleYear the player was drafted.
middle_namecharacterPlayer middle name.
name_matrilinealcharacterMaternal family name.
last_played_datecharacterDate of last MLB game played.
nick_namecharacterPlayer nickname.
name_titlecharacterName title.
name_suffixcharacterName suffix (e.g. Jr., Sr., III).

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

Example​

mlb_all_star_write_ins(league_id='103', season='2023')

Last validated n/a.

mlb_all_star_final_vote​

View All-Star Final Vote per league.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/league/{league_id}/allStarFinalVote

Valid URL: https://statsapi.mlb.com/api/v1/league/103/allStarFinalVote?season=2023

API ParameterPythonPatternRequiredNullableDescription
league_idleague_idYleague_id path parameter.
seasonseasonYSeason year (e.g. 2024).
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
idintegerId.
full_namecharacterPlayer's full name.
linkcharacterAPI link to the game feed.
first_namecharacterPlayer first name.
last_namecharacterPlayer last name.
primary_numbercharacterPlayer uniform number.
birth_datecharacterDate of birth (YYYY-MM-DD).
current_ageintegerCurrent age in years.
birth_citycharacterCity of birth.
birth_countrycharacterCountry of birth.
heightcharacterHeight (feet and inches).
weightintegerWeight in pounds.
activelogicalWhether the player is currently active.
use_namecharacterPreferred first name.
use_last_namecharacterPreferred last name.
boxscore_namecharacterName as shown in box scores.
nick_namecharacterPlayer nickname.
gendercharacterPlayer gender.
is_playerlogicalWhether the person is a player.
is_verifiedlogicalWhether the player profile is verified.
pronunciationcharacterPhonetic name pronunciation.
mlb_debut_datecharacterMLB debut date (YYYY-MM-DD).
name_first_lastcharacterName in first-last order.
name_slugcharacterURL-friendly name slug.
first_last_namecharacterFirst and last name.
last_first_namecharacterName in last, first order.
last_init_namecharacterLast name with first initial.
init_last_namecharacterFirst initial with last name.
full_fml_namecharacterFull name (first-middle-last).
full_lfm_namecharacterFull name (last-first-middle).
strike_zone_topdoubleTop of the player's strike zone (feet).
strike_zone_bottomdoubleBottom of the player's strike zone (feet).
primary_position_codecharacterPrimary position code.
primary_position_namecharacterPrimary fielding position name.
primary_position_typecharacterPrimary position type (e.g. Infielder).
primary_position_abbreviationcharacterPrimary position abbreviation.
bat_side_codecharacterBatting side code (L/R/S).
bat_side_descriptioncharacterBatting side description.
pitch_hand_codecharacterThrowing hand code (L/R).
pitch_hand_descriptioncharacterThrowing hand description.
name_matrilinealcharacterMaternal family name.
birth_state_provincecharacterState or province of birth.
name_titlecharacterName title.
name_suffixcharacterName suffix (e.g. Jr., Sr., III).
middle_namecharacterPlayer middle name.
draft_yeardoubleYear the player was drafted.
last_played_datecharacterDate of last MLB game played.

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

Example​

mlb_all_star_final_vote(league_id='103', season='2023')

Last validated n/a.

mlb_free_agents​

View biographical information and stats for Free Agents.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/people/freeAgents

Valid URL: https://statsapi.mlb.com/api/v1/people/freeAgents?season=2023

API ParameterPythonPatternRequiredNullableDescription
seasonseasonYSeason year (e.g. 2024).
orderorderYorder 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
notescharacterNotes.
date_declaredcharacterDate the player declared free agency (YYYY-MM-DD).
player_idintegerMLBAM player ID.
player_full_namecharacterPlayer full name.
player_linkcharacterAPI relative link to the player.
original_team_iddoubleTeam id the player left.
original_team_namecharacterName of the team the player left.
original_team_linkcharacterAPI relative link to the original team.
new_team_linkcharacterAPI relative link to the new team.
position_codecharacterNumeric scorekeeping position code.
position_namecharacterPosition name.
position_typecharacterPosition category (e.g. 'Pitcher', 'Infielder').
position_abbreviationcharacterPosition abbreviation.
date_signedcharacterDate the player signed a new contract (YYYY-MM-DD).
new_team_iddoubleTeam id the player signed with.
new_team_namecharacterName of the team the player signed with.
sort_orderdoubleDisplay sort order for the sport.

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

Example​

mlb_free_agents(season='2023')

Last validated n/a.

mlb_jobs​

View directory by jobType.

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

Valid URL: https://statsapi.mlb.com/api/v1/jobs?jobType=UMPR

API ParameterPythonPatternRequiredNullableDescription
jobTypejob_typeYjobType query parameter.
sportIdsport_idYsportId query 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_numbercharacterJersey number worn (often blank for non-uniformed roles).
jobcharacterJob title (e.g. 'Umpire').
job_idcharacterJob code identifier.
titlecharacterSpecific role title for the assignment.
person_idintegerMLB player ID.
person_full_namecharacterPlayer full name.
person_linkcharacterAPI relative link to the person.

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

Example​

mlb_jobs(job_type='UMPR')

Last validated n/a.

mlb_datacasters​

View datacasters directory.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/jobs/datacasters

Valid URL: https://statsapi.mlb.com/api/v1/jobs/datacasters

API ParameterPythonPatternRequiredNullableDescription
sportIdsport_idYsportId 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_numbercharacterJersey number worn (often blank for non-uniformed roles).
jobcharacterJob title (e.g. 'Umpire').
job_idcharacterJob code identifier.
titlecharacterSpecific role title for the assignment.
person_idintegerMLB player ID.
person_full_namecharacterPlayer full name.
person_linkcharacterAPI relative link to the person.

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

Example​

mlb_datacasters()

Last validated n/a.

mlb_official_scorers​

View official scorer directory.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/jobs/officialScorers

Valid URL: https://statsapi.mlb.com/api/v1/jobs/officialScorers

API ParameterPythonPatternRequiredNullableDescription
sportIdsport_idYsportId 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_numbercharacterJersey number worn (often blank for non-uniformed roles).
jobcharacterJob title (e.g. 'Umpire').
job_idcharacterJob code identifier.
titlecharacterSpecific role title for the assignment.
person_idintegerMLB player ID.
person_full_namecharacterPlayer full name.
person_linkcharacterAPI relative link to the person.

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

Example​

mlb_official_scorers()

Last validated n/a.

mlb_umpire_games​

Get umpires and associated game for umpireId.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/jobs/umpires/games/{umpire_id}

Valid URL: https://statsapi.mlb.com/api/v1/jobs/umpires/games/596809?season=2023

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

Returns​

return_parsed=True (default) — a tidy polars.DataFrame (parser: parse_mlb_api_list); pass return_as_pandas=True for a pandas.DataFrame. return_parsed=False — the raw JSON Dict payload, unparsed.

Example​

mlb_umpire_games(umpire_id=596809, season='2023')

Last validated n/a.

mlb_schedule_tied​

View tied game schedule info.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/schedule/games/tied

Valid URL: https://statsapi.mlb.com/api/v1/schedule/games/tied?season=2016

API ParameterPythonPatternRequiredNullableDescription
gameTypesgame_typesYgameTypes query parameter.
seasonseasonYSeason year (e.g. 2024).
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
schedule_datecharacterThe calendar date grouping tied (suspended and resumed) games in this response row, as returned by the MLB Stats API schedule endpoint.
game_pkintegerUnique game identifier.
game_guidcharacterGlobally unique game identifier (GUID).
linkcharacterAPI link to the game feed.
game_typecharacterGame type code (R, P, etc.).
seasoncharacterSeason year.
game_datecharacterGame date (YYYY-MM-DD).
official_datecharacterOfficial game date (YYYY-MM-DD).
is_tielogicalWhether the game ended in a tie.
game_numberintegerGame number within a doubleheader.
public_facinglogicalWhether the game is public-facing.
double_headercharacterDoubleheader indicator ('N', 'S', 'Y').
gameday_typecharacterGameday data feed type.
tiebreakercharacterWhether the game is a tiebreaker.
calendar_event_idcharacterCalendar event identifier.
season_displaycharacterDisplay string for the season.
day_nightcharacterDay or night game indicator.
scheduled_inningsintegerScheduled number of innings.
reverse_home_away_statuslogicalWhether home/away teams are reversed.
inning_break_lengthintegerLength of inning breaks in seconds.
games_in_seriesintegerNumber of games in the series.
series_game_numberintegerGame number within the series.
series_descriptioncharacterDescription of the series.
record_sourcecharacterSource of the schedule record.
if_necessarycharacterWhether the game is played only if necessary.
if_necessary_descriptioncharacterDescription of the if-necessary status.
status_abstract_game_statecharacterAbstract game state (e.g. 'Final').
status_coded_game_statecharacterCoded game state.
status_detailed_statecharacterDetailed game state.
status_status_codecharacterStatus code for the game.
status_start_time_tbdlogicalWhether the start time is TBD.
status_reasoncharacterReason for the game status (e.g. 'Rain').
status_abstract_game_codecharacterAbstract game state code.
teams_away_team_idintegerAway team MLBAM ID.
teams_away_team_namecharacterAway team name.
teams_away_team_linkcharacterAPI link to the away team.
teams_away_league_record_winsintegerAway team league-record wins.
teams_away_league_record_lossesintegerAway team league-record losses.
teams_away_league_record_tiesintegerAway team league-record ties.
teams_away_league_record_pctcharacterAway team winning percentage.
teams_away_scoreintegerAway team score.
teams_away_split_squadlogicalWhether the away team is a split squad.
teams_away_series_numberintegerAway team's series number.
teams_home_team_idintegerHome team MLBAM ID.
teams_home_team_namecharacterHome team name.
teams_home_team_linkcharacterAPI link to the home team.
teams_home_league_record_winsintegerHome team league-record wins.
teams_home_league_record_lossesintegerHome team league-record losses.
teams_home_league_record_tiesintegerHome team league-record ties.
teams_home_league_record_pctcharacterHome team winning percentage.
teams_home_scoreintegerHome team score.
teams_home_split_squadlogicalWhether the home team is a split squad.
teams_home_series_numberintegerHome team's series number.
venue_idintegerMLBAM venue ID.
venue_namecharacterVenue name.
venue_linkcharacterAPI link to the venue.
content_linkcharacterAPI link to the game content.

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

Example​

mlb_schedule_tied(season='2016')

Last validated n/a.

mlb_schedule_postseason_series​

View schedule info for postseason based on series.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/schedule/postseason/series

Valid URL: https://statsapi.mlb.com/api/v1/schedule/postseason/series?season=2023

API ParameterPythonPatternRequiredNullableDescription
gameTypesgame_typesYgameTypes query parameter.
seriesNumberseries_numberYseriesNumber query parameter.
teamIdteam_idYteamId query parameter.
sportIdsport_idYsportId query parameter.
seasonseasonYSeason year (e.g. 2024).
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_itemsintegerTotal schedule items on the date.
total_gamesintegerTotal games on the date.
total_games_in_progressintegerGames currently in progress on the date.
gamescharacterNumber of games included in the ATS summary.
sort_orderintegerDisplay sort order for the sport.
series_idcharacterSeries identifier (e.g. 'W_1').
series_sort_numberintegerSort number for the series.
series_is_defaultlogicalWhether the series is the default series.
series_game_typecharacterGame type code for the series.

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

Example​

mlb_schedule_postseason_series(season='2023')

Last validated n/a.

mlb_schedule_postseason_tunein​

View schedule info for the tuneIn application.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/schedule/postseason/tuneIn

Valid URL: https://statsapi.mlb.com/api/v1/schedule/postseason/tuneIn?season=2023

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

Returns​

return_parsed=True (default) — a tidy polars.DataFrame (parser: parse_mlb_api_schedule); pass return_as_pandas=True for a pandas.DataFrame. return_parsed=False — the raw JSON Dict payload, unparsed.

Example​

mlb_schedule_postseason_tunein(season='2023')

Last validated n/a.

mlb_seasons_all​

View information for all seasons based on id.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/seasons/all

Valid URL: https://statsapi.mlb.com/api/v1/seasons/all?sportId=1

API ParameterPythonPatternRequiredNullableDescription
divisionIddivision_idYdivisionId query parameter.
leagueIdleague_idYleagueId query parameter.
withGameTypeDateswith_game_type_datesYwithGameTypeDates query parameter.
sportIdsport_idYsportId 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
season_idcharacterSeason year identifier.
has_wildcardlogicalWhether the season has a wild card round.
pre_season_start_datecharacterPre-season start date.
season_start_datecharacterSeason start date.
regular_season_start_datecharacterRegular season start date.
regular_season_end_datecharacterRegular season end date.
season_end_datecharacterSeason end date.
offseason_start_datecharacterOff-season start date.
off_season_end_datecharacterOff-season end date.
season_level_gameday_typecharacterSeason-level Gameday data feed type.
game_level_gameday_typecharacterGame-level Gameday data feed type.
qualifier_plate_appearancesdoublePlate appearances per team game to qualify.
qualifier_outs_pitcheddoubleOuts pitched per team game to qualify.
post_season_start_datecharacterPost-season start date.
post_season_end_datecharacterPost-season end date.
last_date1st_halfcharacterLast date of the first half.
all_star_datecharacterAll-Star Game date.
first_date2nd_halfcharacterFirst date of the second half.
pre_season_end_datecharacterPre-season end date.
spring_start_datecharacterSpring training start date.
spring_end_datecharacterSpring training end date.

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

Example​

mlb_seasons_all(sport_id=1)

Last validated n/a.

mlb_sport​

View information for any given sportId.

Endpoint URL: GET https://statsapi.mlb.com/api/v1/sports/{sport_id}

Valid URL: https://statsapi.mlb.com/api/v1/sports/1

API ParameterPythonPatternRequiredNullableDescription
sport_idsport_idYsport_id path 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
idintegerId.
codecharacterFielder detail type code.
linkcharacterAPI link to the game feed.
namecharacterDisplay name.
abbreviationcharacterShort abbreviation.
sort_orderintegerDisplay sort order for the sport.
active_statuslogicalWhether the sport/level is active.

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

Example​

mlb_sport(sport_id=1)

Last validated n/a.

mlb_stats_metrics​

View Statcast stats.

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

Valid URL: https://statsapi.mlb.com/api/v1/stats/metrics

API ParameterPythonPatternRequiredNullableDescription
statsstatsYstats query parameter.
groupgroupYConference or group id filter (e.g. an ESPN conference id).
gameTypegame_typeYgameType query parameter.
seasonseasonYSeason year (e.g. 2024).
startDatestart_dateYstartDate query parameter.
endDateend_dateYendDate query parameter.
venueIdvenue_idYvenueId query parameter.
minOccurrencesmin_occurrencesYminOccurrences query parameter.
percentilepercentileYpercentile query parameter.
personIdperson_idYpersonId query parameter.
teamIdteam_idYteamId query parameter.
limitlimitYMaximum number of items to return.
offsetoffsetYoffset query parameter.
hydratehydrateYhydrate query parameter.
fieldsfieldsYfields query parameter.

Returns​

return_parsed=True (default) — a tidy polars.DataFrame (parser: parse_mlb_api_list); pass return_as_pandas=True for a pandas.DataFrame. return_parsed=False — the raw JSON Dict payload, unparsed.

Example​

mlb_stats_metrics()

Last validated n/a.

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_statuscharacterAll-star status flag.
idintegerId.
namecharacterDisplay name.
linkcharacterAPI link to the game feed.
seasonintegerSeason year.
team_codecharacterInternal team code.
file_codecharacterFile code abbreviation.
abbreviationcharacterShort abbreviation.
team_namecharacterTeam name.
location_namecharacterTeam location (city).
first_year_of_playcharacterFirst year the franchise played.
short_namecharacterShort display name.
franchise_namecharacterFranchise name.
club_namecharacterClub name.
activelogicalWhether the player is currently active.
venue_idintegerMLBAM venue ID.
venue_namecharacterVenue name.
venue_linkcharacterAPI link to the venue.
spring_venue_iddoubleSpring training venue MLBAM ID.
spring_venue_linkcharacterAPI link to the spring venue.
league_idintegerLeague MLBAM ID.
league_namecharacterLeague name.
league_linkcharacterAPI link to the league.
sport_idintegerSport MLBAM ID.
sport_linkcharacterAPI link to the sport.
sport_namecharacterSport name (e.g., Major League Baseball).

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

Example​

mlb_teams_history(team_ids='147')

Last validated n/a.

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_splitsintegerTotal number of splits in the leaderboard.
exemptionscharacterA serialized list of any statistical exemption notes or flags associated with the team's stat splits (e.g., players exempt from qualifying thresholds).
splitscharacterSplits.
splits_tied_with_offsetcharacterPlayers tied at the offset boundary.
splits_tied_with_limitcharacterPlayers tied at the limit boundary.
type_display_namecharacterStat type display name.
group_display_namecharacterStat group display name.

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

Example​

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

Last validated n/a.

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_categorycharacterTeam leader category (e.g., homeRuns).
seasoncharacterSeason year.
leaderscharacterSerialized representation of the statistical leaders entries for the team stat category returned by the MLB Stats API.
stat_groupcharacterStat group (e.g., hitting).
total_splitsintegerTotal number of splits in the leaderboard.
game_type_idcharacterGame type code (e.g., R for regular season).
game_type_descriptioncharacterGame type description.

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

Example​

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

Last validated n/a.

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_numbercharacterJersey number worn (often blank for non-uniformed roles).
jobcharacterJob title (e.g. 'Umpire').
job_idcharacterJob code identifier.
titlecharacterSpecific role title for the assignment.
person_idintegerMLB player ID.
person_full_namecharacterPlayer full name.
person_linkcharacterAPI relative link to the person.

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

Example​

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

Last validated n/a.

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_numbercharacterJersey number worn (often blank for non-uniformed roles).
jobcharacterJob title (e.g. 'Umpire').
job_idcharacterJob code identifier.
titlecharacterSpecific role title for the assignment.
person_idintegerMLB player ID.
person_full_namecharacterPlayer full name.
person_linkcharacterAPI relative link to the person.

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

Example​

mlb_team_personnel(team_id=147)

Last validated n/a.

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_numbercharacterJersey number worn (often blank for non-uniformed roles).
person_idintegerMLB player ID.
person_full_namecharacterPlayer full name.
person_linkcharacterAPI relative link to the person.
position_codecharacterNumeric scorekeeping position code.
position_namecharacterPosition name.
position_typecharacterPosition category (e.g. 'Pitcher', 'Infielder').
position_abbreviationcharacterPosition abbreviation.
status_codecharacterStatus code identifier (e.g. 'S', 'P', 'I', 'F').
status_descriptioncharacterRoster status description (e.g. 'Active').

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

Example​

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

Last validated n/a.