Docs
Coverage MatrixDocumentationRelease LogLog In

Play-by-Play

MLB Play-by-Play provides detailed, real-time information on every pitch and game event.

⏱️

Update Frequency

TTL / Cache: This endpoint will update to a 2s TTL (time to live) upon a game moving to inprogress. Upon closed, it will transfer to 120s.

Data Updates: Realtime



Data Points

Boxscore:
AttributeParent ElementTypeDescription
attendancegameIntegerAttendance of a game
abbrawayStringAbbreviation of the away team
ex. MIN (Minnesota)
durationgameStringDuration of a game in hours and minutes
ex. 3:18
errorsawayIntegerNumber of errors for the away team
errorsaway-inningIntegerNumber of errors for the away team in an inning
hitsawayIntegerNumber of hits for the away team
hitsaway-inningIntegerNumber of hits for the away team in an inning
idawayGUIDUnique ID of the away team
ex. 29dd9a87-5bcc-4774-80c3-7f50d985068b
marketawayStringMarket name of the away team
ex. Colorado
nameawayStringTeam name of the away team
ex. Rockies
runsawayIntegerNumber of runs for the away team in the game
runsaway-inningIntegerNumber of runs for the away team in an inning
abbrhomeStringAbbreviation of the home team
ex. CLE (Cleveland)
errorshomeIntegerNumber of errors for the home team
errorshome-inningIntegerNumber of errors for the home team in an inning
hitshomeIntegerNumber of hits for the home team
hitshome-inningIntegerNumber of hits for the home team in an inning
idhomeGUIDUnique ID of the home team
ex. 29dd9a87-5bcc-4774-80c3-7f50d985068b
markethomeStringMarket name of the home team
ex. Cleveland
namehomeStringTeam name of the home team
ex. Guardians
runshomeIntegerNumber of runs for the home team in the game
runshome-inningIntegerNumber of runs for the home team in an inning
Game:
AttributeParent ElementTypeDescription
away_teamgameGUIDUnique ID of the away team
ex. 29dd9a87-5bcc-4774-80c3-7f50d985068b
cablebroadcastStringName of the game's broadcast cable station
internetbroadcastStringName of the game's internet stream
networkbroadcastStringName of the game's broadcast network
ex. MLB Network
radiobroadcastStringName of the game's broadcast radio station
satellitebroadcastStringName of the game's broadcast satellite station
coveragegameStringCoverage level of a game
full, boxscore
double_headergameBooleanSignifies whether a game is part of a double header
day_nightgameStringSignifies a day or night game
D, N
entry_modegameStringSignifies the type of data entry
STOMP, LDE
home_teamgameGUIDUnique ID of the home team
ex. ef64da7f-cfaf-4300-87b0-9313386b977c
idgameGUIDUnique ID of the game
ex. 1b554f5e-d8b7-4268-95da-2f4191015c84
game_numbergameIntegerNumber of the game
parent_idgameGUIDStandard parent ID of a game or series. Use this ID to group events (like the World Series or All-Star Game) across seasons.
ex. 34e4cbbe-0086-4fad-bb08-840cbcfcabf0 (All-Star Game)
referencegameStringUnique MLBAM ID of a game
scheduledgamedateTimeScheduled date and time of a game
ex. 2022-09-25T20:10:00+00:00
tbdgameBooleanSignifies the game start time is to be determined. Placeholder start time is 08:00:00+00:00
season_idgameGUIDUnique ID of the season a game belongs within
ex. 6a5c278f-ebce-41f9-b1ba-2160b6af04ce
season_typegameStringCode type of the season a game belongs within
ex. REG (Regular), PRE (Preseason), PST (Postseason), AST (All-Star)
season_yeargameIntegerYear of the season a game belongs within
split_squadgameBooleanSignifies a Spring Training split squad game
statusgameStringThe status of a game
scheduled, inprogress, complete, closed, wdelay, fdelay, odelay, canceled, unnecessary, if-necessary, postponed, suspended, maintenance
ideventGUIDUnique ID of a deleted event
ex. 5e3a0b5d-72fa-40e5-8f9d-a10e6a46a831
awaygame-time_zonesStringTime zone of the away team
ex. US/Pacific
homegame-time_zonesStringTime zone of the home team
ex. US/Eastern
venuegame-time_zonesStringTime zone of the venue
ex. US/Eastern
Weather:
AttributeParent ElementTypeDescription
cloud_covercurrent_conditionsIntegerCurrent cloud cover of a game in percentage
conditioncurrent_conditionsStringCurrent weather condition of a game
dew_point_fcurrent_conditionsIntegerCurrent dew point number of a game
humiditycurrent_conditionsIntegerCurrent humidity number of a game
obs_timecurrent_conditionsdateTimeTimestamp of the current weather observation
ex. 2020-02-24T20:24:34.000Z
current_temperature_fcurrent_conditionsIntegerCurrent temperature of a game in Fahrenheit
directionwindStringDirection of wind in the game
speed_mphwindIntegerWind speed in the game in miles per hour
cloud_coverforecastedIntegerForcasted cloud cover of a game in percentage
conditionforecastedStringForecasted weather condition of a game
dew_point_fforecastedIntegerForecasted dew point number of a game
humidityforecastedIntegerForecasted humidity number of a game
obs_timeforecasteddateTimeTimestamp of the forecasted weather observation
ex. 2020-02-24T20:24:34.000Z
current_temperature_fforecastedIntegerForecasted temperature of a game in Fahrenheit
directionwindStringForecasted direction of wind in the game
speed_mphwindIntegerForecasted wind speed in a game in miles per hour
Lineup:
AttributeParent ElementTypeDescription
orderlineupIntegerBatting order number in the lineup for a player (0-9). 0 is used for the pitcher
descriptionlineupStringText description of a lineup change
ex. Albert Pujols pinch-hitting for Corey Dickerson.
positionlineupIntegerPosition number for a player (1-10). 10 is used for the designated hitter
idlineupGUIDUnique ID of a lineup entry
ex. 616d0907-26f1-4adf-875f-c0928d6d1b22
first_namelineupStringFirst name of a player
ex. Markus
full_namelineupStringFull name of a player
ex. Mookie Betts
suffixlineupStringName suffix of a player
ex. Jr.
player_idlineupGUIDUnique ID of a player
ex. 084d2514-9ffb-414e-ae16-3bc690aaad51
jersey_numberlineupIntegerNumber of a player's jersey
last_namelineupStringLast name of a player
ex. Betts
preferred_namelineupStringPreferred name of a player
ex. Mookie
team_idlineupGUIDUnique ID of a player's team
ex. ef64da7f-cfaf-4300-87b0-9313386b977c
Play-By-Play - At Bat:
AttributeParent ElementTypeDescription
first_namehitterStringFirst name of a hitter
ex. Markus
full_namehitterStringFull name of a hitter
ex. Mookie Betts
suffixhitterStringName suffix of a hitter
ex. Jr.
hitter_handat_batStringHandedness of a hitter
hitter_idat_batGUIDUnique ID of a hitter
ex. 084d2514-9ffb-414e-ae16-3bc690aaad51
jersey_numberhitterIntegerNumber of a hitter's jersey
last_namehitterStringLast name of a hitter
ex. Betts
preferred_namehitterStringPreferred name of a player
ex. Mookie
idat_batGUIDUnique ID of an at bat entry
ex. c1e69331-8909-4f1c-b132-5b33079355b4
first_namepitcherStringFirst name of a pitcher
ex. Adam
full_namepitcherStringFull name of a pitcher
ex. Adam Wainwright
suffixpitcherStringName suffix of a pitcher
ex. Jr.
pitcher_handat_batStringHandedness of a pitcher
pitcher_idat_batGUIDUnique ID of a pitcher
ex. 084d2514-9ffb-414e-ae16-3bc690aaad51
jersey_numberpitcherIntegerNumber of a pitcher's jersey
last_namepitcherStringLast name of a pitcher
ex. Wainwright
preferred_namepitcherStringPreferred name of a pitcher
ex. Adam
description-StringText description of a play
ex. Will Smith singles to center field. Freddie Freeman to third.
sequence_numberat_batIntegerSequence number of an event within a game
Play-By-Play - Base Runner:
AttributeParent ElementTypeDescription
ending_baserunnerIntegerRunner's base at the end of a play
first_namerunnerStringFirst name of a runner
ex. Markus
full_namerunnerStringFull name of a runner
ex. Mookie Betts
suffixrunnerStringName suffix of a runner
ex. Jr.
jersey_numberrunnerIntegerNumber of a runner's jersey
last_namerunnerStringLast name of a runner
ex. Betts
outrunnerBooleanSignifies the runner was out on a play
outcome_idrunnerStringID of a runner outcome on a play. Check our FAQ for a list of valid outcomes and their definitions
description-StringText description of a runner outcome
ex. Will Smith to third. or Freddie Freeman scores.
idrunnerGUIDUnique ID of a player of a runner
ex. ea1a2111-44cc-4996-babb-9439465e6760
preferred_namerunnerStringPreferred name of a runner
ex. Mookie
starting_baserunnerIntegerRunner's base at the start of a play
created_atrunner_placeddateTimeTimestamp of a runner placed at 2nd base to start an inning
ex. 2022-09-25T20:10:00+00:00
idrunner_placedGUIDUnique ID of a runner placed at 2nd base to start an inning
officialrunner_placedBooleanSignifies whether the API is ingesting data directly from the league at the time of the event.

