STAT-API
← NFL Cookbook

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`);

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