Docs
Coverage MatrixDocumentationChange LogLog InContact Us
Docs

Push Events

MLB Push Events provides detailed, real-time information on every game event.

Syntax

https://api.sportradar.com/mlb/{access_level}/stream/en/events/subscribe?api_key={your_api_key}

Parameters

ParameterDescription
access_levelDefines the access level of your API key

production, trial
your_api_keyYour API key

Optional Query String Parameters

By default, a Push feed will provide all data available for all in progress games. If needed, you can filter the data returned by including query strings.

Optional query string parameters must be added after your API key with an ampersand (&). If you are filtering for more than one result, separate the results with a comma (,) and no spaces.

ParameterDescription
event_categoryEvent category

stolenbase, runneradvancement, hit, single, double, triple, homerun, strikeout, walk, out, double_play, triple_play, atbatover, runscored, or halfover

Example: event_category=hit
event_typeEvent type

atbat, pitch, steal, lineup, warmup, event_over

Example: event_type=atbat_id
inning_halfInning half (top or bottom)

T, B

Example: inning_half=T
inningInning expressed as an integer

Example: inning=9
matchGame id

Example: match=sd:match:7779b2fe-70ad-4823-8c6d-9e2453576e2a
statusGame status

inprogress, created

Example: status=inprogress
teamTeam id

Example: team=sd:team:25507be1-6a68-4267-bd82-e097d94b359b


Code Samples

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api.sportradar.com/mlb/trial/stream/en/events/subscribe?api_key={your_api_key}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
import requests
import json

r = requests.get("https://api.sportradar.com/mlb/trial/stream/en/events/subscribe",
    params = {'api_key': 'your_api_key'},
    allow_redirects=False)

redirect_url = r.headers['Location']
r = requests.get(redirect_url, stream=True)

for line in r.iter_lines():
    # filter out keep-alive new lines
    if line:
        decoded_line = line.decode('utf-8')
        print(json.loads(decoded_line))
curl -L GET 'api.sportradar.com/mlb/trial/stream/en/events/subscribe?api_key={your_api_key}'

Samples with Query String Params

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api.sportradar.com/mlb/trial/stream/en/events/subscribe?api_key={your_api_key}&status=inprogress&match=sd:match:7779b2fe-70ad-4823-8c6d-9e2453576e2a")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
import requests
import json

r = requests.get("https://api.sportradar.com/mlb/trial/stream/en/events/subscribe",
    params = {'api_key': 'your_api_key', 'status': 'inprogress', 'match': 'sd:match:7779b2fe-70ad-4823-8c6d-9e2453576e2a'},
    allow_redirects=False)

redirect_url = r.headers['Location']
r = requests.get(redirect_url, stream=True)

for line in r.iter_lines():
    # filter out keep-alive new lines
    if line:
        decoded_line = line.decode('utf-8')
        print(json.loads(decoded_line))

curl -L GET 'api.sportradar.com/mlb/trial/stream/en/events/subscribe?api_key={your_api_key}&status=inprogress&match=sd:match:7779b2fe-70ad-4823-8c6d-9e2453576e2a'


Response Samples

The above commands return json like this.


Enforced Strikes

See the below samples for behavior of enforced strikes or balls due to time clock violations.