For true, entry_mode=Ingest. For false, entry_mode=LDE.
sequence_numberrunner_placedIntegerSequential number of a runner placed event in a game
statusrunner_placedStringStatus of a runner placed event. Can be utilized to determine if a play is or was under review
official, overturned, under review, upheld
updated_atrunner_placeddateTimeTimestamp of a runner placed event
ex. 2022-09-25T20:25:14+00:00
Play-By-Play - Hitter:
AttributeParent ElementTypeDescription
first_namehitterStringFirst name of a hitter
ex. Markus
full_namehitterStringFull name of a hitter
ex. Mookie Betts
suffixhitterStringName suffix of a hitter
ex. Jr.
hitter_handpitcherStringHandedness of a hitter
idhitterGUIDUnique ID of a player of a hitter
ex. ea1a2111-44cc-4996-babb-9439465e6760
jersey_numberhitterIntegerNumber of a hitter's jersey
last_namehitterStringLast name of a hitter
ex. Betts
preferred_namehitterStringPreferred name of a hitter
ex. Mookie
Play-By-Play - Count:
AttributeParent ElementTypeDescription
ballscountIntegerNumber of balls in an at bat
outscountIntegerNumber of outs in an at bat
pitch_countcountIntegerNumber of pitches in an at bat
strikescountIntegerNumber of strikes in an at bat
Play-By-Play - Errors:
AttributeParent ElementTypeDescription
first_nameerrorStringFirst name of a player committing an error
ex. Gavin
full_nameerrorStringFull name of a player committing an error
ex. Gavin Lux
suffixerrorStringName suffix of a player committing an error
ex. Jr.
iderrorGUIDUnique ID of a player of a player committing an error
ex. ea1a2111-44cc-4996-babb-9439465e6760
jersey_numbererrorIntegerJersey number a player committing an error
last_nameerrorStringLast name of a player committing an error
ex. Lux
preferred_nameerrorStringPreferred name of a player committing an error
ex. Gavin
typeerrorStringType of fielding error
fielding, throwing, interference
Play-By-Play - Fielding:
AttributeParent ElementTypeDescription
first_nameassistStringFirst name of a player recording an assist
ex. Gavin
full_nameassistStringFull name of a player recording an assist
ex. Gavin Lux
suffixassistStringName suffix of a player recording an assist
ex. Jr.
idassistGUIDUnique ID of a player of a player recording an assist
ex. ea1a2111-44cc-4996-babb-9439465e6760
jersey_numberassistIntegerJersey number a player recording an assist
last_nameassistStringLast name of a player recording an assist
ex. Lux
preferred_nameassistStringPreferred name of a player recording an assist
ex. Gavin
sequenceassistIntegerSequential number of an assist
first_nameputoutStringFirst name of a player recording a putout
ex. Byron
full_nameputoutStringFull name of a player recording a putout
ex. Byron Buxton
suffixputoutStringName suffix of a player recording a putout
ex. Jr.
idputoutGUIDUnique ID of a player of a player recording a putout
ex. ea1a2111-44cc-4996-babb-9439465e6760
jersey_numberputoutIntegerJersey number a player recording a putout
last_nameputoutStringLast name of a player recording a putout
ex. Buxton
preferred_nameputoutStringPreferred name of a player recording a putout
ex. Gavin
sequenceputoutIntegerSequential number of a putout
Play-By-Play - Hit Data:
AttributeParent ElementTypeDescription
coord_xcoordinatesDecimalX coordinate marked by operator of where the ball was fielded
coord_ycoordinatesDecimalY coordinate marked by operator of where the ball was fielded
hardnessmlb_hit_dataStringAmount of hard contact on a hit
soft, medium, hard
launch_anglemlb_hit_dataDecimalVertical angle relative to the horizon at which a hit was launched

