Meet six typical games
A histogram says how often a total happens. A scorebox shows a whole game. With `scorebox` in `include` a run returns six archetypes: the median game, the 95th percentile shootout, the 5th percentile defensive game, a home blowout, an away blowout and an overtime game. Each one is a real draw of the run, so you can replay it with the same `seed` in the trace recipe.
NFL sim tutorial · recipe 3 of 5. Read six whole games that stand for the middle of the range, its tails and the overtime case.
API calls in this recipe:weeksrunAPI reference
- What it is
- Run the free game (2026 Week 1 DEN @ KC) 2,000 times and read six whole games from the run: the median game, a shootout, a defensive game, two blowouts and an overtime game.
- When to use it
- You want to see what the tails of the range look like as games, with a score by quarter, and not as numbers.
- What you get back
- Six archetype games. Each one has its draw index, its score by quarter for both teams, its total and its home margin.
1.Ask for the scorebox
Run the free game 2,000 times and switch on the scorebox section only. The `scorebox_limit` field is the number of extra draws that the section returns next to the six archetypes.
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 scorebox = run.output.scorebox;
if (!scorebox) throw new Error('the run returned no scorebox');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
// Ask for the scorebox
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 scorebox = run.output.scorebox;
if (!scorebox) throw new Error('the run returned no scorebox');
// Read the six archetypes
const away = run.matchup.away_abbr;
const home = run.matchup.home_abbr;
console.log(`Six typical games of 2000 draws | scores are Q1-Q2-Q3-Q4-OT-Total | ${away} at ${home}`);
for (const game of scorebox.archetypes) {
const margin = game.final_margin_home;
console.log(
` ${game.archetype ?? 'draw'} | draw ${game.draw_idx} | ${away} ${game.away_linescore.join('-')} | ` +
`${home} ${game.home_linescore.join('-')} | home margin ${margin >= 0 ? '+' : ''}${margin}`,
);
}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.
Six typical games of 2000 draws | scores are Q1-Q2-Q3-Q4-OT-Total | DEN at KC
median | draw 140 | DEN 7-3-3-7-0-20 | KC 7-3-3-9-0-22 | home margin +2
shootout_p95 | draw 1930 | DEN 7-14-10-10-0-41 | KC 7-7-7-3-0-24 | home margin -17
defensive_p05 | draw 173 | DEN 7-0-3-3-0-13 | KC 0-0-7-3-0-10 | home margin -3
home_blowout | draw 372 | DEN 0-9-3-0-0-12 | KC 14-14-3-3-0-34 | home margin +22
away_blowout | draw 54 | DEN 14-3-0-14-0-31 | KC 3-3-7-0-0-13 | home margin -18
overtime | draw 37 | DEN 0-10-7-14-0-31 | KC 7-7-3-14-7-38 | home margin +7