STAT-API
Free game: game_id = 43418 (2026 Week 1 DEN @ KC)GET /api/v1/nfl/weeks is FreeBeta

NFL sim tutorial (beta)

The recipes below teach the NFL play-by-play simulator, one call at a time. Each recipe runs on the free game and prints real output. Each recipe is one program in TypeScript, Python, Go and Java, and the four programs print the same lines.

SIM & Optimizer Cookbook Tracks

23 recipes across TypeScript, Python, Go, and Java — generated from one schema with byte-identical output across languages.

Quickstart guideData timing guide23 recipes verified 4/4 live (2026-11-19)

NFL Play-by-Play SIM

API reference →

Full-game NFL Monte Carlo drive & play simulation — summary metrics, 30-bin bell curves, 6 archetype scoreboxes, play-by-play tracing, and CRN what-if overrides.

  1. 1.Run your first NFL game simulation4/4 verified
  2. 2.See the whole range of outcomes4/4 verified
  3. 3.Meet six typical games4/4 verified
  4. 4.Replay one simulated game4/4 verified
  5. 5.Ask a what-if question4/4 verified

NBA Possession-by-Possession SIM

API reference →

Full-game NBA lineup-rotation and possession simulation — free game discovery, game & player summary projections, empirical bell curves, and CRN spread sensitivity overrides.

  1. 1.Run an NBA possession simulation summary4/4 verified
  2. 2.Extract NBA empirical bell curves and quantiles4/4 verified
  3. 3.Compare NBA Common Random Numbers spread overrides4/4 verified

DFS SIM Lineups, Pool Re-Selector & Async Jobs

API reference →

Contest-aware Monte Carlo GPP lineup generation, sub-50ms in-memory pool_id re-selection with EV/diversity Pareto frontiers, async 202 job polling, and NBA contest simulation.

  1. 1.Generate EV-maximized NFL GPP lineups with Prefer: wait4/4 verified
  2. 2.Re-select SIM portfolios in <50ms via cached pool_id4/4 verified
  3. 3.Queue an async 202 SIM job and poll until completion4/4 verified
  4. 4.Generate EV-optimized NBA Classic GPP lineups4/4 verified

Start here

What you need

An API key from stat-api.com, and one of the four SDKs. Set the key in the environment variable STAT_API_KEY. A free key runs every recipe, because every recipe uses the free game.

The free game

Game 43418 (2026 Week 1 DEN @ KC) is free for every caller on `run`. Other games need a Pro or Elite plan, or the DFS add-on. The `weeks` call is free for all games.

How a run works

A run plays the game `n_draws` times. The limits are 50 to 10000, and the default is 2500. The same `seed` gives the same draws. A run returns the sections that you ask for in `include`: summary, distributions, scorebox and play by play (`pbp`). Every section is on by default, so turn off the sections that you do not read.

What to trust

The sim is a beta. Each `run` answer carries the header `x-sim-engine`, which names the engine release, and the header `x-sim-validation`, which names the page that says what is validated. A game is listed and runs only after its betting line has posted. A game without a line answers `409`.

Your first call, with curl

Two calls need no SDK. The first lists the weeks and names the free game. The second runs the free game 1,000 times and returns the summary only.

curl -s -H "Authorization: Bearer $STAT_API_KEY" \
  "https://api.stat-api.com/api/v1/nfl/weeks?season=2026"

curl -s -X POST "https://api.stat-api.com/api/v1/sim/nfl/run" \
  -H "Authorization: Bearer $STAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"game_id": 43418, "n_draws": 1000, "seed": 42,
       "include": {"summary": true, "distributions": false,
                   "scorebox": false, "pbp": false}}'

Install an SDK

  • npm install @stat-api/client
  • pip install stat-api-client
  • go get github.com/stat-api/stat-api/go

Java builds from source. See the SDK pages.

The recipes

  1. Find the free game, run it without manually assembling inputs, and read the win chances and player projections.

  2. Read the histogram of a game total and of a player, with its percentiles and the share above the market line.

  3. Read six whole games that stand for the middle of the range, its tails and the overtime case.

  4. Replay one draw of a run, drive by drive and play by play.

  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.

Interactive Toy App — 2026 Week 1 DEN @ KC (game_id = 43418)

Powered by @stat-api/client (`api.nfl.weeks`, `api.sim.nfl.run`)

5. Common Random Numbers (`seed = 42`) What-If Override Comparison

Multi-Language SDK Examples (`TypeScript`, `Python`, `Go`, `Java`)

Every snippet below is compiled and verified against the local SDKs in sdks/cookbook/.

1. Run your first NFL game simulation

/docs/cookbook/nfl/sim-summary →

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.

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

2. See the whole range of outcomes

/docs/cookbook/nfl/sim-distributions →

A projection gives one number. The sim gives a draw for every one of its runs, so it can also tell you how wide the range is. Set `distributions` in `include` to get one curve for the game total, the spread and the team stats, and one curve for each player. A curve holds the mean, the percentiles, the skew and a histogram. The `p_over_vegas` field is the share of draws above the market line.

import { StatApi } from '@stat-api/client'

const api = new StatApi() // reads STAT_API_KEY from the environment

// Ask for the distributions
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: 5000,
  seed: 42,
  include: {
    summary: false,
    distributions: true,
    scorebox: false,
    pbp: false,
  },
});
const dist = run.output.distributions;
if (!dist) throw new Error('the run returned no distributions');
const total = dist.total_points;
console.log(
  `Game total | mean ${total.mean.toFixed(2)}, SD ${total.sd.toFixed(2)} | ` +
    `10th ${total.p10.toFixed(2)}, median ${total.p50.toFixed(2)}, 90th ${total.p90.toFixed(2)}`,
);
if (total.vegas_line !== null && total.p_over_vegas !== null) {
  console.log(
    `Market total ${total.vegas_line.toFixed(1)} | simulated chance of the over ${(total.p_over_vegas * 100).toFixed(1)}%`,
  );
}

// Read the histogram
console.log('Share of draws by game total, bins with 2% or more:');
for (const bin of total.bins) {
  if (bin.prob < 0.02) continue;
  console.log(
    `  [${bin.x_min.toFixed(2).padStart(6)}, ${bin.x_max.toFixed(2).padStart(6)}) ` +
      `${(bin.prob * 100).toFixed(2).padStart(5)}% ${'#'.repeat(Math.floor(bin.prob * 100))}`,
  );
}

// Find a draw that you can replay
const median = total.bins.find((b) => b.x_min <= total.p50 && total.p50 < b.x_max);
console.log(`Median bin: sample draw ${median?.sample_draw_idx ?? 'none'}`);

// Read the range of a player
const star = [...dist.players]
  .filter((p) => p.rec_yd !== null)
  .sort((a, b) => (b.rec_yd?.mean ?? 0) - (a.rec_yd?.mean ?? 0))[0];
if (star?.rec_yd) {
  const rec = star.rec_yd;
  console.log(
    `Top receiver ${star.player_id} (${star.position}) rec yds | ` +
      `10th ${rec.p10.toFixed(2)}, median ${rec.p50.toFixed(2)}, 90th ${rec.p90.toFixed(2)} | skew ${rec.skew.toFixed(2)}`,
  );
}

3. Meet six typical games

/docs/cookbook/nfl/sim-scorebox →

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.

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

4. Replay one simulated game

/docs/cookbook/nfl/sim-trace →

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.

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

5. Ask a what-if question

/docs/cookbook/nfl/sim-overrides →

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.

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