Available with Statcast only
launch_speedmlb_hit_dataDecimalMeasured speed of a hit ball

Available with Statcast only
locationmlb_hit_dataIntegerPositional number (1-9) of the player nearest to a hit ball location. Please see our FAQ for fielding position numbers and definitions

Available with Statcast only
total_distancemlb_hit_dataIntegerTotal distance a hit ball traveled (in feet)

Available with Statcast only
trajectorymlb_hit_dataStringTrajectory of a batted ball into the field of play
ex. ground_ball, fly_ball, line_drive,'popup'
hit_locationpitchIntegerNumber code of hit ball location (1-35). Please see our FAQ for a diagram of our field and its corresponding hit location zones
hit_typepitchStringType of hit
GB(Ground ball), FB(Fly ball), LD(Line drive), PU(Popup)
Play-By-Play - Inning:
AttributeParent ElementTypeDescription
typeinning_halfStringIndicates top or bottom inning half
T, B
numberinningIntegerNumber of an inning
sequenceinningIntegerSequential number of an inning
Play-By-Play - Pitch:
AttributeParent ElementTypeDescription
idpitchGUIDUnique ID of a pitch
ex. 37d94861-7ce4-4547-802c-f97f93e434b4
pitch_xpitcherIntegerNumber as a percentage distance from the center of the strike zone, in positive or negative values from approximately -300% to positive 300%
ex. 70
pitch_ypitcherIntegerNumber as a percentage distance from the center of the strike zone, in positive or negative values from approximately -200% to positive 200%
ex. -95
created_atpitchdateTimeTimestamp of a thrown pitch
ex. 2022-09-25T20:10:00+00:00
pitch_countpitcherIntegerNumber of pitches for a pitcher in a game
officialpitchBooleanSignifies whether the API is ingesting data directly from the league at the time of the event.

