Skip to main content

MLB — MLB Stats API — Other: pbp–venue

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
timecodetimecodeY
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.

Raises​

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

Example​

mlb_pbp(game_pk=716390)

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_sideString
team_idInt64Unique ESPN team identifier.
team_nameStringTeam name.
jersey_numberStringJersey number worn (often blank for non-uniformed roles).
parent_team_idInt64MLB Stats API identifier for the player's parent (MLB-level) organization, useful for tracking players on optional assignment.
batting_orderStringSpot in the batting order (box-score row order).
all_positionsStringAll fielding positions played by the player during the game, as a list of position codes.
person_idInt64MLB player ID.
person_full_nameStringPlayer full name.
person_linkStringAPI relative link to the person.
person_boxscore_nameStringName as shown in box scores.
position_codeStringNumeric scorekeeping position code.
position_nameStringPosition name.
position_typeStringPosition category (e.g. 'Pitcher', 'Infielder').
position_abbreviationStringPosition abbreviation.
status_codeStringStatus code identifier (e.g. 'S', 'P', 'I', 'F').
status_descriptionStringRoster status description (e.g. 'Active').
stats_batting_summaryStringCondensed text summary of the batter's performance line (e.g., '2-4, HR, 2 RBI') for display purposes.
stats_batting_games_playedFloat64Number of games played indicator for this batter's boxscore row (typically 1 for a standard game appearance).
stats_batting_fly_outsFloat64Number of outs recorded by the batter on fly balls in this game.
stats_batting_ground_outsFloat64Number of outs recorded by the batter on ground balls in this game.
stats_batting_air_outsFloat64Number of outs recorded by the batter on balls hit in the air during this game.
stats_batting_runsFloat64Number of runs scored by the batter in this game.
stats_batting_doublesFloat64Number of doubles hit by the batter in this game.
stats_batting_triplesFloat64Number of triples hit by the batter in this game.
stats_batting_home_runsFloat64Number of home runs hit by the batter in this game.
stats_batting_strike_outsFloat64Number of times the batter struck out in this game.
stats_batting_base_on_ballsFloat64Number of walks (bases on balls) drawn by the batter in this game, including intentional walks.
stats_batting_intentional_walksFloat64Number of intentional walks issued to the batter in this game.
stats_batting_hitsFloat64Total number of hits recorded by the batter in this game.
stats_batting_hit_by_pitchFloat64Number of times the batter was hit by a pitch in this game.
stats_batting_at_batsFloat64Number of official at-bats for the batter in this game.
stats_batting_caught_stealingFloat64Number of times the batter was caught stealing in this game.
stats_batting_stolen_basesFloat64Number of stolen bases recorded by the batter in this game.
stats_batting_stolen_base_percentageStringPercentage of stolen base attempts that were successful for the batter in this game.
stats_batting_ground_into_double_playFloat64Number of times the batter grounded into a double play in this game.
stats_batting_ground_into_triple_playFloat64Number of times the batter grounded into a triple play in this game.
stats_batting_plate_appearancesFloat64Total number of plate appearances for the batter in this game.
stats_batting_total_basesFloat64Total number of bases accumulated by the batter on hits in this game.
stats_batting_rbiFloat64Number of runs batted in (RBI) credited to the batter in this game.
stats_batting_left_on_baseFloat64Number of runners left on base when the batter made an out or the inning ended in this game.
stats_batting_sac_buntsFloat64Number of sacrifice bunts executed by the batter in this game.
stats_batting_sac_fliesFloat64Number of sacrifice flies hit by the batter that scored a run in this game.
stats_batting_catchers_interferenceFloat64Number of times the batter reached base due to catcher's interference in this game.
stats_batting_pickoffsFloat64Number of times the batter was picked off base in this game.
stats_batting_at_bats_per_home_runStringAt-bats per home run ratio for the batter in this game.
stats_batting_pop_outsFloat64Number of outs recorded by the batter on infield pop-ups in this game.
stats_batting_line_outsFloat64Number of outs recorded by the batter on line drives caught in this game.
stats_fielding_caught_stealingFloat64Number of baserunners caught stealing by the player (typically a catcher) in this game.
stats_fielding_stolen_basesFloat64Number of stolen bases allowed by the player while fielding in this game.
stats_fielding_stolen_base_percentageStringPercentage of stolen base attempts against the player (catcher perspective) that were successful in this game.
stats_fielding_caught_stealing_percentageStringPercentage of stolen base attempts that the player threw out in this game.
stats_fielding_assistsFloat64Number of fielding assists recorded by the player in this game.
stats_fielding_put_outsFloat64Number of putouts recorded by the player in this game.
stats_fielding_errorsFloat64Number of fielding errors committed by the player in this game.
stats_fielding_chancesFloat64Total fielding chances for the player in this game (putouts + assists + errors).
stats_fielding_fieldingStringFielding percentage for the player in this game, calculated as (putouts + assists) / total chances.
stats_fielding_passed_ballFloat64Number of passed balls charged to the player (catcher-specific) in this game.
stats_fielding_pickoffsFloat64Number of pickoffs credited to the player as a fielder in this game.
season_stats_batting_games_playedInt64Season-to-date number of games in which the batter appeared.
season_stats_batting_fly_outsInt64Season-to-date number of outs recorded by the batter on fly balls caught in the outfield.
season_stats_batting_ground_outsInt64Season-to-date number of outs recorded by the batter on ground balls.
season_stats_batting_air_outsInt64Season-to-date number of outs recorded by the batter on balls hit in the air (fly balls and line drives caught).
season_stats_batting_runsInt64Season-to-date number of runs scored by the batter.
season_stats_batting_doublesInt64Season-to-date number of doubles hit by the batter.
season_stats_batting_triplesInt64Season-to-date number of triples hit by the batter.
season_stats_batting_home_runsInt64Season-to-date number of home runs hit by the batter.
season_stats_batting_strike_outsInt64Season-to-date number of times the batter struck out.
season_stats_batting_base_on_ballsInt64Season-to-date total walks (bases on balls) drawn by the batter, including intentional walks.
season_stats_batting_intentional_walksInt64Season-to-date number of intentional walks (IBB) issued to the batter.
season_stats_batting_hitsInt64Season-to-date total number of hits recorded by the batter.
season_stats_batting_hit_by_pitchInt64Season-to-date number of times the batter was hit by a pitch.
season_stats_batting_avgStringSeason-to-date batting average (hits divided by at-bats) for the batter.
season_stats_batting_at_batsInt64Season-to-date number of official at-bats accumulated by the batter.
season_stats_batting_obpStringSeason-to-date on-base percentage (OBP), measuring how often the batter reaches base per plate appearance.
season_stats_batting_slgStringSeason-to-date slugging percentage (SLG), measuring total bases per at-bat.
season_stats_batting_opsStringSeason-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_stealingInt64Season-to-date number of times the batter was caught stealing a base.
season_stats_batting_stolen_basesInt64Season-to-date number of bases stolen by the batter.
season_stats_batting_stolen_base_percentageStringSeason-to-date percentage of stolen base attempts that were successful for the batter.
season_stats_batting_caught_stealing_percentageStringSeason-to-date percentage of stolen base attempts that resulted in the batter being caught stealing.
season_stats_batting_ground_into_double_playInt64Season-to-date number of times the batter grounded into a double play.
season_stats_batting_ground_into_triple_playInt64Season-to-date number of times the batter grounded into a triple play.
season_stats_batting_plate_appearancesInt64Season-to-date total number of plate appearances for the batter, including at-bats, walks, HBP, and sacrifices.
season_stats_batting_total_basesInt64Season-to-date total number of bases accumulated by the batter on hits.
season_stats_batting_rbiInt64Season-to-date number of runs batted in (RBI) credited to the batter.
season_stats_batting_left_on_baseInt64Season-to-date number of runners left on base when the batter made an out or the inning ended.
season_stats_batting_sac_buntsInt64Season-to-date number of sacrifice bunts executed by the batter.
season_stats_batting_sac_fliesInt64Season-to-date number of sacrifice flies hit by the batter that scored a run.
season_stats_batting_babipStringSeason-to-date Batting Average on Balls In Play (BABIP), measuring batting average excluding strikeouts and home runs.
season_stats_batting_ground_outs_to_airoutsStringSeason-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_interferenceInt64Season-to-date number of times the batter reached base due to catcher's interference.
season_stats_batting_pickoffsInt64Season-to-date number of times the batter was picked off base by a pitcher or catcher.
season_stats_batting_at_bats_per_home_runStringSeason-to-date ratio of at-bats per home run, reflecting the batter's home run frequency.
season_stats_batting_pop_outsInt64Season-to-date number of outs recorded by the batter on pop-ups caught in the infield.
season_stats_batting_line_outsInt64Season-to-date number of outs recorded by the batter on line drives caught.
season_stats_pitching_games_playedInt64Season-to-date number of games the pitcher was active on the roster (may include non-pitching appearances).
season_stats_pitching_games_startedInt64Season-to-date number of games in which the pitcher was the starting pitcher.
season_stats_pitching_fly_outsInt64Season-to-date number of outs recorded by the pitcher on fly balls.
season_stats_pitching_ground_outsInt64Season-to-date number of outs recorded by the pitcher on ground balls.
season_stats_pitching_air_outsInt64Season-to-date number of outs recorded by the pitcher on balls hit in the air.
season_stats_pitching_runsInt64Season-to-date total runs (earned and unearned) allowed by the pitcher.
season_stats_pitching_doublesInt64Season-to-date number of doubles allowed by the pitcher.
season_stats_pitching_triplesInt64Season-to-date number of triples allowed by the pitcher.
season_stats_pitching_home_runsInt64Season-to-date number of home runs allowed by the pitcher.
season_stats_pitching_strike_outsInt64Season-to-date number of batters struck out by the pitcher.
season_stats_pitching_base_on_ballsInt64Season-to-date total walks (bases on balls) issued by the pitcher, including intentional walks.
season_stats_pitching_intentional_walksInt64Season-to-date number of intentional walks (IBB) issued by the pitcher.
season_stats_pitching_hitsInt64Season-to-date number of hits allowed by the pitcher.
season_stats_pitching_hit_by_pitchInt64Season-to-date number of hit-by-pitch events while the pitcher was pitching (alternate field name for hit_batsmen).
season_stats_pitching_at_batsInt64Season-to-date number of at-bats faced by the pitcher (excluding walks, HBP, and sacrifices).
season_stats_pitching_obpStringSeason-to-date on-base percentage allowed by the pitcher (opponents' OBP against this pitcher).
season_stats_pitching_caught_stealingInt64Season-to-date number of baserunners caught stealing while the pitcher was on the mound.
season_stats_pitching_stolen_basesInt64Season-to-date number of stolen bases allowed while the pitcher was pitching.
season_stats_pitching_stolen_base_percentageStringSeason-to-date percentage of stolen base attempts that were successful while the pitcher was on the mound.
season_stats_pitching_caught_stealing_percentageStringSeason-to-date percentage of stolen base attempts that were thrown out while the pitcher was pitching.
season_stats_pitching_number_of_pitchesInt64Season-to-date total number of pitches thrown by the pitcher.
season_stats_pitching_eraStringSeason-to-date Earned Run Average (ERA) for the pitcher, expressed as earned runs per nine innings.
season_stats_pitching_innings_pitchedStringSeason-to-date total innings pitched, expressed as a decimal where each out is one-third of an inning.
season_stats_pitching_winsInt64Season-to-date number of wins credited to the pitcher.
season_stats_pitching_lossesInt64Season-to-date number of losses charged to the pitcher.
season_stats_pitching_savesInt64Season-to-date number of saves recorded by the pitcher.
season_stats_pitching_save_opportunitiesInt64Season-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_holdsInt64Season-to-date number of holds recorded by the pitcher (relief appearance maintaining a lead without a save situation).
season_stats_pitching_blown_savesInt64Season-to-date number of blown save opportunities for the pitcher.
season_stats_pitching_earned_runsInt64Season-to-date number of earned runs allowed by the pitcher.
season_stats_pitching_whipStringSeason-to-date Walks plus Hits per Inning Pitched (WHIP), measuring baserunners allowed per inning.
season_stats_pitching_batters_facedInt64Season-to-date total number of batters faced by the pitcher.
season_stats_pitching_outsInt64Season-to-date total number of outs recorded by the pitcher.
season_stats_pitching_games_pitchedInt64Season-to-date number of games in which the pitcher appeared.
season_stats_pitching_complete_gamesInt64Season-to-date number of complete games pitched by the pitcher.
season_stats_pitching_shutoutsInt64Season-to-date number of complete-game shutouts pitched.
season_stats_pitching_ballsInt64Season-to-date number of ball calls recorded against the pitcher.
season_stats_pitching_strikesInt64Season-to-date total number of strikes thrown by the pitcher.
season_stats_pitching_strike_percentageStringSeason-to-date percentage of all pitches thrown that were strikes.
season_stats_pitching_hit_batsmenInt64Season-to-date number of batters hit by a pitch thrown by the pitcher.
season_stats_pitching_balksInt64Season-to-date number of balks called against the pitcher.
season_stats_pitching_wild_pitchesInt64Season-to-date number of wild pitches thrown by the pitcher.
season_stats_pitching_pickoffsInt64Season-to-date number of pickoffs executed by the pitcher.
season_stats_pitching_ground_outs_to_airoutsStringSeason-to-date ratio of ground ball outs to air ball outs allowed by the pitcher.
season_stats_pitching_rbiInt64Season-to-date number of RBI allowed (runs batted in by opposing batters) while this pitcher was pitching.
season_stats_pitching_win_percentageStringSeason-to-date winning percentage for the pitcher (wins divided by decisions).
season_stats_pitching_pitches_per_inningStringSeason-to-date average number of pitches thrown per inning by the pitcher.
season_stats_pitching_games_finishedInt64Season-to-date number of games in which the pitcher was the last pitcher used by their team.
season_stats_pitching_strikeout_walk_ratioStringSeason-to-date ratio of strikeouts to walks, measuring the pitcher's command and dominance.
season_stats_pitching_strikeouts_per9_innStringSeason-to-date strikeouts recorded per nine innings pitched (K/9), a rate measure of strikeout ability.
season_stats_pitching_walks_per9_innStringSeason-to-date walks issued per nine innings pitched (BB/9), a rate measure of control.
season_stats_pitching_hits_per9_innStringSeason-to-date hits allowed per nine innings pitched, a rate stat measuring hit prevention.
season_stats_pitching_runs_scored_per9StringSeason-to-date total runs (including unearned) allowed per nine innings pitched.
season_stats_pitching_home_runs_per9StringSeason-to-date home runs allowed per nine innings pitched.
season_stats_pitching_inherited_runnersInt64Season-to-date number of baserunners already on base when the pitcher entered the game.
season_stats_pitching_inherited_runners_scoredInt64Season-to-date number of inherited runners who eventually scored while or after the pitcher was pitching.
season_stats_pitching_catchers_interferenceInt64Season-to-date number of times the pitcher benefited from a catcher's interference call.
season_stats_pitching_sac_buntsInt64Season-to-date number of sacrifice bunts allowed by the pitcher.
season_stats_pitching_sac_fliesInt64Season-to-date number of sacrifice flies allowed by the pitcher.
season_stats_pitching_passed_ballInt64Season-to-date number of passed balls that occurred while the pitcher was pitching.
season_stats_pitching_pop_outsInt64Season-to-date number of outs recorded by the pitcher on pop-ups caught in the infield.
season_stats_pitching_line_outsInt64Season-to-date number of outs recorded by the pitcher on line drives caught.
season_stats_fielding_caught_stealingInt64Season-to-date number of baserunners caught stealing by the player (typically a catcher stat).
season_stats_fielding_stolen_basesInt64Season-to-date number of stolen bases allowed by the player while fielding (typically catcher).
season_stats_fielding_stolen_base_percentageStringSeason-to-date percentage of stolen base attempts against the player that were successful (catcher perspective).
season_stats_fielding_caught_stealing_percentageStringSeason-to-date percentage of stolen base attempts that the player (usually a catcher) threw out.
season_stats_fielding_assistsInt64Season-to-date number of fielding assists recorded by the player (touching the ball before a putout by a teammate).
season_stats_fielding_put_outsInt64Season-to-date number of putouts recorded by the player (directly retiring a baserunner or batter).
season_stats_fielding_errorsInt64Season-to-date number of fielding errors committed by the player.
season_stats_fielding_chancesInt64Season-to-date total fielding chances for the player (putouts + assists + errors).
season_stats_fielding_fieldingStringSeason-to-date fielding percentage for the player, calculated as (putouts + assists) / total chances.
season_stats_fielding_passed_ballInt64Season-to-date number of passed balls charged to the player (catcher-specific).
season_stats_fielding_pickoffsInt64Season-to-date number of pickoffs credited to the player as a fielder.
game_status_is_current_batterBooleanIndicates whether the player is currently at bat at the moment the boxscore was captured.
game_status_is_current_pitcherBooleanIndicates whether the player is currently pitching at the moment the boxscore was captured.
game_status_is_on_benchBooleanIndicates whether the player is currently on the bench (not in the active lineup) at time of capture.
game_status_is_substituteBooleanIndicates whether the player entered the game as a substitute for another player.
stats_fielding_games_startedFloat64Indicator of whether the player started at a fielding position in this game.
season_stats_fielding_games_startedFloat64Season-to-date number of games in which the player started at a fielding position.
season_stats_pitching_pitches_thrownFloat64Season-to-date total pitches thrown by the pitcher (may differ from number_of_pitches if strikes/balls are tracked separately).
stats_pitching_summaryStringCondensed text summary of the pitcher's performance line (e.g., '6.0 IP, 2 ER, 8 K') for display purposes.
stats_pitching_games_playedFloat64Number of games the pitcher appeared in for this boxscore row (typically 1).
stats_pitching_games_startedFloat64Indicator of whether the pitcher was the starting pitcher in this game.
stats_pitching_fly_outsFloat64Number of outs recorded by the pitcher on fly balls in this game.
stats_pitching_ground_outsFloat64Number of outs recorded by the pitcher on ground balls in this game.
stats_pitching_air_outsFloat64Number of outs recorded by the pitcher on balls hit in the air in this game.
stats_pitching_runsFloat64Total runs (earned and unearned) allowed by the pitcher in this game.
stats_pitching_doublesFloat64Number of doubles allowed by the pitcher in this game.
stats_pitching_triplesFloat64Number of triples allowed by the pitcher in this game.
stats_pitching_home_runsFloat64Number of home runs allowed by the pitcher in this game.
stats_pitching_strike_outsFloat64Number of batters struck out by the pitcher in this game.
stats_pitching_base_on_ballsFloat64Number of walks (bases on balls) issued by the pitcher in this game, including intentional walks.
stats_pitching_intentional_walksFloat64Number of intentional walks (IBB) issued by the pitcher in this game.
stats_pitching_hitsFloat64Number of hits allowed by the pitcher in this game.
stats_pitching_hit_by_pitchFloat64Number of hit-by-pitch events while the pitcher was pitching in this game (alternate field for hit_batsmen).
stats_pitching_at_batsFloat64Number of at-bats faced by the pitcher (excluding walks, HBP, and sacrifices) in this game.
stats_pitching_caught_stealingFloat64Number of baserunners caught stealing while the pitcher was on the mound in this game.
stats_pitching_stolen_basesFloat64Number of stolen bases allowed while the pitcher was pitching in this game.
stats_pitching_stolen_base_percentageStringPercentage of stolen base attempts that were successful while the pitcher was on the mound in this game.
stats_pitching_number_of_pitchesFloat64Total number of pitches thrown by the pitcher in this game.
stats_pitching_innings_pitchedStringTotal innings pitched by the pitcher in this game, expressed as a decimal (each out counts as one-third of an inning).
stats_pitching_winsFloat64Indicator of whether the pitcher was credited with the win in this game.
stats_pitching_lossesFloat64Indicator of whether the pitcher was charged with the loss in this game.
stats_pitching_savesFloat64Indicator of whether the pitcher recorded a save in this game.
stats_pitching_save_opportunitiesFloat64Number of save opportunities the pitcher entered in this game.
stats_pitching_holdsFloat64Number of holds recorded by the pitcher in this game.
stats_pitching_blown_savesFloat64Number of blown save opportunities for the pitcher in this game.
stats_pitching_earned_runsFloat64Number of earned runs allowed by the pitcher in this game.
stats_pitching_batters_facedFloat64Total number of batters faced by the pitcher in this game.
stats_pitching_outsFloat64Total number of outs recorded by the pitcher in this game.
stats_pitching_games_pitchedFloat64Number of pitching appearances for the pitcher in this game (typically 1).
stats_pitching_complete_gamesFloat64Indicator of whether the pitcher threw a complete game in this appearance.
stats_pitching_shutoutsFloat64Indicator of whether the pitcher recorded a complete-game shutout in this game.
stats_pitching_pitches_thrownFloat64Total pitches thrown by the pitcher in this game (may differ from number_of_pitches depending on tracking method).
stats_pitching_ballsFloat64Number of ball calls recorded against the pitcher in this game.
stats_pitching_strikesFloat64Total number of strikes thrown by the pitcher in this game.
stats_pitching_strike_percentageStringPercentage of all pitches thrown that were strikes in this game.
stats_pitching_hit_batsmenFloat64Number of batters hit by a pitch thrown by the pitcher in this game.
stats_pitching_balksFloat64Number of balks called against the pitcher in this game.
stats_pitching_wild_pitchesFloat64Number of wild pitches thrown by the pitcher in this game.
stats_pitching_pickoffsFloat64Number of pickoffs executed by the pitcher in this game.
stats_pitching_rbiFloat64Number of RBI allowed (runs batted in by opposing batters off this pitcher) in this game.
stats_pitching_games_finishedFloat64Indicator of whether the pitcher was the last pitcher used by their team in this game.
stats_pitching_runs_scored_per9StringTotal runs (including unearned) allowed per nine innings rate for the pitcher in this game.
stats_pitching_home_runs_per9StringHome runs allowed per nine innings rate for the pitcher in this game.
stats_pitching_inherited_runnersFloat64Number of baserunners already on base when the pitcher entered the game.
stats_pitching_inherited_runners_scoredFloat64Number of inherited runners who scored while or after the pitcher was pitching in this game.
stats_pitching_catchers_interferenceFloat64Number of catcher's interference calls that occurred while the pitcher was pitching in this game.
stats_pitching_sac_buntsFloat64Number of sacrifice bunts allowed by the pitcher in this game.
stats_pitching_sac_fliesFloat64Number of sacrifice flies allowed by the pitcher in this game.
stats_pitching_passed_ballFloat64Number of passed balls that occurred while the pitcher was pitching in this game.
stats_pitching_pop_outsFloat64Number of outs recorded by the pitcher on infield pop-ups in this game.
stats_pitching_line_outsFloat64Number of outs recorded by the pitcher on line drives caught in this game.
stats_pitching_noteStringSupplementary note or annotation attached to the pitcher's boxscore line (e.g., indicating a special circumstance).
stats_batting_noteStringSupplementary 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.

Raises​

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

Example​

mlb_boxscore(game_pk=716390)

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
numInt64Inning number.
ordinal_numStringInning ordinal label (e.g. 1st).
home_runsInt64Home runs.
home_hitsInt64Home hits in the inning.
home_errorsInt64Home errors in the inning.
home_left_on_baseInt64Home runners left on base in the inning.
away_runsInt64Away runs scored in the inning.
away_hitsInt64Away hits in the inning.
away_errorsInt64Away errors in the inning.
away_left_on_baseInt64Away runners left on base in the inning.

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

Raises​

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

Example​

mlb_linescore(game_pk=716390)

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_indexStringA serialized list of indices identifying individual pitch events within the at-bat for this win-probability row.
action_indexStringA serialized list of indices identifying action-type events (stolen bases, pickoffs, etc.) within the at-bat for this win-probability row.
runner_indexStringA serialized list of indices identifying baserunner movement events during the play in this win-probability row.
runnersStringA serialized representation of baserunner movement records for this play in the win-probability feed, capturing start/end base positions and event types.
play_eventsStringA serialized representation of the sequence of pitch and action events comprising the at-bat for this win-probability row.
creditsStringA serialized list of player credit records for this play, linking fielding, pitching, or batting achievements to specific player identifiers.
flagsStringA 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_probabilityFloat64Home team win probability (percent) entering the at-bat.
away_team_win_probabilityFloat64Away team win probability (percent) entering the at-bat.
home_team_win_probability_addedFloat64Change in home team win probability attributed to the at-bat.
play_end_timeStringThe ISO 8601 timestamp marking the conclusion of the play associated with this win-probability snapshot.
at_bat_indexInt64Zero-based index of the at-bat within the game.
result_typeStringThe high-level category of the play result in the win-probability feed (e.g., 'atBat', 'action').
result_eventStringThe short categorical label for the play outcome in the win-probability feed (e.g., 'Single', 'Home Run', 'Strikeout').
result_event_typeStringThe snake-cased type identifier for the play outcome in the win-probability feed (e.g., 'single', 'home_run').
result_descriptionStringA human-readable text description of the play result as reported in the win-probability game feed.
result_rbiInt64The number of runs batted in credited to the batter for the play in this win-probability row.
result_away_scoreInt64The away team's cumulative run total at the conclusion of the play in this win-probability row.
result_home_scoreInt64The home team's cumulative run total at the conclusion of the play in this win-probability row.
result_is_outBooleanBoolean flag indicating whether the batter was retired on the play recorded in this win-probability row.
about_at_bat_indexInt64The sequential index of the at-bat within the game to which this win-probability observation belongs.
about_half_inningStringIndicates whether the win-probability observation occurred in the top or bottom half of the inning.
about_is_top_inningBooleanBoolean flag indicating whether this win-probability observation occurred in the top half of the inning.
about_inningInt64The inning number in which this win-probability observation was recorded.
about_start_timeStringThe ISO 8601 timestamp marking the start of the play event within the win-probability game feed.
about_end_timeStringThe ISO 8601 timestamp marking the end of the play event within the win-probability game feed.
about_is_completeBooleanBoolean flag indicating whether the at-bat associated with this win-probability row has concluded.
about_is_scoring_playBooleanBoolean flag indicating whether this play resulted in one or more runs being scored.
about_has_reviewBooleanBoolean flag indicating whether this play was subject to a manager's challenge or umpire review.
about_has_outBooleanBoolean flag indicating whether this play resulted in at least one out being recorded.
about_captivating_indexInt64A numeric score reflecting how compelling or exciting this plate appearance was, based on leverage and game-state context.
count_ballsInt64The ball count in the current at-bat at the time this win-probability snapshot was recorded.
count_strikesInt64The strike count in the current at-bat at the time this win-probability snapshot was recorded.
count_outsInt64The number of outs in the current half-inning at the time this win-probability snapshot was recorded.
matchup_batter_idInt64The MLB Stats API (MLBAM) numeric identifier for the batter in this win-probability matchup row.
matchup_batter_full_nameStringThe full name of the batter whose plate appearance generated this win-probability observation.
matchup_batter_linkStringThe MLB Stats API relative URL linking to the batter's player resource for this win-probability row.
matchup_bat_side_codeStringA single-character code indicating the batter's handedness for this matchup in the win-probability feed (e.g., 'L', 'R', 'S').
matchup_bat_side_descriptionStringThe human-readable description of the batter's hitting side for this win-probability matchup row.
matchup_pitcher_idInt64The MLB Stats API (MLBAM) numeric identifier for the pitcher in this win-probability matchup row.
matchup_pitcher_full_nameStringThe full name of the pitcher who delivered pitches for this win-probability observation.
matchup_pitcher_linkStringThe MLB Stats API relative URL linking to the pitcher's player resource for this win-probability row.
matchup_pitch_hand_codeStringA single-character code indicating the pitcher's throwing hand for this win-probability matchup (e.g., 'L' or 'R').
matchup_pitch_hand_descriptionStringThe human-readable description of the pitcher's throwing arm for this win-probability matchup row.
matchup_post_on_first_idFloat64The 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_nameStringThe full name of the runner occupying first base at the conclusion of the play in this win-probability row.
matchup_post_on_first_linkStringThe MLB Stats API relative URL linking to the player resource of the runner on first base after the play.
matchup_batter_hot_cold_zonesStringA serialized representation of the batter's hot and cold zone data applicable to this win-probability matchup.
matchup_pitcher_hot_cold_zonesStringA serialized representation of the pitcher's hot and cold zone data applicable to this win-probability matchup.
matchup_splits_batterStringA string describing the batter's situational split for this win-probability matchup (e.g., 'vs. Right').
matchup_splits_pitcherStringA string describing the pitcher's situational split for this win-probability matchup (e.g., 'vs. Left').
matchup_splits_men_on_baseStringA string describing the baserunner configuration applicable to the batter's situational split in this win-probability row.
leverage_indexFloat64Leverage index quantifying the importance of the at-bat situation.
drama_indexFloat64A numeric score quantifying the dramatic significance of this play within the game, based on win-probability swing and game leverage.
matchup_post_on_second_idFloat64The 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_nameStringThe full name of the runner occupying second base at the conclusion of the play in this win-probability row.
matchup_post_on_second_linkStringThe MLB Stats API relative URL linking to the player resource of the runner on second base after the play.
matchup_post_on_third_idFloat64The 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_nameStringThe full name of the runner occupying third base at the conclusion of the play in this win-probability row.
matchup_post_on_third_linkStringThe MLB Stats API relative URL linking to the player resource of the runner on third base after the play.
review_details_is_overturnedBooleanBoolean flag indicating whether the original on-field ruling was reversed following the replay review for this play.
review_details_in_progressBooleanBoolean flag indicating whether a replay review of this play was still underway at the time of data capture.
review_details_review_typeStringThe type of review mechanism applied to this play in the win-probability feed (e.g., 'managerChallenge', 'umpireReview').
review_details_challenge_team_idFloat64The 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.

Raises​

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

Example​

mlb_win_probability(game_pk=716390)

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

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

Raises​

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

Example​

mlb_people()

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

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

Raises​

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

Example​

mlb_person(person_id=660271)

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_splitsFloat64Total number of splits in the leaderboard.
exemptionsStringSerialized list of statistical exemptions or special-case flags applied to this player's game-log splits.
splitsStringSplits.
type_display_nameStringStat type display name.
group_display_nameStringStat group display name.

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

Raises​

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

Example​

mlb_person_game_stats(person_id=660271, game_pk=716390)

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/1/players

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

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

Raises​

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

Example​

mlb_sport_players()

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
idInt64Id.
codeStringFielder detail type code.
linkStringAPI link to the game feed.
nameStringDisplay name.
abbreviationStringShort abbreviation.
sort_orderInt64Display sort order for the sport.
active_statusBooleanWhether the sport/level is active.

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

Raises​

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

Example​

mlb_sports()

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?sportId=1

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
idInt64Numeric league id from the source API (PFF: 1 = NFL).
nameStringLeague display name as the source lists it (PFF: 'Pro Football').
linkStringAPI link to the game feed.
abbreviationStringLeague abbreviation as the source lists it (e.g. NFL).
name_shortString
season_stateStringA string describing the current phase of the league's season (e.g., 'inProgress', 'offseason', 'preseason').
has_wild_cardBooleanBoolean flag indicating whether this league includes a wild card playoff format for postseason eligibility.
has_split_seasonBooleanBoolean flag indicating whether this league divides its season into two halves with separate standings (as used historically in some minor leagues).
num_gamesFloat64The total number of regular-season games scheduled per team in this league for the given season.
has_playoff_pointsBooleanBoolean flag indicating whether this league uses a playoff points system to determine postseason seeding.
num_teamsFloat64Number of teams the player appeared for.
num_wildcard_teamsFloat64The number of wild card berths available for postseason entry in this league for the given season.
seasonStringSeason year.
org_codeStringThe organizational code identifying the parent body (e.g., 'MLB') governing this league within the MLB Stats API hierarchy.
conferences_in_useBoolean
divisions_in_useBoolean
sort_orderInt64Display sort order for the sport.
activeBooleanWhether the player is currently active.
season_date_info_season_idStringSeason identifier for the date info block.
season_date_info_pre_season_start_dateStringPreseason start date (YYYY-MM-DD).
season_date_info_pre_season_end_dateStringPreseason end date (YYYY-MM-DD).
season_date_info_season_start_dateStringSeason start date (YYYY-MM-DD).
season_date_info_spring_start_dateStringSpring training start date (YYYY-MM-DD).
season_date_info_spring_end_dateStringSpring training end date (YYYY-MM-DD).
season_date_info_regular_season_start_dateStringRegular season start date (YYYY-MM-DD).
season_date_info_last_date1st_halfStringLast date of the first half (YYYY-MM-DD).
season_date_info_all_star_dateStringAll-Star Game date (YYYY-MM-DD).
season_date_info_first_date2nd_halfStringFirst date of the second half (YYYY-MM-DD).
season_date_info_regular_season_end_dateStringRegular season end date (YYYY-MM-DD).
season_date_info_post_season_start_dateStringPostseason start date (YYYY-MM-DD).
season_date_info_post_season_end_dateStringPostseason end date (YYYY-MM-DD).
season_date_info_season_end_dateStringSeason end date (YYYY-MM-DD).
season_date_info_offseason_start_dateStringOffseason start date (YYYY-MM-DD).
season_date_info_off_season_end_dateStringOffseason end date (YYYY-MM-DD).
season_date_info_season_level_gameday_typeStringSeason-level Gameday data type code.
season_date_info_game_level_gameday_typeStringGame-level Gameday data type code.
season_date_info_qualifier_plate_appearancesFloat64Plate appearances per game needed to qualify.
season_date_info_qualifier_outs_pitchedFloat64Outs pitched per game needed to qualify.
sport_idFloat64Sport MLBAM ID.
sport_linkStringAPI link to the sport.

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

Raises​

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

Example​

mlb_leagues()

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?sportId=1

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_idStringstats.ncaa.org season identifier.
has_wildcardBooleanWhether the season has a wild card round.
pre_season_start_dateStringPre-season start date.
pre_season_end_dateStringPre-season end date.
season_start_dateStringSeason start date.
spring_start_dateStringSpring training start date.
spring_end_dateStringSpring training end date.
regular_season_start_dateStringRegular season start date.
last_date1st_halfStringLast date of the first half.
all_star_dateStringAll-Star Game date.
first_date2nd_halfStringFirst date of the second half.
regular_season_end_dateStringRegular season end date.
post_season_start_dateStringPost-season start date.
post_season_end_dateStringPost-season end date.
season_end_dateStringSeason end date.
offseason_start_dateStringOff-season start date.
off_season_end_dateStringOff-season end date.
season_level_gameday_typeStringSeason-level Gameday data feed type.
game_level_gameday_typeStringGame-level Gameday data feed type.
qualifier_plate_appearancesFloat64Plate appearances per team game to qualify.
qualifier_outs_pitchedFloat64Outs pitched per team game to qualify.

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

Raises​

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

Example​

mlb_season(season_id='X')

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
idInt64Id.
nameStringDisplay name.
linkStringAPI link to the game feed.
activeBooleanWhether the player is currently active.
seasonStringSeason year.

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

Raises​

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

Example​

mlb_venues()

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
idInt64Id.
nameStringDisplay name.
linkStringAPI link to the game feed.
activeBooleanWhether the player is currently active.
seasonStringSeason year.

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

Raises​

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

Example​

mlb_venue(venue_id=15)