Skip to main content

MLB — MLB Stats API — Play

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_indexStringA serialized list of indices identifying individual pitch events that occurred within this at-bat.
action_indexStringA serialized list of indices identifying action-type events (e.g., stolen bases, pickoffs) that occurred within the at-bat.
runner_indexStringA serialized list of indices identifying baserunner movement events that occurred during or after this play.
runnersStringA serialized representation of baserunner movement records for this play, including starting base, ending base, and relevant event types.
play_eventsStringA serialized representation of the sequence of individual pitch and action events comprising this at-bat.
play_end_timeStringThe ISO 8601 timestamp marking the conclusion of the entire play (as distinct from a single pitch event) within the game feed.
at_bat_indexInt64Zero-based index of the at-bat within the game.
result_typeStringThe high-level category of the play result as classified by the MLB Stats API (e.g., 'atBat', 'action').
result_eventStringThe short categorical label for the play outcome as classified by the MLB Stats API (e.g., 'Strikeout', 'Home Run', 'Walk').
result_event_typeStringThe snake-cased type identifier for the play outcome used internally by the MLB Stats API (e.g., 'strikeout', 'home_run').
result_descriptionStringA human-readable text description of the play result as reported by the MLB Stats API (e.g., 'Strikeout', 'Single to left field').
result_rbiInt64The number of runs batted in credited to the batter as a result of this play.
result_away_scoreInt64The away team's cumulative run total at the conclusion of this play.
result_home_scoreInt64The home team's cumulative run total at the conclusion of this play.
result_is_outBooleanBoolean flag indicating whether the play resulted in the batter being retired (i.e., an out was charged to the batter).
about_at_bat_indexInt64The sequential index of the at-bat within the game to which this play or pitch event belongs.
about_half_inningStringIndicates whether the play occurred in the top or bottom half of the inning (e.g., 'top' or 'bottom').
about_is_top_inningBooleanBoolean flag indicating whether this play occurred in the top half of the inning (true) or bottom half (false).
about_inningInt64The inning number in which this play or pitch event occurred.
about_start_timeStringThe ISO 8601 timestamp marking the start of the play event, used for temporal sequencing within the game feed.
about_end_timeStringThe ISO 8601 timestamp marking the end of the play event, used for temporal sequencing within the game feed.
about_is_completeBooleanBoolean flag indicating whether the at-bat or play event has concluded (i.e., reached a terminal result).
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 assigned by the MLB Stats API reflecting how compelling or exciting a given play was, based on leverage and game context.
count_ballsInt64The ball count in the current at-bat at the time of this pitch or play event.
count_strikesInt64The strike count in the current at-bat at the time of this pitch or play event.
count_outsInt64The number of outs recorded in the current half-inning at the time of this pitch or play event.
matchup_batter_idInt64The MLB Stats API (MLBAM) numeric identifier for the batter in this play's matchup.
matchup_batter_full_nameStringThe full name of the batter involved in this plate appearance.
matchup_batter_linkStringThe MLB Stats API relative URL linking to the batter's player resource for this matchup.
matchup_bat_side_codeStringA 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_descriptionStringThe human-readable description of the batter's hitting side for this matchup (e.g., 'Left', 'Right', 'Switch').
matchup_pitcher_idInt64The MLB Stats API (MLBAM) numeric identifier for the pitcher in this play's matchup.
matchup_pitcher_full_nameStringThe full name of the pitcher involved in this plate appearance.
matchup_pitcher_linkStringThe MLB Stats API relative URL linking to the pitcher's player resource for this matchup.
matchup_pitch_hand_codeStringA single-character code indicating the pitcher's throwing hand for this matchup (e.g., 'L' for left, 'R' for right).
matchup_pitch_hand_descriptionStringThe human-readable description of the pitcher's throwing arm for this matchup (e.g., 'Left', 'Right').
matchup_post_on_first_idFloat64The MLB Stats API (MLBAM) numeric identifier for the runner on first base after the play concluded.
matchup_post_on_first_full_nameStringThe full name of the baserunner on first base after the play concluded, if applicable.
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 effectiveness data for this matchup context.
matchup_pitcher_hot_cold_zonesStringA serialized representation of the pitcher's hot and cold zone effectiveness data for this matchup context.
matchup_splits_batterStringA string describing the batter's situational split relevant to this matchup (e.g., 'vs. Right' or 'vs. Left').
matchup_splits_pitcherStringA string describing the pitcher's situational split relevant to this matchup (e.g., 'vs. Left' or 'vs. Right').
matchup_splits_men_on_baseStringA string describing the baserunner configuration applicable to the batter's situational split for this plate appearance.
matchup_post_on_second_idFloat64The MLB Stats API (MLBAM) numeric identifier for the runner on second base after the play concluded.
matchup_post_on_second_full_nameStringThe full name of the baserunner on second base after the play concluded, if applicable.
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 concluded.
matchup_post_on_third_full_nameStringThe full name of the baserunner on third base after the play concluded, if applicable.
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 call was reversed as a result of the replay review.
review_details_in_progressBooleanBoolean flag indicating whether the umpire review of this play was still ongoing at the time of data capture.
review_details_review_typeStringThe type of review mechanism applied to this play (e.g., 'managerChallenge', 'umpireReview').
review_details_challenge_team_idFloat64The 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.

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_play_by_play(game_pk=716390)

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) — the output of parse_mlb_api_list; pass return_as_pandas=True for a pandas.DataFrame.

No returns table is published for this endpoint: no capture: statsapi.mlb.com answers 406 to the datacenter IP and 401 'Please Login' through the residential proxy; the route needs an MLB login session the package does not hold.

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_play_analytics(game_pk=716390, guid='90groovy-2438-test-guid-placeholder0')

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) — the output of parse_mlb_api_list; pass return_as_pandas=True for a pandas.DataFrame.

No returns table is published for this endpoint: no capture: statsapi.mlb.com answers 406 to the datacenter IP and 401 'Please Login' through the residential proxy; the route needs an MLB login session the package does not hold.

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_play_context_metrics_averages(game_pk=716390, guid='90groovy-2438-test-guid-placeholder0')