Run your first NFL game simulation
The sim plays one NFL game many times and counts what happens. Start with the free game. The `weeks` call names it and `run` plays the game with zero manual inputs required. Every section of a run is on by default, so this recipe asks for the summary only.
NFL sim tutorial · recipe 1 of 5. Find the free game, run it without manually assembling inputs, and read the win chances and player projections.
API calls in this recipe:weeksrunAPI reference
- What it is
- Find the free game (2026 Week 1 DEN @ KC, game 43418), run the game 5,000 times, and read the summary.
- When to use it
- You want the chance that the home team wins, covers or goes over the market total, and the player projections.
- What you get back
- A summary with the simulated total, the win, cover and over chances, and one row of statistics per player.
1.Find the free game
The `weeks` call is free. It lists the games of a season and names the free game in `free_game_id`.
const weeks = await api.nfl.weeks({ season: 2026 });
const gameId = weeks.free_game_id;
console.log(`Season ${weeks.season} | free game ${gameId} | ${weeks.games.length} games`);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
// Find the free game
const weeks = await api.nfl.weeks({ season: 2026 });
const gameId = weeks.free_game_id;
console.log(`Season ${weeks.season} | free game ${gameId} | ${weeks.games.length} games`);
// Run the game 5,000 times
const run = await api.sim.nfl.run({
game_id: gameId,
n_draws: 5000,
seed: 42,
include: {
summary: true,
distributions: false,
scorebox: false,
pbp: false,
},
});
const summary = run.output.summary;
if (!summary) throw new Error('the run returned no summary');
console.log(
`Simulated total ${summary.sim_total_mean.toFixed(2)} (SD ${summary.sim_total_sd.toFixed(2)}) | ` +
`home win ${(summary.home_win_prob * 100).toFixed(1)}% | ` +
`home cover ${(summary.home_cover_prob * 100).toFixed(1)}% | ` +
`over ${(summary.over_prob * 100).toFixed(1)}%`,
);
console.log(`Box-score checks: ${summary.conservation_ok ? 'passed' : 'failed'}`);
// Rank the players
const top = [...summary.players].sort((a, b) => b.rec_yd_mean - a.rec_yd_mean).slice(0, 5);
console.log('Top 5 players by mean receiving yards:');
for (const p of top) {
console.log(
` Player ${p.player_id} (${p.position}/${p.depth_role}) | mean ${p.rec_yd_mean.toFixed(1)} | ` +
`median ${p.rec_yd_p50.toFixed(1)} | 90th percentile ${p.rec_yd_p90.toFixed(1)}`,
);
}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.
Season 2026 | free game 43418 | 163 games
Simulated total 43.16 (SD 13.00) | home win 55.1% | home cover 50.8% | over 50.5%
Box-score checks: passed
Top 5 players by mean receiving yards:
Player 1311 (WR/WR1) | mean 59.1 | median 54.0 | 90th percentile 109.0
Player 2455 (WR/WR1) | mean 54.8 | median 50.0 | 90th percentile 100.0
Player 79 (TE/TE1) | mean 46.2 | median 41.0 | 90th percentile 87.0
Player 525 (WR/WR2) | mean 45.9 | median 40.0 | 90th percentile 88.0
Player 3156 (WR/WR2) | mean 41.8 | median 36.0 | 90th percentile 85.0