{
   "payload":{
      "game":{
         "id":"1506ae41-f6e1-4d94-bd5a-5adcf6a3a967",
         "status":"closed",
         "coverage":"full",
         "game_number":1,
         "double_header":false,
         "entry_mode":"STOMP",
         "mlb_id":"718777",
         "day_night":"D",
         "scheduled":"2023-03-30T18:20:00+00:00",
         "home_team":"55714da8-fcaf-4574-8443-59bfb511a524",
         "away_team":"dcfd5266-00ce-442c-bc09-264cd20cf455",
         "home":{
            "name":"Cubs",
            "market":"Chicago",
            "abbr":"CHC",
            "id":"55714da8-fcaf-4574-8443-59bfb511a524",
            "runs":4,
            "hits":6,
            "errors":1
         },
         "away":{
            "name":"Brewers",
            "market":"Milwaukee",
            "abbr":"MIL",
            "id":"dcfd5266-00ce-442c-bc09-264cd20cf455",
            "runs":0,
            "hits":4,
            "errors":1
         }
      },
      "event":{
         "id":"40ce37f0-24fe-4abe-8d9c-bee4b6167102",
         "type":"pitch",
         "inning":3,
         "inning_half":"T",
         "sequence_number":98,
         "sequence":1680202550928,
         "hitter_id":"42cb5171-ffa3-4600-9c41-dbc3805206ea",
         "atbat_id":"894a5399-585b-4966-93a1-8370a3c3e24f",
         "outcome_id":"bAB",
         "status":"official",
         "created_at":"2023-03-30T18:55:50+00:00",
         "updated_at":"2023-04-04T23:24:25+00:00",
         "wall_clock":{
            "start_time":"2023-03-30T18:55:38+00:00",
            "end_time":"2023-03-30T18:55:45+00:00"
         },
         "flags":{
            "is_ab_over":false,
            "is_bunt":false,
            "is_bunt_shown":false,
            "is_hit":false,
            "is_wild_pitch":false,
            "is_passed_ball":false,
            "is_double_play":false,
            "is_triple_play":false
         },
         "count":{
            "balls":2,
            "strikes":2,
            "outs":0,
            "pitch_count":3
         },
         "pitcher":{
            "id":"cc86d4d3-1618-415e-b7fc-a303f3b8dd6f",
            "pitcher_hand":"R",
            "hitter_hand":"L",
            "pitch_count":39,
            "last_name":"Stroman",
            "first_name":"Marcus",
            "preferred_name":"Marcus",
            "jersey_number":"0"
         },
         "hitter":{
            "last_name":"Yelich",
            "first_name":"Christian",
            "preferred_name":"Christian",
            "jersey_number":"22",
            "id":"42cb5171-ffa3-4600-9c41-dbc3805206ea"
         },
         "runners":[
            "\\"{
               "id":"45d9ee07-705d-4d91-8131-264ab0cc8af4",
               "starting_base":2,
               "ending_base":2,
               "outcome_id":"",
               "out":false,
               "last_name":"Turang",
               "first_name":"Brice",
               "preferred_name":"Brice",
               "jersey_number":"0"
            }
         ]
      }
   },
   "locale":"en",
   "metadata":{
      "league":"MLB",
      "match":"sd:match:1506ae41-f6e1-4d94-bd5a-5adcf6a3a967",
      "status":"closed",
      "inning":3,
      "inning_half":"T",
      "event_type":"pitch",
      "event_category":"pitch",
      "locale":"en",
      "operation":"update",
      "version":"v6.5"
   }
}{
   "payload":{
      "game":{
         "id":"db073916-8fae-4672-a160-061b2892c17c",
         "status":"inprogress",
         "coverage":"full",
         "game_number":1,
         "double_header":false,
         "entry_mode":"STOMP",
         "mlb_id":"718710",
         "day_night":"N",
         "scheduled":"2023-04-04T23:05:00+00:00",
         "home_team":"a09ec676-f887-43dc-bbb3-cf4bbaee9a18",
         "away_team":"2142e1ba-3b40-445c-b8bb-f1f8b1054220",
         "home":{
            "name":"Yankees",
            "market":"New York",
            "abbr":"NYY",
            "id":"a09ec676-f887-43dc-bbb3-cf4bbaee9a18",
            "runs":0,
            "hits":0,
            "errors":0
         },
         "away":{
            "name":"Phillies",
            "market":"Philadelphia",
            "abbr":"PHI",
            "id":"2142e1ba-3b40-445c-b8bb-f1f8b1054220",
            "runs":1,
            "hits":1,
            "errors":0
         }
      },
      "event":{
         "id":"3457862e-9483-4430-9a0e-b75e92dda03c",
         "type":"pitch",
         "inning":2,
         "inning_half":"T",
         "sequence_number":44,
         "sequence":1680650663534,
         "hitter_id":"169ed0b1-e34b-4f4b-925b-f3288f24a5e7",
         "atbat_id":"6ae2a923-ca55-464e-ad8c-3b054cb2617d",
         "outcome_id":"kKS",
         "status":"official",
         "created_at":"2023-04-04T23:24:23+00:00",
         "updated_at":"2023-04-04T23:24:36+00:00",
         "wall_clock":{
            "start_time":"2023-04-04T23:24:16+00:00",
            "end_time":"2023-04-04T23:24:30+00:00"
         },
         "flags":{
            "is_ab_over":false,
            "is_bunt":false,
            "is_bunt_shown":false,
            "is_hit":false,
            "is_wild_pitch":false,
            "is_passed_ball":false,
            "is_double_play":false,
            "is_triple_play":false
         },
         "count":{
            "balls":0,
            "strikes":2,
            "outs":0,
            "pitch_count":2
         },
         "pitcher":{
            "pitch_type":"SI",
            "pitch_speed":91.5,
            "pitch_zone":12,
            "pitch_x":17,
            "pitch_y":-204,
            "id":"f7967ff6-16ea-408f-aa90-7d4df691679f",
            "pitcher_hand":"R",
            "hitter_hand":"R",
            "pitch_count":16,
            "last_name":"Germán",
            "first_name":"Domingo",
            "preferred_name":"Domingo",
            "jersey_number":"0"
         },
         "hitter":{
            "last_name":"Castellanos",
            "first_name":"Nicholas",
            "preferred_name":"Nick",
            "jersey_number":"8",
            "id":"169ed0b1-e34b-4f4b-925b-f3288f24a5e7"
         }
      }
   },
   "locale":"en",
   "metadata":{
      "league":"MLB",
      "match":"sd:match:db073916-8fae-4672-a160-061b2892c17c",
      "status":"inprogress",
      "inning":2,
      "inning_half":"T",
      "event_type":"pitch",
      "event_category":"pitch",
      "locale":"en",
      "operation":"update",
      "version":"v6.5"
   }
}
{
   "payload":{
      "game":{
         "id":"72c21aec-5c0f-49d6-b8c5-9037ab1bd8dd",
         "status":"closed",
         "coverage":"full",
         "game_number":1,
         "double_header":false,
         "entry_mode":"STOMP",
         "mlb_id":"718717",
         "day_night":"D",
         "scheduled":"2023-04-04T20:10:00+00:00",
         "home_team":"d52d5339-cbdd-43f3-9dfa-a42fd588b9a3",
         "away_team":"25507be1-6a68-4267-bd82-e097d94b359b",
         "home":{
            "name":"Padres",
            "market":"San Diego",
            "abbr":"SD",
            "id":"d52d5339-cbdd-43f3-9dfa-a42fd588b9a3",
            "runs":6,
            "hits":10,
            "errors":1
         },
         "away":{
            "name":"Diamondbacks",
            "market":"Arizona",
            "abbr":"ARI",
            "id":"25507be1-6a68-4267-bd82-e097d94b359b",
            "runs":8,
            "hits":9,
            "errors":1
         }
      },
      "event":{
         "id":"fc41c294-4815-436d-bf6c-6f1d2a670c5a",
         "type":"pitch",
         "inning":1,
         "inning_half":"B",
         "sequence_number":38,
         "sequence":1680639905014,
         "hitter_id":"3bb4a60b-953e-4bef-8b25-c6f07d54eddf",
         "atbat_id":"1e5c5ed6-4f6a-4b7f-9892-1523b476aed8",
         "outcome_id":"kAK",
         "status":"official",
         "created_at":"2023-04-04T20:25:05+00:00",
         "updated_at":"2023-04-04T23:30:19+00:00",
         "wall_clock":{
            "start_time":"2023-04-04T20:23:46+00:00",
            "end_time":"2023-04-04T20:23:51+00:00"
         },
         "flags":{
            "is_ab_over":true,
            "is_bunt":false,
            "is_bunt_shown":false,
            "is_hit":false,
            "is_wild_pitch":false,
            "is_passed_ball":false,
            "is_double_play":false,
            "is_triple_play":false
         },
         "count":{
            "balls":3,
            "strikes":3,
            "outs":3,
            "pitch_count":5
         },
         "pitcher":{
            "id":"e488a3a6-4673-4e5d-befe-6d5ab57b0b8e",
            "pitcher_hand":"R",
            "hitter_hand":"R",
            "pitch_count":12,
            "last_name":"Gallen",
            "first_name":"Zachary",
            "preferred_name":"Zac",
            "jersey_number":"23"
         },
         "hitter":{
            "last_name":"Machado",
            "first_name":"Manuel",
            "preferred_name":"Manny",
            "jersey_number":"13",
            "id":"3bb4a60b-953e-4bef-8b25-c6f07d54eddf"
         },
         "fielders":[
            "\\"{
               "id":"c5b9d056-d030-4640-9e4a-a83599984388",
               "type":"putout",
               "sequence":1,
               "last_name":"Herrera",
               "first_name":"Jose",
               "preferred_name":"Jose",
               "jersey_number":"11"
            }
         ]
      }
   },
   "locale":"en",
   "metadata":{
      "league":"MLB",
      "match":"sd:match:72c21aec-5c0f-49d6-b8c5-9037ab1bd8dd",
      "status":"closed",
      "inning":1,
      "inning_half":"B",
      "event_type":"pitch",
      "event_category":"pitch,strikeout,out,atbatover,halfover",
      "locale":"en",
      "operation":"update",
      "version":"v6.5"
   }
}