For true, entry_mode=Ingest. For false, entry_mode=LDE.
outcome_idpitchStringID of a pitch outcome on a play. Check our FAQ for a list of valid outcomes and their definitions
referencepitchStringUnique MLBAM ID of a pitch

Available with Statcast only
sequence_numberpitchIntegerSequential number of a pitch in a game
pitch_speedpitcherStringSpeed of a pitch in MPH
ex. 92.0
pitch_typepitcherStringCode for a type of pitch
FA(Fastball), SI(Sinker), CT(Cutter), CU(Curveball), SL(Slider), CH(Changeup), KN(Knuckleball), SP(Splitter), SC(Screwball), FO(Forkball), IB(Intentional Ball), PI(Pitchout), Other
pitch_zonepitcherIntegerNumber corresponding to the pitch strike zone (1-13)
See our FAQ for more detail and a graphic representation
statuspitchStringStatus of a pitch. Can be utilized to determine if a play is or was under review
official, overturned, under review, upheld
updated_atpitchdateTimeTimestamp of a pitch update
ex. 2022-09-25T20:25:14+00:00
end_timewall_clockdateTimeTimestamp of an event end time
ex. 2022-09-25T23:00:45+00:00
start_timewall_clockdateTimeTimestamp of an event start time
ex. 2022-09-25T23:00:45+00:00
Play-By-Play - Pitcher:
AttributeParent ElementTypeDescription
first_namepitcherStringFirst name of a pitcher
ex. Clayton
full_namepitcherStringFull name of a pitcher
ex. Clayton Kershaw
suffixpitcherStringName suffix of a pitcher
ex. Jr.
pitcher_handpitcherStringHandedness of a pitcher
idpitcherGUIDUnique ID of a player of a pitcher
ex. ea1a2111-44cc-4996-babb-9439465e6760
jersey_numberpitcherIntegerNumber of a pitcher's jersey
last_namepitcherStringLast name of a pitcher
ex. Kershaw
preferred_namepitcherStringPreferred name of a pitcher
ex. Clayton
Play-By-Play - Play Flags:
AttributeParent ElementTypeDescription
is_ab_overflagsBooleanIndicates an at bat has ended on a pitch
is_buntflagsBooleanIndicates a bunt play
is_double_playflagsBooleanIndicates a double play
is_passed_ballflagsBooleanIndicates a passed ball
is_hitflagsBooleanIndicates a hit
is_triple_playflagsBooleanIndicates a triple play
is_wild_pitchflagsBooleanIndicates a wild pitch
Play-By-Play - Steal:
AttributeParent ElementTypeDescription
created_atstealdateTimeTimestamp of a steal attempt
ex. 2022-09-25T20:10:00+00:00
idstealGUIDUnique ID of a steal attempt
ex. bebe4b5d-970a-40f4-bfa5-05a9a38eac4a
officialstealBooleanSignifies whether the API is ingesting data directly from the league at the time of the event.

