STAT-API
← NFL Cookbook

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

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