Syntax

https://api.sportradar.com/nba/{access_level}/stream/{language_code}/events/subscribe

Parameters

Parameter	Description
`access_level`	Defines the access level of your API key `production`, `trial`
`language_code`	Optional code for supported languages `en` (English)

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.

Each query string parameter can be added with a preceding ampersand (&).

Parameter	Description
`event_category`	Event category Example: `event_category=shot`
`event_type`	Event type Example: `event_type=stoppage`
`match`	Match id Example: `match=sd:match:76b2e680-7da7-461f-95ad-e7c34dbc4c56`
`players`	Player id Example: `players=sd:player:c1ff3e58-266f-4183-9fa1-d7c914cf4886`
`status`	Game status `inprogress`, `created` Example: `status=inprogress`
`team`	Team id Example: `team=sd:team:583eca2f-fb46-11e1-82cb-f4ce4684ea4c`

Code Samples

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

url = URI("https://api.sportradar.com/nba/trial/stream/en/events/subscribe")

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)
request["x-api-key"] = "{your_api_key}"  # Replace with your actual key

response = http.request(request)
puts response.read_body

import requests
import json

headers = {
    'x-api-key': 'your_api_key'  # Replace with your actual key
}

r = requests.get(
    "https://api.sportradar.com/nba/trial/stream/en/events/subscribe",
    headers=headers,
    allow_redirects=False
)

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

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 -X GET 'https://api.sportradar.com/nba/trial/stream/en/events/subscribe' \
  -H 'x-api-key: {your_api_key}'

Samples with Query String Params

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

url = URI("https://api.sportradar.com/nba/trial/stream/en/events/subscribe?&status=inprogress&match=sd:match:76b2e680-7da7-461f-95ad-e7c34dbc4c56")

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)
request["x-api-key"] = "{your_api_key}"  # Replace with your actual key

response = http.request(request)
puts response.read_body

import requests
import json

headers = {
    'x-api-key': 'your_api_key'  # Replace with your actual key
}