For true, entry_mode=Ingest. For false, entry_mode=LDE.
sequence_numberstealIntegerSequence number of an event within a game
statusstealStringStatus of a pitch/play. Can be utilized to determine if a play is or was under review
official, overturned, under review, upheld
updated_atstealdateTimeTimestamp of a steal attempt update
ex. 2022-09-25T20:25:14+00:00
Play-By-Play - Warming Up:
AttributeParent ElementTypeDescription
first_namewarming_upStringFirst name of a pitcher warming up in the bullpen
ex. Brusdar
full_namewarming_upStringFull name of a pitcher warming up in the bullpen
ex. Brusdar Graterol
suffixwarming_upStringName suffix of a pitcher warming up in the bullpen
ex. Jr.
idwarming_upGUIDUnique ID of a warming up event
ex. ea1a2111-44cc-4996-babb-9439465e6760
player_idwarming_upGUIDUnique ID of a player of a pitcher warming up in the bullpen
ex. 43862b88-c119-4625-b138-f3c5ea1b8b06
jersey_numberwarming_upIntegerNumber of a pitcher's jersey
last_namewarming_upStringLast name of a pitcher warming up in the bullpen
ex. Graterol
preferred_namewarming_upStringPreferred name of a pitcher warming up in the bullpen
ex. Brusdar
team_idwarming_upGUIDUnique team ID of a pitcher warming up in the bullpen
ex. 75729d34-bca7-4a0f-b3df-6f26c6ad3719
Play-By-Play - Pitch Data:
AttributeParent ElementTypeDescription
break_anglebreaksDecimalDegrees clockwise (batter’s view) that the plane ofthe pitch deviates from the vertical

Available with Statcast only
break_lengthbreaksDecimalMax distance (in inches) that the pitch separates from the straight line between pitch start and pitch end

Available with Statcast only
break_ybreaksDecimalDistance (in feet) from home plate where the break is greatest

Available with Statcast only
spin_directionbreaksDecimalThe axis of rotation for the ball at release given as an angle that reflects how the spin will influence the ball trajectory. Pure back-spin is 180 degrees, pure side-spin that puts the ball to the 1b side is 90 degrees, pure-side spin that pulls the ball to the 3b side is 270 degrees, and pure top-spin is 0 or 360 degrees

