Simulations
Intro
Our API simulations allow you to replay real games at any time, on your own schedule.
With the replayer, you can:
- Retrieve available game recordings (by league or sport)
- Start a simulation session for a specific game
- Poll REST endpoints to receive data as if the game were live
- Subscribe to Push feeds for real-time streaming updates
AuthenticationSimulations do not require an API key or any authentication.
Key Concepts
- League: A specific competition (e.g., NFL, MLB, NBA)
- Sport: A broader category (currently only supported for Soccer)
- API Identifier: The value used in request paths (
nfl,mlb,soccer, etc.)
Note: Most simulations are league-based. Soccer is currently the only sport-level simulation.
Quick Start
- Fetch available recordings
- Select a
recordingId - Create a session (
sessionId) (REST only) - Request a feed using the replay endpoint
Available Leagues & Sports
Replay simulations are currently available for the following APIs:
Fetch Available Recordings
First, fetch the available recordings by league (NFL, MLB, etc.) or by sport (Soccer).
Recordings by League
curl --location 'https://playback.sportradar.com/graphql' \
--header 'Content-Type: application/json' \
--data '{
"query": "query getRecordings($league: String) { recordings(league: $league) { id scheduled meta league start end title apis { name description formats } } }",
"variables": {
"league": "nfl"
}
}'The above query is specific to the NFL ("league":"nfl"). Click here for all available league parameters.
Quick Access:
Recordings by Sport
curl --location 'https://playback.sportradar.com/graphql' \
--header 'Content-Type: application/json' \
--data '{
"query": "query RecordingsBySport { recordingsBySport(sport: \"soccer\") { id title meta league sport scheduled start end apis { name description apiType formats versions languages } } }"
}'Quick Access:
Select RecordingId
Select a RecordingId for the game you would like to replay.
NFL Response Sample
{
"data": {
"recordings": [
{
"id": "95aa13a0-6538-11ef-9287-d597687b4672",
"title": "Baltimore Ravens AT Kansas City Chiefs",
"meta": {
"gameId": "ebb5f3ac-bb13-4dc4-ab8b-6c65623eac13",
"awayTeam": "6526d38583a47c56303cf1fa",
"homeTeam": "6526d350fb66c7d02dfb8a0f",
"scheduled": "2024-09-06T00:20:00+00:00",
"awayTeamName": "Baltimore Ravens",
"homeTeamName": "Kansas City Chiefs"
},
"league": "nfl",
"scheduled": "2024-09-06T00:20:00.000Z",
"start": 1725583604260,
"end": 1725595789187,
"apis": [
{
"name": "events",
"description": "game events",
"apiType": "push",
"formats": [
"json"
],
"versions": [
"v7"
],
"languages": [
"en"
]
},
{
"name": "statistics",
"description": null,
"apiType": "push",
"formats": [
"json"
],
"versions": [
"v7"
],
"languages": [
"en"
]
},
{
"name": "pulse",
"description": "game push pulse",
"apiType": "push",
"formats": [
"json"
],
"versions": [
"v7"
],
"languages": [
"en"
]
},
{
"name": "boxscore",
"description": "game box score",
"apiType": "rest",
"formats": [
"json",
"xml"
],
"versions": [
"v7"
],
"languages": [
"en"
]
},
{
"name": "game",
"description": "game statistics",
"apiType": "rest",
"formats": [
"json",
"xml"
],
"versions": [
"v7"
],
"languages": [
"en"
]
},
{
"name": "pbp",
"description": "game play by play",
"apiType": "rest",
"formats": [
"json",
"xml"
],
"versions": [
"v7"
],
"languages": [
"en"
]
},
{
"name": "rosters",
"description": "game rosters",
"apiType": "rest",
"formats": [
"json",
"xml"
],
"versions": [
"v7"
],
"languages": [
"en"
]
}
]
}
]
}
}MLB Response Sample
{
"data": {
"recordings": [
{
"id": "fb821410-5fda-11ef-b731-154d1d4eafcf",
"title": "Astros AT Phillies",
"meta": {
"gameId": "9207104d-771d-4aa0-993f-7939d8b8c617",
"awayTeam": 3655,
"homeTeam": 3635,
"scheduled": "2024-08-27T22:40:00+00:00",
"awayTeamName": "Astros",
"homeTeamName": "Phillies"
},
"league": "mlb",
"scheduled": "2024-08-27T22:40:00.000Z",
"start": 1724798370278,
"end": 1724807855106,
"apis": [
{
"name": "boxscore",
"description": "game box score",
"apiType": "rest",
"formats": [
"json",
"xml"
],
"versions": [
"v7"
],
"languages": [
"en"
]
},
{
"name": "game",
"description": "game statistics",
"apiType": "rest",
"formats": [
"json",
"xml"
],
"versions": [
"v7"
],
"languages": [
"en"
]
},
{
"name": "pbp",
"description": "game play by play",
"apiType": "rest",
"formats": [
"json",
"xml"
],
"versions": [
"v7"
],
"languages": [
"en"
]
},
{
"name": "pitch metrics",
"description": null,
"apiType": "rest",
"formats": [
"json",
"xml"
],
"versions": [
"v7"
],
"languages": [
"en"
]
},
{
"name": "events",
"description": "game events",
"apiType": "push",
"formats": [
"json"
],
"versions": [
"v7"
],
"languages": [
"en"
]
},
{
"name": "statistics",
"description": null,
"apiType": "push",
"formats": [
"json"
],
"versions": [
"v7"
],
"languages": [
"en"
]
},
{
"name": "linescore",
"description": "game linescore",
"apiType": "push",
"formats": [
"json"
],
"versions": [
"v7"
],
"languages": [
"en"
]
}
]
},
{
"id": "024fb770-5fdb-11ef-b731-154d1d4eafcf",
"title": "Royals AT Guardians",
"meta": {
"gameId": "f7d3cb9a-9cfe-40a3-8fd1-7714b0ef5654",
"awayTeam": 3651,
"homeTeam": 3650,
"scheduled": "2024-08-28T17:10:00+00:00",
"awayTeamName": "Royals",
"homeTeamName": "Guardians"
},
"league": "mlb",
"scheduled": "2024-08-28T17:10:00.000Z",
"start": 1724864993188,
"end": 1724876267756,
"apis": [
{
"name": "boxscore",
"description": "game box score",
"apiType": "rest",
"formats": [
"json",
"xml"
],
"versions": [
"v7"
],
"languages": [
"en"
]
},
{
"name": "game",
"description": "game statistics",
"apiType": "rest",
"formats": [
"json",
"xml"
],
"versions": [
"v7"
],
"languages": [
"en"
]
},
{
"name": "pbp",
"description": "game play by play",
"apiType": "rest",
"formats": [
"json",
"xml"
],
"versions": [
"v7"
],
"languages": [
"en"
]
},
{
"name": "pitch metrics",
"description": null,
"apiType": "rest",
"formats": [
"json",
"xml"
],
"versions": [
"v7"
],
"languages": [
"en"
]
},
{
"name": "events",
"description": "game events",
"apiType": "push",
"formats": [
"json"
],
"versions": [
"v7"
],
"languages": [
"en"
]
},
{
"name": "statistics",
"description": null,
"apiType": "push",
"formats": [
"json"
],
"versions": [
"v7"
],
"languages": [
"en"
]
},
{
"name": "linescore",
"description": "game linescore",
"apiType": "push",
"formats": [
"json"
],
"versions": [
"v7"
],
"languages": [
"en"
]
}
]
}
]
}
}An NFL recording may include the below RESTful endpoints. All are available in json or xml.
- Game Boxscore (
boxscore) - Game Play-by-Play (
pbp) - Game Roster (
rosters) - Game Statistics (
game)
It may also include Push feeds, available in json only:
- Push Events (
events) - Push Statistics (
statistics) - Push Pulse (
pulse)
Available endpoints vary by league and sport
Register Your Session (REST Only)
Use the id for your selected game to start a session. At this point the specific feed—if multiple feeds are available—is not needed.
curl --location --request POST 'https://playback.sportradar.com/graphql' \
--header 'Content-Type: application/json' \
--data-raw '{
"query":"mutation CreateSession($input: CreateSessionInput!) { createSession(input: $input) }",
"variables":{
"input":{
"recordingId":"95aa13a0-6538-11ef-9287-d597687b4672"
}
}
}'This request uses recordingId":"95aa13a0-6538-11ef-9287-d597687b4672 in the above NFL response sample. The response returns your unique sessionId to be used in subsequent data API requests.
Make an API Request
Use your recordingId and sessionId to make a request for a game. Continually request this path to receive updates.
Click here for the complete path parameters.
curl --location --request GET 'https://playback.sportradar.com/replay/nfl/95aa13a0-6538-11ef-9287-d597687b4672?feed=boxscore&contentType=json&sessionId={sessionId}'RESTful Request Path
https://playback.sportradar.com/replay/{sportradar_api}/{recordingId}?feed={feed}&contentType={contentType}&sessionId={sessionId}
REST Path Parameters
| Parameter | Description |
|---|---|
sportradar_api | Desired API (sport or league) for the simulation. Baseball: mlb (MLB)Basketball: nba (NBA), nbdl (NBA G League), ncaamb (NCAA Men's Basketball), ncaawb (NCAA Women's Basketball), wnba (WNBA)Football: ncaafb (NCAA Football), nfl (NFL), ufl (UFL)Hockey: nhl (NHL)Soccer: soccer |
recordingId | ID of the recording. (ex. 95aa13a0-6538-11ef-9287-d597687b4672) |
RESTful Query String Parameters
| Parameter | Description |
|---|---|
feed_name | Desired feed for the simulation. Found under apis.name. Note the apis.description field for endpoint name if needed. Feed availability varies for each API.boxscore, game, pbp, rostersNHL only: analytics, shot_zones, faceoffs, time_on_iceSoccer only: lineups, summary, timeline, standings, extended-timeline, extended-summary, links, summaries, season-leaders, season-missing-players, season-info, season-competitors |
contentType | Desired content type.json or xml |
sessionId | Session ID returned by the session request. (ex. aa23f380-2234-11ed-8a8a-cbecc410da60\_-137242789) |
Push Request Path
https://playback.sportradar.com/subscribe/{feed_name}?recording_id={recordingId}
Push Path Parameters
| Parameter | Description |
|---|---|
feed_name | Desired feed for the simulation. Found under apis.name.Push feeds are indicated with "apiType": "push".events, statistics, clockpulse (NFL only), linescore (MLB only) |
recordingId | ID of the recording. (ex. 95aa13a0-6538-11ef-9287-d597687b4672) |
Using Simulations to Test Failover Behavior
Sportradar provides failover coverage for leagues with official data partnerships.
You can test failover behavior for NBA or WNBA by using a simulated Top-25 NCAA men’s basketball game.
Updated 10 days ago