STAT-API
← NFL Cookbook

Ask a what-if question

Flat top-level and `home`/`away`/`players` fields on `run` override the game's hydrated inputs: the market line (`total`, `home_spread`, `home_score`, `away_score`), the weather, team tempo/pass rate, and player availability or props. Run the game twice with the same `seed`, once without overrides and once with them. Both runs use the same random draws, so each difference between the two summaries comes from your change and not from luck. This is called common random numbers. The sim solves each game to the market, so the team totals follow a new spread.

NFL sim tutorial · recipe 5 of 5. Change the spread of the game, and read the exact change in the win chance and in the points, because both runs use the same seed.

API calls in this recipe:weeksrunAPI reference

What it is
Run the free game (2026 Week 1 DEN @ KC) twice with the same seed: once as it is, and once with the home team as a 6.5 point favorite.
When to use it
You want the exact effect of one change, such as a moved line, a different pace, or a player who sits, with no noise from the random draws.
What you get back
Two summaries. Every difference between them comes from the override, because both runs use the same draws.

1.Run the baseline

The baseline is the game as the market and the inputs have it. It uses `seed` 42.

const weeks = await api.nfl.weeks({ season: 2026 });
const gameId = weeks.free_game_id;
const include = {
  summary: true,
  distributions: false,
  scorebox: false,
  pbp: false,
};
const baseline = await api.sim.nfl.run({ game_id: gameId, n_draws: 5000, seed: 42, include });

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

// Run the baseline
const weeks = await api.nfl.weeks({ season: 2026 });
const gameId = weeks.free_game_id;
const include = {
  summary: true,
  distributions: false,
  scorebox: false,
  pbp: false,
};
const baseline = await api.sim.nfl.run({ game_id: gameId, n_draws: 5000, seed: 42, include });

// Run the what-if with the same seed
const scenario = await api.sim.nfl.run({
  game_id: gameId,
  n_draws: 5000,
  seed: 42,
  include,
  home_spread: -6.5,
});

// Read the exact change
const before = baseline.output.summary;
const after = scenario.output.summary;
if (!before || !after) throw new Error('a run returned no summary');
const home = baseline.matchup.home_abbr;
const away = baseline.matchup.away_abbr;
const signed = (x: number, digits: number): string => `${x >= 0 ? '+' : ''}${x.toFixed(digits)}`;
console.log(`What if ${home} were a 6.5 point favorite? Seed 42 on both runs.`);
console.log(
  `Home win chance | ${(before.home_win_prob * 100).toFixed(1)}% -> ${(after.home_win_prob * 100).toFixed(1)}% ` +
    `(${signed((after.home_win_prob - before.home_win_prob) * 100, 1)} points)`,
);
console.log(
  `${home} points | ${before.home_team.points_mean.toFixed(2)} -> ${after.home_team.points_mean.toFixed(2)} ` +
    `(${signed(after.home_team.points_mean - before.home_team.points_mean, 2)})`,
);
console.log(
  `${away} points | ${before.away_team.points_mean.toFixed(2)} -> ${after.away_team.points_mean.toFixed(2)} ` +
    `(${signed(after.away_team.points_mean - before.away_team.points_mean, 2)})`,
);

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.

What if KC were a 6.5 point favorite? Seed 42 on both runs.
Home win chance | 55.1% -> 70.4% (+15.3 points)
KC points | 22.41 -> 24.84 (+2.43)
DEN points | 20.74 -> 18.47 (-2.27)