Available with Statcast only
spin_ratebreaksDecimalRate of spin on the ball (in RPMs) after it was released by pitcher.

Available with Statcast only
codemlb_pitch_dataStringTwo-letter code for a type of pitch.
FA, FF, FT, FC, SI, FS, FO, CH, SC, SL, CU, CS, KC, SU, FL, GY, KN, EP, IN, PO, AB, AS, NP, UN

See FAQ for pitch code descriptions
a_xcoordinatesDecimalBall acceleration on the x axis

Available with Statcast only
a_ycoordinatesDecimalBall acceleration on the y axis

Available with Statcast only
a_zcoordinatesDecimalBall acceleration on the z axis

Available with Statcast only
p_xcoordinatesDecimalHorizontal position in feet of the ball as it crosses the front axis of home plate

Available with Statcast only
p_zcoordinatesDecimalVertical position in feet above home plate of the ball as it crosses the front axis of home plate

Available with Statcast only
pfx_xcoordinatesDecimalHorizontal movement of the ball in inches

Available with Statcast only
pfx_zcoordinatesDecimalVertical movement of the ball in inches

Available with Statcast only
v_x0coordinatesDecimalVelocity of the ball from the x axis

Available with Statcast only
v_y0coordinatesDecimalVelocity of the ball from the y axis; this is negative because 0,0,0 is behind the batter and the ball travels from pitcher mound towards 0,0,0

Available with Statcast only
v_z0coordinatesDecimalVelocity of the ball from the z axis

Available with Statcast only
xcoordinatesDecimalX coordinate where a pitch crossed the front of home plate
x0coordinatesDecimalCoordinate location of the ball at the point it was released from the pitchers hand on the x axis (time = 0)

Available with Statcast only
ycoordinatesDecimalY coordinate where a pitch crossed the front of home plate
y0coordinatesDecimalCoordinate location of the ball at the point it was released from the pitchers hand on the y axis (time = 0)

Available with Statcast only
z0coordinatesDecimalCoordinate location of the ball at the point it was released from the pitchers hand on the z axis (time = 0)

Available with Statcast only
descriptionmlb_pitch_dataStringText description of a pitch
ex. Curveball
end_speedmlb_pitch_dataDecimalSpeed in MPH of the ball as it crosses the front edge of home plate (0,0 in the x axis)

Available with Statcast only
extensionmlb_pitch_dataDecimalMeasure of the true release point from pitching rubber - distance in feet closer to home plate than the 60.5 ft from pitching rubber to home

Available with Statcast only
plate_timemlb_pitch_dataDecimalTime from pitchers release until the ball is projected to reach the back tip of home plate or struck by the bat

Available with Statcast only
start_speedmlb_pitch_dataDecimalSpeed in MPH of the ball at 50 feet in front of homeplate
strike_zone_bottommlb_pitch_dataDecimalDistance in inches from ground to bottom of batter strike zone
strike_zone_topmlb_pitch_dataDecimalDistance in inches from ground to top of batter strike zone
Venue:
AttributeParent ElementTypeDescription
addressvenueStringAddress of a venue
ex. 1000 Vin Scully Avenue
capacityvenueStringCapacity of a venue
ex. 56000
cityvenueStringCity of a venue
ex. Los Angeles
countryvenueStringCountry of a venue
ex. USA
field_orientationvenueStringField orientation of a venue
ex. NE
idvenueGUIDUnique ID of a venue
ex. 66a19c3d-24fe-477d-bee7-c6ef1b98352f
latlocationDecimalLatitude of a venue
ex. 34.0745409
lnglocationDecimalLongitude of a venue
ex. -118.2408881
marketvenueStringMarket of a venue
ex. Los Angeles
namevenueStringName of a venue
ex. Dodger Stadium
stadium_typevenueStringType of a venue
ex. outdoor
statevenueStringState of a venue
ex. CA
surfacevenueStringSurface type of a venue
ex. grass
time_zonevenueStringTime zone of a venue
ex. US/Central
zipvenueIntegerZIP code of a venue
ex. 90012
Language
Authorization
Query
Click Try It! to start a request and see the response here!