r = requests.get("https://api.sportradar.com/nba/trial/stream/en/events/subscribe",
    params = {'status': 'inprogress', 'match': 'sd:match:76b2e680-7da7-461f-95ad-e7c34dbc4c56'},
    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 -X GET 'api.sportradar.com/nba/trial/stream/en/events/subscribe?&status=inprogress&match=sd:match:76b2e680-7da7-461f-95ad-e7c34dbc4c56'
  -H 'x-api-key: {your_api_key}'

Response Sample

The above commands return json like this.

Simulations

Check out our Simulations to replay actual games at any time, on your own schedule. Push simulations are available as well.

Data Points

Game

Attribute	Parent Element	Type	Description
`coverage`	`game`	String	Birthplace of a prospect Coverage level of a game `full`, `extended_boxscore`
`id`	`game`	GUID	Unique ID of a game ex. `1f730a9a-8221-48ff-a259-ac2103fb58b0`
`reference`	`game`	String	League reference ID of a game ex. `1610612758`
`sr_id`	`game`	GUID	Unique Sportradar ID of a game ex. `sr:match:35431817`
`status`	`game`	String	The status of a game `scheduled`, `created`, `inprogress`, `halftime`, `complete`, `closed`, `cancelled`, `delayed`, `postponed`, `time-tbd`, `if-necessary`, `unnecessary` Please see ourFAQ section for a list of game status definitions
`title`	`game`	String	Title of a game ex. `Game 3`
`scheduled`	`game`	dateTime	Scheduled date and time of a game ex. `2025-10-21T23:30:00+00:00`
`away`	`game` - `time_zones`	String	Time zone of the away team ex. `US/Pacific`
`home`	`game` - `time_zones`	String	Time zone of the home team ex. `US/Eastern`
`venue`	`game` - `time_zones`	String	Time zone of the venue ex. `US/Eastern`

Metadata

Attribute	Parent Element	Type	Description
`event_category`	`metadata`	String	Category of an event ex. `lineupchange` or `shot`
`event_type`	`metadata`	String	Type of an event ex. `threepointmiss` or `rebound`
`league`	`metadata`	String	Alias of a league ex. `NBA`
`locale`	`metadata`	String	Language code ex. `en` (English)
`match`	`metadata`	GUID	Unique ID of a game ex. `sd:match:d8539eb6-3e27-40c8-906f-9cd1736321d8`
`operation`	`metadata`	String	Operation of an update `update`, `delete`
`players`	`metadata`	GUID	Unique ID(s) of players associated with an event ex. `sd:player:68b7aac9-02fd-4bd8-b10c-6702d2c5eb98,sd:player:ffa9a64f-d624-4033-bd23-59dcfd805175`
`status`	`metadata`	String	The status of a game `scheduled`, `created`, `inprogress`, `halftime`, `complete`, `closed`, `cancelled`, `delayed`, `postponed`, `time-tbd`, `if-necessary`, `unnecessary` Please see ourFAQ section for a list of game status definitions
`team`	`metadata`	GUID	Unique ID(s) of team(s) associated with an event ex. `sd:team:583ecefd-fb46-11e1-82cb-f4ce4684ea4c,sr:team:3410`
`version`	`metadata`	String	Version of the API ex. `v7`

Play-by-Play - Attribution & Possession

Attribution is the team associated with the play-by-play event (i.e. the statistic associated with it). Possession is the team who currently has the possession of the ball as a result of that play-by-play event.

Attribute	Parent Element	Type	Description
`id`	`event` - `attribution`	GUID	Unique ID of a team ex. `583ed0ac-fb46-11e1-82cb-f4ce4684ea4c`
`market`	`event` - `attribution`	String	Market name of a team ex. `Sacramento`
`name`	`event` - `attribution`	String	Team name ex. `Kings`
`reference`	`event` - `attribution`	String	League reference ID of a team ex. `1610612750`
`sr_id`	`event` - `attribution`	GUID	Unique Sportradar ID of a team ex. `sr:team:3415`
`team_basket`	`event` - `attribution`	String	The basket the offensive team is shooting at in the arena. Direction is based on the TV broadcast's perspective. `left`, `right`
`id`	`event` - `possession`	GUID	Unique ID of a team ex. `583ed0ac-fb46-11e1-82cb-f4ce4684ea4c`
`market`	`event` - `possession`	String	Market name of a team ex. `Sacramento`
`name`	`event` - `possession`	String	Team name ex. `Kings`
`sr_id`	`event` - `possession`	GUID	Unique Sportradar ID of a team ex. `sr:team:3415`

Play-by-Play - Home/Away Teams

Attribute	Parent Element	Type	Description
`bonus`	`game` - `away`	Boolean	Signifies a team is in the bonus
`points`	`game` - `away`	Integer	Total points for the away team
`id`	`game` - `away`	GUID	Unique ID of the away team ex. `583ed0ac-fb46-11e1-82cb-f4ce4684ea4c`
`market`	`game` - `away`	String	Market name of the away team ex. `Sacramento`
`name`	`game` - `away`	String	Away team name ex. `Kings`
`reference`	`game` - `away`	String	League reference ID of the away team ex. `1610612750`
`remaining_timeouts`	`game` - `away`	Integer	Remaining timeouts for the away team
`sr_id`	`game` - `away`	GUID	Unique Sportradar ID of the away team ex. `sr:team:3415`
`bonus`	`game` - `home`	Boolean	Signifies a team is in the bonus
`points`	`game` - `home`	Integer	Total points for the home team
`id`	`game` - `home`	GUID	Unique ID of the home team ex. `583ed0ac-fb46-11e1-82cb-f4ce4684ea4c`
`market`	`game` - `home`	String	Market name of the home team ex. `Sacramento`
`name`	`game` - `home`	String	Home team name ex. `Kings`
`reference`	`game` - `home`	String	League reference ID of the home team ex. `1610612750`
`remaining_timeouts`	`game` - `home`	Integer	Remaining timeouts for the home team
`sr_id`	`game` - `home`	GUID	Unique Sportradar ID of the home team ex. `sr:team:3415`

Play-by-Play - Event

Attribute	Parent Element	Type	Description
`clock_decimal`	`event`	String	Clock value in decimal form when the game clock is under 1:00. Otherwise it displays the same value as `clock` ex. `00:21.70`
`attempt`	`event`	String	Text description of a free throw attempt ex. `1 of 2` or `2 of 2`
`away_points`	`event`	Integer	Total points for the away team after an event
`clock`	`event`	String	Clock value of an event ex. `12:37`
`description`	`event`	String	Text description of an event ex. `Kevon Looney makes two point jump shot (Klay Thompson assists)`
`event_type`	`event`	String	Type of event ex. `turnover` or `rebound` *See our FAQ for a complete list of types
`home_points`	`event`	Integer	Total points for the home team after an event
`id`	`event`	GUID	Unique ID of an event ex. `b9feda23-c03f-4304-afa4-06d7dc830651`
`action_area`	`event` - `location`	String	Action area of an event `underbasket`, `inthepaint`, `insiderightwing`, `insideright`, `insidecenter`, `insideleft`, `insideleftwing`, `outsideright`, `outsidecenter`, `outsideleft`, `outsideleftwing`, `backcourt` *Please see our FAQ for detailed plot points of our action areas
`coord_x`	`event` - `location`	Integer	X coordinate of an event. The court we use is 1128 by 600; the scale is in inches.
`coord_y`	`event` - `location`	Integer	Y coordinate of an event. The court we use is 1128 by 600; the scale is in inches.
`number`	`event`	Integer	Sequential number of an event in a game
`qualifier`	`event` - `qualifiers` - `qualifier`	String	Additional descriptor of a play-by-play event type. Appears only in JSON format `2ndchance`, `fastbreak`, `fromturnover`, `defensivegoaltending`, `pointsinthepaint`, `fastbreak`, `fromturnover`, `team`, `deadball`, `1freethrow`.`2freethrow`, `mandatory`
`rescinded`	`event`	Boolean	Signifies a technical foul `event_type="technicalfoul"`) has been rescinded by the league when `true`
`sequence`	`event`	Integer	NIX timestamp of the wall clock value. Use this value to help sequence play-by-play events (smallest to largest sequence number). ex. `1678835426293`
`turnover_type`	`event`	String	Type of turnover ex. `Traveling` or `Lane Violation` *See our FAQ for a complete list of types
`created`	`event`	dateTime	Timestamp of the creation of an event ex. `2025-10-21T23:30:00+00:00`
`updated`	`event`	dateTime	Timestamp of the last update to an event ex. `2025-10-21T23:30:00+00:00`
`wall_clock`	`event`	dateTime	Timestamp in UTC when the on-venue statistician began entry of a play-by-play event. ex. `2025-10-21T23:30:00+00:00`