Data Points

Metadata:
AttributeParent ElementTypeDescription
event_categorymetadataStringCategory of an event
ex. lineup,starters,pitching
event_typemetadataStringType of an event
ex. lineup
leaguemetadataStringAlias of a league
ex. MLB
localemetadataStringLanguage code
ex. en (English)
matchmetadataGUIDUnique ID of a game
ex. sd:match:30ad883f-aeaf-4e6b-9fd9-a1cc0b6c4679
operationmetadataStringOperation of an update
create, update, delete
statusmetadataStringThe status of a game
scheduled, inprogress, complete, closed, wdelay, fdelay, odelay, canceled, unnecessary, if-necessary, postponed, suspended, maintenance
teammetadataGUIDUnique ID of a team
ex. sd:team:575c19b7-4052-41c2-9f0a-1c5813d02f99
versionmetadataStringVersion of the API
ex. v6.5
Boxscore:
AttributeParent ElementTypeDescription
abbrawayStringAbbreviation of the away team
ex. MIN (Minnesota)
errorsawayIntegerNumber of errors for the away team
hitsawayIntegerNumber of hits for the away team
idawayGUIDUnique ID of the away team
ex. 29dd9a87-5bcc-4774-80c3-7f50d985068b
idaway-probable_pitcherGUIDUnique ID of the away team's probable pitcher
ex. 515af486-d938-4cb6-90e4-943323a5737c
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
abbrhomeStringAbbreviation of the home team
ex. CLE (Cleveland)
errorshomeIntegerNumber of errors for the home team
hitshomeIntegerNumber of hits for the home team
idhomeGUIDUnique ID of the home team
ex. 29dd9a87-5bcc-4774-80c3-7f50d985068b
idhome-probable_pitcherGUIDUnique ID of the home team's probable pitcher
ex. 515af486-d938-4cb6-90e4-943323a5737c
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
abbrteamStringAbbreviation of a team
ex. TB (Tampa Bay)
idteamGUIDUnique ID of a team
ex. bdc11650-6f74-49c4-875e-778aeb7632d9
marketteamStringMarket name of a team
ex. Tampa Bay
nameteamStringTeam name
ex. Rays
Game:
AttributeParent ElementTypeDescription
away_teamgameGUIDUnique ID of the away team
ex. 29dd9a87-5bcc-4774-80c3-7f50d985068b
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
referencegameStringUnique MLBAM ID of a game
scheduledgamedateTimeScheduled date and time of a game
ex. 2022-09-25T20:10:00+00:00
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
Lineup:
AttributeParent ElementTypeDescription
orderlineupsIntegerBatting 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-12).

