STAT-API
← NFL Cookbook

See the whole range of outcomes

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.

NFL sim tutorial · recipe 2 of 5. Read the histogram of a game total and of a player, with its percentiles and the share above the market line.

API calls in this recipe:weeksrunAPI reference

What it is
Run the free game (2026 Week 1 DEN @ KC) 5,000 times and read the histogram of the game total and the range of the best fantasy player.
When to use it
You price an alternate line or a prop, or you draw a bell curve, and the mean alone is not enough.
What you get back
A curve for the game total and a curve for each player, each with the mean, the percentiles, the skew, the histogram bins, and the share of draws above the market line.

1.Ask for the distributions

Run the free game 5,000 times and switch on the distributions section only.

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

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

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.

Game total | mean 43.16, SD 13.00 | 10th 27.00, median 43.00, 90th 60.00
Market total 42.7 | simulated chance of the over 50.5%
Share of draws by game total, bins with 2% or more:
  [ 17.46,  21.62)  2.38% ##
  [ 21.62,  25.77)  4.04% ####
  [ 25.77,  29.92)  6.26% ######
  [ 29.92,  34.08) 11.54% ###########
  [ 34.08,  38.23) 11.08% ###########
  [ 38.23,  42.38) 12.58% ############
  [ 42.38,  46.54) 12.14% ############
  [ 46.54,  50.69) 11.04% ###########
  [ 50.69,  54.85)  8.32% ########
  [ 54.85,  59.00)  6.58% ######
  [ 59.00,  63.15)  5.74% #####
  [ 63.15,  67.31)  2.98% ##
Median bin: sample draw 15
Top receiver 1311 (WR) rec yds | 10th 16.00, median 54.00, 90th 109.00 | skew 0.83