Replay one simulated game
A run keeps the summary statistics of its draws unless `include.pbp` is turned on. Pass a specific `draw_idx` inside `include.pbp_draws` with the same `seed` and `n_draws` to `run` to replay that draw's drives and every play. The first call asks for the scorebox, because the six archetypes carry the index of a draw worth replaying.
NFL sim tutorial · recipe 4 of 5. Replay one draw of a run, drive by drive and play by play.
API calls in this recipe:weeksrunAPI reference
- What it is
- Pick the shootout game from a run of the free game (2026 Week 1 DEN @ KC), then replay that one draw via `run` (`include.pbp` + `pbp_draws`): its drives and its plays.
- When to use it
- A number from a run looks odd and you want to see the game behind it, or you want to show one simulated game to a reader.
- What you get back
- The score by quarter, the drives with their results, and the plays with the clock, the down and distance, the field position and a description.
1.Pick a draw from a run
Run the free game 2,000 times with the scorebox on. Take the draw of the 95th percentile shootout. Its `draw_idx` is passed to `include.pbp_draws` in the next step.
const weeks = await api.nfl.weeks({ season: 2026 });
const gameId = weeks.free_game_id;
const run = await api.sim.nfl.run({
game_id: gameId,
n_draws: 2000,
seed: 42,
include: {
summary: false,
distributions: false,
scorebox: true,
pbp: false,
scorebox_limit: 1,
},
});
const shootout = run.output.scorebox?.archetypes.find((g) => g.archetype === 'shootout_p95');
if (!shootout) throw new Error('the run has no shootout game');
console.log(`Replay draw ${shootout.draw_idx}, the 95th percentile shootout of 2000 draws`);The complete program
Every step as one runnable file. It reads STAT_API_KEY from the environment, and is the same file that ships in the cookbook project for each SDK.
import { StatApi } from '@stat-api/client'
const api = new StatApi() // reads STAT_API_KEY from the environment
// Pick a draw from a run
const weeks = await api.nfl.weeks({ season: 2026 });
const gameId = weeks.free_game_id;
const run = await api.sim.nfl.run({
game_id: gameId,
n_draws: 2000,
seed: 42,
include: {
summary: false,
distributions: false,
scorebox: true,
pbp: false,
scorebox_limit: 1,
},
});
const shootout = run.output.scorebox?.archetypes.find((g) => g.archetype === 'shootout_p95');
if (!shootout) throw new Error('the run has no shootout game');
console.log(`Replay draw ${shootout.draw_idx}, the 95th percentile shootout of 2000 draws`);
// Replay the draw with run
const replay = await api.sim.nfl.run({
game_id: gameId,
n_draws: 2000,
seed: 42,
include: {
summary: false,
distributions: false,
scorebox: false,
pbp: true,
pbp_draws: [shootout.draw_idx],
},
});
const traced = replay.output.pbp?.[0];
if (!traced) throw new Error('the run returned no play-by-play trace');
const away = run.matchup.away_abbr;
const home = run.matchup.home_abbr;
console.log(
`${away} ${traced.scorebox.away_linescore[5]} - ${home} ${traced.scorebox.home_linescore[5]} | ` +
`${traced.drives.length} drives | ${traced.plays.length} plays`,
);
// Read the drives and the plays
console.log('First 5 drives:');
for (const d of traced.drives.slice(0, 5)) {
const team = d.posteam_is_home ? home : away;
console.log(
` ${d.drive_number}. ${team} | Q${d.start_quarter} ${d.start_clock} | ${d.plays} plays, ${d.net_yards} yds | ` +
`${d.result} | ${away} ${d.away_score_after} - ${home} ${d.home_score_after}`,
);
}
console.log('First 5 plays:');
for (const p of traced.plays.slice(0, 5)) {
console.log(` ${p.clock_display} | ${p.down_distance_display} | ${p.yardline_display} | ${p.description}`);
}Sample output
Engine nfl-play-sim/2.8.0, game 43418, made on 2026-11-18. The programs in all four languages print these lines.
Replay draw 1930, the 95th percentile shootout of 2000 draws
DEN 41 - KC 24 | 24 drives | 163 plays
First 5 drives:
1. KC | Q1 15:00 | 9 plays, 74 yds | TOUCHDOWN | DEN 0 - KC 7
2. DEN | Q1 10:08 | 8 plays, 80 yds | TOUCHDOWN | DEN 7 - KC 7
3. KC | Q1 07:34 | 7 plays, 26 yds | TURNOVER | DEN 7 - KC 7
4. DEN | Q1 04:26 | 10 plays, 50 yds | TOUCHDOWN | DEN 14 - KC 7
5. KC | Q2 14:54 | 4 plays, 6 yds | PUNT | DEN 14 - KC 7
First 5 plays:
15:00 | 1st & 10 | OWN 26 | Rush for 4 yds
14:17 | 2nd & 6 | OWN 30 | Pass complete for 14 yds (13 air, 1 YAC), 1ST DOWN
13:31 | 1st & 10 | OWN 44 | Pass complete for 19 yds (19 air, 0 YAC), 1ST DOWN
13:11 | 1st & 10 | OPP 37 | Pass complete for 19 yds (-1 air, 20 YAC), 1ST DOWN
12:28 | 1st & 10 | OPP 18 | Rush for 3 yds