See our FAQ for a list of position definitions
idlineupGUIDUnique ID of a lineup entry
ex. 616d0907-26f1-4adf-875f-c0928d6d1b22
inning_halflineupStringInning half of a player entering the game
T, B
inninglineupsIntegerInning of a player entering the game
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
sequencelineupIntegerSequence number of a lineup event
team_ideventGUIDUnique 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_handeventStringHandedness of a hitter
hitter_ideventGUIDUnique 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 hitter
ex. Mookie
atbat_ideventGUIDUnique 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_ideventGUIDUnique 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
sequenceeventUNIXSequence number of an event
typeeventStringType of an event
ex. atbat
created_ateventdateTimeTimestamp of an event creation time
ex. 2022-09-25T23:00:45+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
updated_ateventdateTimeTimestamp of an event update time
ex. 2022-09-25T23:00:45+00:00
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
outrunnersBooleanSignifies the runner was out on a play
outcome_idrunnersStringID 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.
idrunnersGUIDUnique ID of a player of a runner
ex. ea1a2111-44cc-4996-babb-9439465e6760
preferred_namerunnersStringPreferred name of a runner
ex. Mookie
starting_baserunnersIntegerRunner's base at the start of a play
created_atrunner_placeddateTimeTimestamp of a runner placed event
ex. 2022-09-25T20:10:00+00:00
idrunner_placedGUIDUnique ID of a runner placed event (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 - Errors:
AttributeParent ElementTypeDescription
first_nameerrorsStringFirst name of a player committing an error
ex. Gavin
full_nameerrorsStringFull name of a player committing an error
ex. Gavin Lux
suffixerrorsStringName suffix of a player committing an error
ex. Jr.
iderrorsGUIDUnique ID of a player of a player committing an error
ex. ea1a2111-44cc-4996-babb-9439465e6760
jersey_numbererrorsIntegerJersey number a player committing an error
last_nameerrorsStringLast name of a player committing an error
ex. Lux
preferred_nameerrorsStringPreferred name of a player committing an error
ex. Gavin
typeerrorsStringType of fielding error
fielding, throwing, interference
Play-By-Play - Fielding:
AttributeParent ElementTypeDescription
first_namefieldersStringFirst name of a player recording an assist
ex. Gavin
full_namefieldersStringFull name of a player recording an assist
ex. Gavin Lux
suffixfieldersStringName suffix of a player recording an assist
ex. Jr.
idfieldersGUIDUnique ID of a player of a player recording an assist
ex. ea1a2111-44cc-4996-babb-9439465e6760
jersey_numberfieldersIntegerJersey number a player recording an assist
last_namefieldersStringLast name of a player recording an assist
ex. Lux
preferred_namefieldersStringPreferred name of a player recording an assist
ex. Gavin
sequencefieldersIntegerSequential number of an assist
first_namefieldersStringFirst name of a player recording a putout
ex. Byron
full_namefieldersStringFull name of a player recording a putout
ex. Byron Buxton
suffixfieldersStringName suffix of a player recording a putout
ex. Jr.
idfieldersGUIDUnique ID of a player recording a putout
ex. ea1a2111-44cc-4996-babb-9439465e6760
jersey_numberfieldersIntegerJersey number a player recording a putout
last_namefieldersStringLast name of a player recording a putout
ex. Buxton
preferred_namefieldersStringPreferred name of a player recording a putout
ex. Gavin
sequencefieldersIntegerSequential number of a putout
Play-By-Play - Hit Data:
AttributeParent ElementTypeDescription
hit_locationeventIntegerNumber code of hit ball location (1-35). Please see our FAQ for a diagram of our field and its corresponding hit location zones
hit_typeeventStringType of hit
GB(Ground ball), FB(Fly ball), LD(Line drive), PU(Popup)
Play-By-Play - Inning:
AttributeParent ElementTypeDescription
inning_halfevent / metadataStringIndicates top or bottom inning half
T, B
inningevent / lineup / metadataIntegerNumber of an inning
sequence_numbereventIntegerSequential 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
statuseventStringStatus of a pitch. Can be utilized to determine if a play is or was under review
official, overturned, under review, upheld
updated_ateventdateTimeTimestamp of a pitch update
ex. 2022-09-25T20:25:14+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_up / eventStringFirst name of a pitcher warming up in the bullpen
ex. Brusdar
full_namewarming_up / eventStringFull name of a pitcher warming up in the bullpen
ex. Brusdar Graterol
suffixwarming_up / eventStringName suffix of a pitcher warming up in the bullpen
ex. Jr.
idwarming_up / eventGUIDUnique ID of a warming up event
ex. ea1a2111-44cc-4996-babb-9439465e6760
player_idwarming_up / eventGUIDUnique ID of a player of a pitcher warming up in the bullpen
ex. 43862b88-c119-4625-b138-f3c5ea1b8b06
jersey_numberwarming_up / eventIntegerNumber of a pitcher's jersey
last_namewarming_up / eventStringLast name of a pitcher warming up in the bullpen
ex. Graterol
preferred_namewarming_up / eventStringPreferred name of a pitcher warming up in the bullpen
ex. Brusdar
team_idwarming_up / eventGUIDUnique team ID of a pitcher warming up in the bullpen
ex. 75729d34-bca7-4a0f-b3df-6f26c6ad3719