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
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.
Available Leagues & Sports
Replay simulations are currently available for the following APIs:
Quick Start
Making a call takes four steps. Each has its own numbered section below.
- Fetch Available Recordings — list what can be replayed
- Select a RecordingId — pick the game or event
- Register Your Session — get a
sessionId(REST only) - Make an API Request — request a feed from the replay endpoint
1. 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.
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 } } }"
}'2. Select a 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
3. 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.
4. 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)Golf: pga (PGA Tour), lpga (LPGA Tour)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-competitorsGolf only: golf-summary, golf-leaderboard, golf-hole-statistics, and per-round feeds such as golf-scorecards-01, golf-teetimes-01NBA Draft only: draft-summary, draft-trades, draft-team-picks-<team_id> (one per team) |
contentType | Desired content type.json or xml |
sessionId | Session ID returned by the session request. (ex. aa23f380-2234-11ed-8a8a-cbecc410da60\_-137242789) |
deduped | Optional. Controls replay pacing. Omitted or false — the recording replays in natural time, following its real pacing.true — duplicate and unchanged moments are stripped out and the remaining unique moments are packed back-to-back, so the recording plays back faster. Useful for multi-day events, where it removes the wait between rounds.Available for recordings captured from September 2026 onward. |
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)Golf only: golf-push-leaderboard, golf-push-scorecard |
recordingId | ID of the recording. (ex. 95aa13a0-6538-11ef-9287-d597687b4672) |
Multi-Day Events
Golf tournaments and the NBA Draft run across several days. They use the same workflow described above — fetch a recording, register a session, then request a feed — with a few differences worth knowing before you integrate.
Skipping the wait between roundsGolf tournaments and the NBA Draft play out over several days in real life. By default a recording replays in natural time, which carries those real gaps with it — including the overnight wait between rounds. Add
deduped=trueto the replay request to pack the recording back-to-back instead, so round 2 follows round 1 rather than arriving a day later. See Replay Pacing below.
Replay Pacing
A recording can be replayed at two different paces. Both use the same request path; the difference is the optional deduped query string parameter.
| Mode | Request | Behavior |
|---|---|---|
| Natural time (default) | deduped omitted, or deduped=false | The recording follows its real pacing, reproducing the original timing of the event — including the full gaps between rounds and between draft days. |
| Deduped | deduped=true | Duplicate and unchanged moments are stripped out and the remaining unique moments are packed back-to-back, so the recording plays back faster. |
Natural time is the better choice when you are testing how your integration behaves over a realistic timeline. Deduped is the better choice when you want to reach the end of a multi-day event quickly, without waiting out the dead air between rounds.
AvailabilityThe
dedupedparameter is available for recordings captured from September 2026 onward. Recordings made before then replay in natural time only — requestingdeduped=truefor one of those returns an error rather than a deduped stream.
curl --location --request GET 'https://playback.sportradar.com/replay/pga/{recordingId}?feed=golf-leaderboard&contentType=json&sessionId={sessionId}&deduped=true'Golf Simulations
Golf simulations cover the PGA and LPGA tours. Unlike other sports, golf is scoped by tour rather than by sport: pass pga or lpga as the league value on the recordings query, and use that same value as the sportradar_api in the replay path.
Once you have a recordingId, session registration and replay follow the same pattern as every other sport.
The apis array reflects what was captured for that specific recording rather than a fixed list. A tournament recording may include:
golf-summary,golf-leaderboard,golf-hole-statistics(REST)golf-push-leaderboard,golf-push-scorecard(Push)
Events that carry per-round data expose one feed per round, for example golf-scorecards-01 through golf-scorecards-04 and golf-teetimes-01 through golf-teetimes-04.
curl --location --request GET 'https://playback.sportradar.com/replay/pga/{recordingId}?feed=golf-leaderboard&contentType=json&sessionId={sessionId}'Golf Response Sample (LPGA)
{
"id": "4b2bbce6-883e-4a1b-8cdc-f44d538dae50",
"title": "CPKC Women's Open",
"meta": {
"tour": "lpga",
"season": 2026,
"startDate": "2026-08-20",
"endDate": "2026-08-23",
"tournamentId": "f70b2bf0-4702-46d6-8a07-d7d93ac9b933"
},
"league": "lpga",
"sport": "golf",
"apis": [
{ "name": "golf-push-leaderboard", "apiType": "push", "formats": ["json"] },
{ "name": "golf-push-scorecard", "apiType": "push", "formats": ["json"] },
{ "name": "golf-summary", "apiType": "rest", "versions": ["v3"], "formats": ["json"] },
{ "name": "golf-leaderboard", "apiType": "rest", "versions": ["v3"], "formats": ["json"] },
{ "name": "golf-hole-statistics", "apiType": "rest", "versions": ["v3"], "formats": ["json"] }
]
}NBA Draft Simulations
The NBA Draft is available as a simulation under the nba league key.
Its apis array has a different shape to every other simulation. Where other recordings expose a small fixed set of feed names, a draft recording exposes draft-summary, draft-trades, and one draft-team-picks-<team_id> feed per team — 30 on the current recording. Read the full list from the apis array in the recordings response rather than assuming a fixed set.
curl --location --request GET 'https://playback.sportradar.com/replay/nba/cc99bf90-aa6d-4802-b5a3-3c3cce2b560f?feed=draft-summary&contentType=json&sessionId={sessionId}'NBA Draft Response Sample
{
"id": "cc99bf90-aa6d-4802-b5a3-3c3cce2b560f",
"title": "NBA Draft 2026",
"league": "nba",
"scheduled": "2026-06-24T00:00:00.000Z",
"apis": [
{ "name": "draft-summary" },
{ "name": "draft-trades" },
{ "name": "draft-team-picks-<team_id>" }
]
}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 5 days ago