Play-by-Play - Play Participants & Stats

Attribute	Parent Element	Type	Description
`id`	`event` - `statistics` - `team`	GUID	Unique ID of a team ex. `583ed0ac-fb46-11e1-82cb-f4ce4684ea4c`
`market`	`event` - `statistics` - `team`	String	Market name of a team ex. `Sacramento`
`name`	`event` - `statistics` - `team`	String	Team name ex. `Kings`
`reference`	`event` - `statistics` - `team`	String	League reference ID of a team ex. `1610612750`
`sr_id`	`event` - `statistics` - `team`	GUID	Unique Sportradar ID of a team ex. `sr:team:3415`
`full_name`	`event` - `statistics` - `player`	String	Full name of a player ex. `Stephen Curry`
`id`	`event` - `statistics` - `player`	GUID	Unique player ID ex. `8ec91366-faea-4196-bbfd-b8fab7434795`
`jersey_number`	`event` - `statistics` - `player`	Integer	Number of a player's jersey
`reference`	`event` - `statistics` - `player`	String	League reference ID of a player ex. `1626157`
`sr_id`	`event` - `statistics` - `player`	GUID	Unique Sportradar ID of a player ex. `sr:player:608110`
`made`	`event` - `statistics`	Boolean	Signifies a made basket when `true`
`points`	`event` - `statistics`	Integer	Number of points scored for an event
`rebound_type`	`event` - `statistics` - `rebound`	String	Rebound type `defensive`, `offensive`
`shot_distance`	`event` - `statistics`	Decimal	Shot distance in feet from the basket ex. `2.37`
`shot_type`	`event` - `statistics`	String	Shot type `jump shot`, `layup`, `dunk`, `hook`, `tip`
`shot_type_desc`	`event` - `statistics`	String	Text description of a shot type ex. `driving` or `alley-oop` *See our FAQ for a complete list of descriptions
`three_point_shot`	`event` - `statistics`	Boolean	Signifies a 3-point attempt when `true`
`made`	`event` - `statistics` - `freethrow`	Boolean	Signifies a made free throw when `true`
`free_throw_type`	`event` - `statistics` - `freethrow`	String	Type of free throw ex. `regular`, `technical`, `flagrant`, `clear path`

Play-by-Play - On Court Participants

Attribute	Parent Element	Type	Description
`full_name`	`event` - `on_court` - `home` / `away` - `players`	String	Full name of a player ex. `Stephen Curry`
`id`	`event` - `on_court` - `home` / `away` - `players`	GUID	Unique player ID ex. `8ec91366-faea-4196-bbfd-b8fab7434795`
`jersey_number`	`event` - `on_court` - `home` / `away` - `players`	Integer	Number of a player's jersey
`reference`	`event` - `on_court` - `home` / `away` - `players`	String	League reference ID of a player ex. `1626157`
`sr_id`	`event` - `on_court` - `home` / `away` - `players`	GUID	Unique Sportradar ID of a player ex. `sr:player:608110`
`id`	`event` - `on_court` - `home` / `away`	GUID	Unique ID of a team ex. `583ed0ac-fb46-11e1-82cb-f4ce4684ea4c`
`market`	`event` - `on_court` - `home` / `away`	String	Market name of a team ex. `Sacramento`
`name`	`event` - `on_court` - `home` / `away`	String	Team name ex. `Kings`
`reference`	`event` - `on_court` - `home` / `away`	String	League reference ID of a team ex. `1610612750`
`sr_id`	`event` - `on_court` - `home` / `away`	GUID	Unique Sportradar ID of a team ex. `sr:team:3415`

Quarter

Attribute	Parent Element	Type	Description
`id`	`period`	GUID	Unique ID of a quarter ex. `fece1ac0-b703-4478-8a7c-3f27313dec97`
`number`	`period`	Integer	Number of a quarter
`sequence`	`period`	Integer	Sequential number of a quarter
`type`	`period`	GUID	Type of period ex. `quarter`