API Documentation

Player Profile with Historical Data

Each player includes historical stats from 2020 through the current 2026 season and matchup history against every team. Weekly actuals and season totals carry all three scoring formats: the base fantasy_points / MISC_FPTS is standard, with _ppr / _half (weekly) and _PPR / _HALF (totals) variants alongside. Use ?scoring= on /stats to have the API resolve them for you (default ppr).

{
  "player_id": "Jared Goff#QB",
  "player_name": "Jared Goff",
  "position": "QB",
  "team": "DET",
  "seasons": {
    "2024": {
      "weekly_stats": {
        "1": {
          "opponent": "LA",
          "fantasy_points": 18.56,       // standard
          "fantasy_points_ppr": 18.56,   // QBs rarely catch passes, so equal here
          "fantasy_points_half": 18.56
        },
        "2": {
          "opponent": "TB",
          "fantasy_points": 29.08,
          "fantasy_points_ppr": 29.08,
          "fantasy_points_half": 29.08
        }
        // ... weeks 3-17
      },
      "season_totals": {
        "MISC_FPTS": 372.5,              // standard
        "MISC_FPTS_PPR": 372.5,
        "MISC_FPTS_HALF": 372.5,
        "Rank": 5, "Rank_PPR": 6, "Rank_HALF": 6
        // ... passing/rushing counting stats
      }
    },
    "2023": { /* Full season data */ },
    "2022": { /* Full season data */ },
    "2021": { /* Full season data */ },
    "2020": { /* Full season data */ }
  },
  "vs_opponent": {
    "GB": {
      "games_played": 8,
      "avg_actual": 19.42,
      "total_actual": 155.36,
      "avg_projected": 18.9,
      "avg_deviation": 0.52,
      "by_season": { "2025": { "games_played": 2, "avg_actual": 21.3 } }
    },
    "CHI": {
      "games_played": 8,
      "avg_actual": 22.87,
      "total_actual": 182.96,
      "avg_projected": 19.4,
      "avg_deviation": 3.47,
      "by_season": { "2025": { "games_played": 2, "avg_actual": 25.1 } }
    }
    // ... all 32 teams
  }
}

Matchup Analysis

Get historical performance data when a player faces a specific opponent. Perfect for start/sit decisions.

GET /matchups/Amon-Ra%20St.%20Brown%23WR/GB

{
  "player_id": "Amon-Ra St. Brown#WR",
  "player_name": "Amon-Ra St. Brown",
  "position": "WR",
  "team": "DET",
  "opponent": "GB",
  "stats": {
    "games_played": 6,
    "games_with_projections": 4,
    "avg_actual": 21.45,
    "total_actual": 128.7,
    "avg_projected": 18.2,
    "avg_deviation": 3.1,
    "avg_deviation_percentage": 17.03,
    "last_game_season": "2025",
    "last_game_week": 13,
    "by_season": {
      "2025": { "games_played": 2, "avg_actual": 24.6 },
      "2024": { "games_played": 2, "avg_actual": 19.9 }
    }
  }
}

// Use case: Amon-Ra averages 21.4 pts vs GB (6 games)
// but only 15.8 pts vs MIN (6 games) - start him vs GB!

Snap Share Trend

Catch a role change before the box score shows it. Compare a player’s recent snap share to his season average.

GET /snaps/Bucky%20Irving%23RB?season=2024&trend=4

{
  "player_id": "Bucky Irving#RB",
  "season": "2024",
  "season_snap_pct_avg": 44.4,
  "recent_snap_pct_avg": 57.0,
  "trend_delta": 12.6
}

// Use case: +12.6 over the last 4 weeks means Irving is taking over
// the Tampa Bay backfield. Buy before the points catch up.

Projection Deviation Analysis

Identify boom/bust candidates by seeing how players perform vs their projections.

GET /deviations/Jahmyr%20Gibbs%23RB

{
  "player_id": "Jahmyr Gibbs#RB",
  "player_name": "Jahmyr Gibbs",
  "position": "RB",
  "season": "2024",
  "avg_deviation": 3.2,
  "weeks_analyzed": 16,
  "weekly_deviations": [
    {
      "week": 1,
      "actual_points": 22.4,
      "projected_points": 14.5,
      "deviation": 7.9,
      "deviation_percentage": 54.5,
      "opponent": "LA"
    },
    {
      "week": 2,
      "actual_points": 8.6,
      "projected_points": 15.2,
      "deviation": -6.6,
      "deviation_percentage": -43.4,
      "opponent": "TB"
    }
  ]
}

// Use case: Moderate deviation = consistent player
// Gibbs ranges from 8.6 to 22.4 pts - reliable floor

Weekly Projections

Get fantasy point projections for all players, sorted by projected points.

GET /projections/12?position=TE

{
  "week": "12",
  "season": "2025",
  "projections": [
    {
      "player_id": "Sam LaPorta#TE",
      "player_name": "Sam LaPorta",
      "position": "TE",
      "team": "DET",
      "week": "12",
      "projected_points": 12.8,
      "injury_status": "Healthy"
    },
    {
      "player_id": "Travis Kelce#TE",
      "player_name": "Travis Kelce",
      "position": "TE",
      "team": "KC",
      "week": "12",
      "projected_points": 11.4,
      "injury_status": "Healthy"
    },
    {
      "player_id": "George Kittle#TE",
      "player_name": "George Kittle",
      "position": "TE",
      "team": "SF",
      "week": "12",
      "projected_points": 10.9,
      "injury_status": "Questionable"
    }
  ],
  "count": 64
}

Example: how sticky is points per game from one season to the next?

Pull a player's weekly actuals for consecutive seasons and compare two forecasts of next season: last season as-is, and last season pulled 30% of the way back toward the position average. A dozen players over 2021–2025 is about 60 requests. Past seasons and weekly actuals are not on the free plan, so this runs on Basic ($5/month, 5,000 requests a month).

import os, statistics, requests
from urllib.parse import quote

API = "https://api.gridirondata.com/api/v1"
H = {"x-api-key": os.environ["GRIDIRON_API_KEY"]}

def ppg(player_id, season):
    r = requests.get(f"{API}/stats/{quote(player_id, safe='')}/{season}", headers=H)
    if r.status_code == 404:
        return None                      # no data for that season
    weeks = [w["points"] for w in r.json()["weekly_stats"].values()
             if isinstance(w, dict) and w.get("points") is not None]
    return sum(weeks) / len(weeks) if len(weeks) >= 8 else None

roster = ["Justin Jefferson#WR", "CeeDee Lamb#WR", "Davante Adams#WR", "Mike Evans#WR"]
seasons = range(2021, 2026)
table = {(p, s): ppg(p, s) for p in roster for s in seasons}

naive, shrunk = [], []
for s in seasons[:-1]:
    this = {p: table[(p, s)] for p in roster if table[(p, s)] and table.get((p, s + 1))}
    if not this:
        continue
    mean = statistics.mean(this.values())
    for p, v in this.items():
        nxt = table[(p, s + 1)]
        naive.append(abs(v - nxt))
        shrunk.append(abs(0.7 * v + 0.3 * mean - nxt))
print(f"naive MAE {statistics.mean(naive):.2f}  shrunk MAE {statistics.mean(shrunk):.2f}")

On a 12-player roster across positions, 2021–2025, shrinking cut the average miss from 3.05 to 2.75 PPR points per game, most of it at RB and WR. The fuller script, with per-position results, the biggest year-over-year moves and a /deviations check of whether projection-beaters keep beating projections, is backtest.py in our examples.

To grade weekly projections against actuals across the whole league, see the Backtest Fantasy Projections Against Actuals guide.

GET Get Player by ID

Retrieve detailed information for a specific player. On the free plan this returns the profile only; see the free plan.

Path Parameters

Query Parameters

curl -H "x-api-key: YOUR_KEY" \
  "https://api.gridirondata.com/api/v1/players/Josh%20Allen%23QB"

GET Search Players

Search for players by name, position, or team.

Query Parameters

curl -H "x-api-key: YOUR_KEY" \
  "https://api.gridirondata.com/api/v1/players/search?name=Allen&position=QB"

GET Get Player by ESPN Id

Look a player up by ESPN athlete id, the numeric key most sportsbook and ESPN feeds carry. Returns the same record as Get Player by ID. Free plan included.

curl -H "x-api-key: YOUR_KEY" \
  "https://api.gridirondata.com/api/v1/players?espn_id=3139477"

GET Get Player by GSIS or PFR Id

Look a player up by NFL GSIS id (00-0034857), the key in nflverse and NFL data, or by Pro Football Reference id with ?pfr_id=AlleJo02. Returns the same record as Get Player by ID, including the ids map: gsis, pfr, pff, nfl, espn and sleeper, whichever we have. The crosswalk comes from nflverse's player file (CC-BY-4.0) and is refreshed daily; a player nflverse doesn't list has no ids and isn't found this way. Free plan included.

curl -H "x-api-key: YOUR_KEY" \
  "https://api.gridirondata.com/api/v1/players?gsis_id=00-0034857"

{
  "player_id": "Josh Allen#QB",
  "player_name": "Josh Allen",
  "position": "QB",
  "espn_player_id": 3918298,
  "ids": {"gsis": "00-0034857", "pfr": "AlleJo02", "pff": "46601",
          "nfl": "46076", "espn": "3918298", "sleeper": "4984"},
  "seasons": {"...": "..."}
}

GET Get Player (Exact Match)

Get a specific player by exact name and position match.

Query Parameters

curl -H "x-api-key: YOUR_KEY" \
  "https://api.gridirondata.com/api/v1/players?name=Josh%20Allen&position=QB"

GET List Players

List all players with pagination.

Query Parameters

GET Get Weekly Projections

Get fantasy point projections for all players for a specific week. Provider weekly projections are published as each week approaches, so for weeks that aren't out yet the API returns a prorated season-long projection (season points ÷ games) for every player. The projection_source field tells you which was used — weekly (real per-week number) or season_prorated (estimate) — and real weekly values replace the estimate automatically once published.

Players who can't play. For the current and upcoming weeks, players who are OUT, on IR, PUP, suspended or on a reserve list, and free agents, project 0 points with available: false, projection_source: "unavailable" and an unavailable_reason. projected_points_if_active keeps the number they'd have. Past weeks aren't changed by today's injury report.

Per-stat projections (Pro). Each row has projected_stats: pass_att, pass_cmp, pass_yds, pass_td, pass_int, rush_att, rush_yds, rush_td, rec, rec_yds and rec_td for the week. They're the season projection per game, scaled to the weekly points projection when there is one. Free and Basic keys get points only, and the response's top-level projected_stats is a note that the stat lines need Pro.

Path Parameters

Query Parameters

curl -H "x-api-key: YOUR_KEY" \
  "https://api.gridirondata.com/api/v1/projections/12?position=QB&scoring=half"

{
  "week": "12",
  "season": "2026",
  "scoring": "half",
  "projections": [
    {
      "player_id": "Josh Allen#QB",
      "player_name": "Josh Allen",
      "position": "QB",
      "team": "BUF",
      "week": "12",
      "projected_points": 24.5,
      "projection_source": "season_prorated",
      "espn_player_id": 3918298,
      "on_bye": false,
      "injury_status": "ACTIVE",
      "injury_status_raw": "Healthy",
      "available": true,
      "projected_stats": {
        "pass_att": 32.4, "pass_cmp": 21.2, "pass_yds": 250.0,
        "pass_td": 1.76, "pass_int": 0.59,
        "rush_att": 4.1, "rush_yds": 20.0, "rush_td": 0.18
      }
    },
    {
      "player_id": "Jalen Hurts#QB",
      "player_name": "Jalen Hurts",
      "position": "QB",
      "team": "PHI",
      "week": "12",
      "projected_points": 0,
      "projection_source": "unavailable",
      "espn_player_id": 4040715,
      "on_bye": false,
      "injury_status": "IR",
      "injury_status_raw": "IR",
      "available": false,
      "unavailable_reason": "IR",
      "projected_points_if_active": 18.85,
      "projected_stats": {"pass_yds": 0, "pass_td": 0, "...": 0}
    }
  ],
  "count": 32,
  "prorated_count": 32,
  "unavailable_count": 1
}

GET Get Rest-of-Season Projections

Projected fantasy points for every player over the regular-season weeks still to play (through week 18), for the current season. Basic and up; a free key gets 403 with "reason": "basic_required". The player's bye week is left out, and so is the current week once he has a stat line for it. games_remaining and remaining_weeks list what was counted.

How it's computed. Weekly projections are published a week or so ahead, so most remaining weeks don't have one yet. A week that has a published weekly projection counts that number (listed in weekly_projection_weeks). Every other week counts the player's per-game rate: his nearest published weekly projection (rate_source: weekly, rate_week), or season projection ÷ 17 when he has none (rate_source: season_prorated). There is no other modeling: no strength of schedule, no injury adjustment. method is per_game_rate when any week used the rate and weekly_sum when every remaining week had a weekly projection. When weekly projections carry stat fields, projected_stats totals them on the same basis.

Query Parameters

curl -H "x-api-key: YOUR_KEY" \
  "https://api.gridirondata.com/api/v1/projections/ros?position=QB"

{
  "season": "2026",
  "current_week": 8,
  "position": "QB",
  "scoring": "ppr",
  "method": "per_game_rate",
  "method_note": "per_game_rate: weeks without a published weekly projection count ...",
  "projections": [
    {
      "player_id": "Josh Allen#QB",
      "player_name": "Josh Allen",
      "position": "QB",
      "team": "BUF",
      "bye_week": 7,
      "games_remaining": 11,
      "remaining_weeks": [8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18],
      "ros_points": 242.0,
      "points_per_game": 22.0,
      "rate_source": "weekly",
      "rate_week": 8,
      "weekly_projection_weeks": [8],
      "method": "per_game_rate",
      "injury_status": "Active"
    }
  ],
  "count": 38
}

GET Get Player Stats

Get historical stats for a player in a specific season: weekly fantasy points (2020 on) and season totals. From 2025 on, each week also carries box_score, that game's passing, rushing and receiving line from ESPN box scores (pass_yds, rush_att, rec, targets and the rest).

Path Parameters

Query Parameters

Alternative: You can also query by name and position:

curl -H "x-api-key: YOUR_KEY" \
  "https://api.gridirondata.com/api/v1/stats?name=Josh%20Allen&position=QB&season=2024&scoring=ppr"

{
  "player_id": "Justin Jefferson#WR",
  "season": "2024",
  "scoring": "ppr",
  "season_points": 227.9,
  "weekly_stats": {
    "1": {
      "opponent": "NYG",
      "fantasy_points": 11.9,        // standard (base)
      "fantasy_points_ppr": 15.9,
      "fantasy_points_half": 13.9,
      "points": 15.9                 // resolved for scoring=ppr
    }
  },
  "season_totals": {
    "MISC_FPTS": 149.9,              // standard
    "MISC_FPTS_PPR": 227.9,
    "MISC_FPTS_HALF": 188.9,
    "Rank": 8, "Rank_PPR": 3, "Rank_HALF": 5
  }
}

GET Get Projection Deviations

Analyze how a player performs vs their projections. Useful for identifying boom/bust candidates.

Path Parameters

Query Parameters

Alternative: Query by name and position:

{
  "player_id": "Josh Allen#QB",
  "player_name": "Josh Allen",
  "position": "QB",
  "season": "2025",
  "avg_deviation": 3.2,
  "weeks_analyzed": 11,
  "weekly_deviations": [
    {
      "week": 1,
      "actual_points": 28.4,
      "projected_points": 24.5,
      "deviation": 3.9,
      "deviation_percentage": 15.9,
      "opponent": "ARI"
    }
  ]
}

GET Get Snap Share

Per-week snap share — the percentage of his team’s offensive plays a player was on the field for — plus special-teams snaps, a season average, and a trailing trend. Snap share moves before box-score production does, so it is the earliest reliable signal of a role change.

Data is sourced from nflverse / Pro-Football-Reference game-level snap counts. Percentages are returned as 0–100. Seasons 2020–2026 are available (the current season updates weekly); regular season (weeks 1–18) only.

Path Parameters

Query Parameters

Alternative: Query by name and position:

Response Fields

GET /snaps/Bucky%20Irving%23RB?season=2024&trend=4

{
  "player_id": "Bucky Irving#RB",
  "player_name": "Bucky Irving",
  "position": "RB",
  "season": "2024",
  "games": 17,
  "games_with_snaps": 17,
  "season_snap_pct_avg": 44.4,
  "recent_snap_pct_avg": 57.0,
  "trend_weeks": 4,
  "trend_delta": 12.6,
  "totals": {
    "games": 17,
    "offense_snaps": 516,
    "offense_pct_avg": 44.4,
    "st_snaps": 41,
    "st_pct_avg": 8.6
  },
  "weekly_snaps": [
    { "week": 1,  "offense_snaps": 20, "snap_pct": 31.0, "st_snaps": 8, "st_pct": 30.0, "team": "TB", "opponent": "WAS" },
    { "week": 18, "offense_snaps": 48, "snap_pct": 72.0, "st_snaps": 0, "st_pct": 0.0,  "team": "TB", "opponent": "NO"  }
  ],
  "source": "nflverse / Pro-Football-Reference game-level snap counts"
}

// Irving opened 2024 at 31% of Tampa Bay's snaps and finished at 72%.
// trend_delta of +12.6 flags the takeover while it is still happening.

Snap share on /stats

Snap data is also joined onto the stats endpoint, so you can read production and playing time together without a second request. Each weekly entry gains snap_pct and offense_snaps, and the response carries a snap_counts block.

GET /stats/Bucky%20Irving%23RB/2024

{
  "weekly_stats": {
    "1": { "points": 12.6, "opponent": "WAS", "snap_pct": 31.0, "offense_snaps": 20 }
  },
  "snap_counts": {
    "weekly": { ... },
    "totals": { "games": 17, "offense_snaps": 516, "offense_pct_avg": 44.4 }
  }
}

Note: weeks played and weeks with snaps are not always the same set — a blocking tight end can log snaps with no fantasy line. Weeks missing from one side simply omit the corresponding fields rather than reporting zero.

GET League-wide News Feed

Recent news across every tracked player, newest first, in one call: signings, trades, releases, injuries and depth-chart moves. Use it through free agency (March) and the NFL Draft (April) instead of polling player by player. The scrapers run year-round.

Plans: Basic and above get the full feed: 90 days of history, filters and paging. Free keys get 403 with "reason": "basic_required" and an upgrade_url; see the free plan.

Query Parameters

curl -H "x-api-key: YOUR_KEY" \
  "https://api.gridirondata.com/api/v1/news/latest?since=2027-03-09T00:00:00Z&impact=transaction&position=WR"

{
  "since": "2027-03-09T00:00:00Z",
  "until": "2027-03-11T14:02:10Z",
  "count": 1,
  "filters": {"impact": ["transaction"], "position": ["WR"]},
  "news": [
    {
      "player_id": "Davante Adams#WR",
      "player_name": "Davante Adams",
      "position": "WR",
      "team": "LAR",
      "headline": "Davante Adams expected at start of Rams offseason program",
      "summary": "",
      "impact": "transaction",
      "source": "pft-nbc",
      "url": "https://profootballtalk.nbcsports.com/...",
      "published_at": "2027-03-10T19:41:00Z"
    }
  ],
  "next_cursor": "WyIyMDI3LTAzLTEwVDE5OjQxOjAwWiIs..."
}

One headline about two players appears once per player, so a position or team filter still catches it.

GET Get Player News

Recent NFL news headlines for a player, newest first. Each item is tagged with an impact category (injury, transaction, role, or general) to help surface start/sit-relevant updates. Items are refreshed throughout the day, all year, and roll off after 90 days. For every player at once, use /news/latest.

Path Parameters

Query Parameters

Alternative: Query by name and position:

{
  "player_id": "Malik Nabers#WR",
  "days": 14,
  "count": 2,
  "news": [
    {
      "headline": "Nabers (knee) full participant at Wednesday practice",
      "summary": "Giants WR Malik Nabers practiced fully and is trending toward playing Sunday.",
      "impact": "injury",
      "source": "espn-nfl",
      "url": "https://www.espn.com/nfl/story/_/id/00000000",
      "published_at": "2026-09-10T17:22:00Z"
    },
    {
      "headline": "Nabers feeling 'good' but mum on playing Week 1",
      "summary": "",
      "impact": "general",
      "source": "espn-nfl",
      "url": "https://www.espn.com/nfl/story/_/id/00000001",
      "published_at": "2026-09-01T03:21:40Z"
    }
  ]
}

No news yet? When a player has no recent news, the response includes a request_scrape link you can call to queue an on-demand scrape (see next endpoint):

{
  "player_id": "Max Bredeson#RB",
  "days": 14,
  "count": 0,
  "news": [],
  "message": "No news found for Max Bredeson#RB in the last 14 days.",
  "request_scrape": {
    "method": "POST",
    "href": "https://api.gridirondata.com/api/v1/news/Max%20Bredeson%23RB/request",
    "description": "No news yet — POST to this link to request a fresh scrape for this player."
  }
}

POST Request a News Scrape

Queue an on-demand news scrape for a specific player — useful when GET /news/{player_id} returns no results and you want the latest sources checked immediately. The request is accepted and processed asynchronously; poll GET /news/{player_id} shortly after to see any new headlines. No request body is required.

Path Parameters

{
  "player_id": "Max Bredeson#RB",
  "status": "accepted",
  "message": "Scrape requested. New headlines (if any are found in current sources) will appear shortly.",
  "poll": {
    "method": "GET",
    "href": "https://api.gridirondata.com/api/v1/news/Max%20Bredeson%23RB"
  }
}

GET Get Injury Status Changes

Returns every player whose injury status changed since since. This is a Pro plan feature; Free and Basic keys get 403 with "reason": "pro_required", an upgrade_url and a pro_includes list of what the plan adds.

GridIron checks ESPN's league-wide injury report every 2 minutes from 8:00 am to 1:00 am ET (every 10 minutes overnight), so a status change usually appears here within a few minutes of ESPN posting it, with a detected_at time. A full refresh still runs daily at 11:00 ET and after inactives on game days, and once a day around 12:30 pm ET Sleeper's player data is checked for anyone ruled out whom ESPN hasn't caught yet. Poll with the next_since value from your last response to get only new changes. Statuses use the standard values; a change that is only a different spelling (Healthy to ACTIVE) isn't reported.

Freshness. Each change says where it came from and which game it applies to:

• source: espn (ESPN's injury feed, polled every 2 minutes), espn-roster (ESPN team rosters, checked daily; offensive linemen), sleeper (the daily Sleeper cross-check) or stats-refresh (the scheduled refresh). Older changes from the scheduled refresh have null.
• game_id and game_kickoff_utc: the player's team's next game that hadn't kicked off at detected_at (the same game_id as /schedule), or null if the team has no game left.
• team_freshness (top level, one entry per team, or just the team you filter on): last_checked_at is the last good poll of ESPN's injury feed that listed the team, and espn_updated_at is the newest update ESPN made to any of that team's entries. last_checked_at at the top level tells a quiet feed from a stale one.

Query Parameters

curl -H "x-api-key: YOUR_PRO_KEY" \
  "https://api.gridirondata.com/api/v1/injuries/changes?since=2026-09-27T16:00:00Z"

{
  "season": "2026",
  "since": "2026-09-27T16:00:00Z",
  "until": "2026-09-27T17:05:41Z",
  "count": 1,
  "changes": [
    {
      "player_id": "Josh Allen#QB",
      "player_name": "Josh Allen",
      "position": "QB",
      "team": "BUF",
      "previous_status": "QUESTIONABLE",
      "status": "OUT",
      "previous_status_raw": "Questionable",
      "status_raw": "Out",
      "detected_at": "2026-09-27T16:55:12Z",
      "source": "espn",
      "game_id": "401772938",
      "game_kickoff_utc": "2026-09-27T17:00:00Z"
    }
  ],
  "next_since": "2026-09-27T16:55:12Z",
  "last_checked_at": "2026-09-27T17:04:02Z",
  "team_freshness": {
    "BUF": {"last_checked_at": "2026-09-27T17:04:02Z", "espn_updated_at": "2026-09-27T16:54Z"}
  },
  "truncated": false
}

GET Get Depth Charts

Every team's depth chart as of this morning's nflverse refresh (as_of is the snapshot time). Each entry has the player, our player_id when the player is in /players (most defenders aren't), espn_id, gsis_id, the depth chart position, formation, slot and rank (1 = starter). The starting QB for every team is one call: ?position=QB&starters=true.

nflverse builds these from public depth charts (ESPN-sourced since 2025). They are not official team depth charts, and a change late in the week shows up the morning after nflverse picks it up. For who is actually out, use /injuries/changes.

Query Parameters

curl -H "x-api-key: YOUR_PRO_KEY" \
  "https://api.gridirondata.com/api/v1/depth-charts?position=QB&starters=true"

{
  "season": "2026",
  "as_of": "2026-11-01T07:02:30Z",
  "loaded_at": "2026-11-01T08:00:41Z",
  "count": 32,
  "entries": [
    {
      "team": "BUF",
      "player_name": "Josh Allen",
      "player_id": "Josh Allen#QB",
      "espn_id": "3918298",
      "gsis_id": "00-0034857",
      "position": "QB",
      "position_name": "Quarterback",
      "formation": "3WR 1TE",
      "slot": 9,
      "rank": 1,
      "as_of": "2026-11-01T07:02:30Z"
    }
  ],
  "note": "Depth charts as of the daily nflverse refresh (as_of). ...",
  "source": "Depth charts, inactives and player ids: nflverse (github.com/nflverse/nflverse-data), CC-BY-4.0."
}

GET Get Official Inactives

The NFL's official game-day inactive list by week and team, with gsis, ESPN, Sleeper and PFR ids. It is published after the games, usually several days later (nflverse's weekly roster file), so it is for audit and backtesting: checking what a model assumed against who actually sat. It is not a pre-kickoff feed; for game-day decisions use /injuries/changes or webhooks.

A week fills in as teams are published. teams_published is how many teams have inactives listed so far, and teams_played how many teams' games that week are final; the week is complete when they match.

Query Parameters

curl -H "x-api-key: YOUR_PRO_KEY" \
  "https://api.gridirondata.com/api/v1/inactives?week=2&team=CIN"

{
  "season": "2026",
  "week": 2,
  "team": "CIN",
  "count": 7,
  "inactives": [
    {
      "season": "2026", "week": 2, "game_type": "REG", "team": "CIN",
      "player_name": "Josh Johnson", "player_id": "Josh Johnson#QB",
      "position": "QB", "jersey_number": "11",
      "gsis_id": "00-0026300", "espn_id": "11394", "sleeper_id": "260", "pfr_id": "JohnJo05"
    }
  ],
  "teams_published": 1,
  "teams_played": 1,
  "weeks_available": [1, 2, 3, 4, 5, 6, 7, 8],
  "loaded_at": "2026-11-01T08:00:41Z",
  "note": "Official NFL game-day inactives, published after the games (usually days later) ...",
  "source": "Depth charts, inactives and player ids: nflverse (github.com/nflverse/nflverse-data), CC-BY-4.0."
}

GET Get Prop Probability

The probability a player goes over or under a stat line, with fair (no-vig) American odds to compare against the book's price. How it works:

• Mean: the player's season projection per game, shrunk toward his own average this season. The projection counts as 6 games, so by mid-season his own games carry about half the weight.
• Spread: variance proportional to the mean, fitted per position and stat on every 2025–26 game by players with a real role. Receptions, receiving yards and rushing yards use a right-skewed (gamma) distribution, since a few big games pull their average above a typical game; passing stats and rush attempts are normal; touchdowns and interceptions are Poisson.
• Track record: every response includes the stat's walk-forward backtest (each week predicted from earlier weeks only, at lines from 0.6× to 1.4× the player's mean): its Brier score and log loss, the Brier score of always guessing the base rate, and a calibration table.

Players on bye or unavailable (OUT, IR, ...) get p_over 0. The response also has the week's game, its betting line and the team's implied points. This is a model estimate, not betting advice.

Query Parameters

curl -H "x-api-key: YOUR_PRO_KEY" \
  "https://api.gridirondata.com/api/v1/props?player_id=Drake%20Maye%23QB&stat=pass_yds&line=245.5"

{
  "player_id": "Drake Maye#QB",
  "espn_player_id": 4431452,
  "team": "NE",
  "week": 8,
  "stat": "pass_yds",
  "injury_status": "ACTIVE",
  "available": true,
  "game": {"opponent": "NYJ", "home": true, "implied_team_points": 26.5, "odds": {"...": "..."}},
  "projection": {
    "mean": 249.3,
    "sd": 58.1,
    "distribution": "normal",
    "season_projection_per_game": 239.03,
    "games_played": 7,
    "season_average": 262.4
  },
  "lines": [
    {"line": 245.5, "p_over": 0.526, "p_under": 0.474, "p_push": 0,
     "fair_odds_over": -111, "fair_odds_under": 111}
  ],
  "model": {"k": 26.5, "backtest": {"n": 2135, "brier": 0.172, "brier_base_rate": 0.25, "calibration": ["..."]}},
  "disclaimer": "Model estimate, not betting advice. ..."
}

GET Get Defense vs Position

What each defense allows per game to QBs, RBs, WRs and TEs: fantasy points plus the stats behind them (passing and rushing yards and TDs, receptions, receiving yards, targets). rank 1 allows the most fantasy points per game, the best matchup for that position.

Query Parameters

curl -H "x-api-key: YOUR_PRO_KEY" \
  "https://api.gridirondata.com/api/v1/defense?position=WR&last=4"

{
  "season": "2026",
  "scoring": "ppr",
  "weeks": [4, 5, 6, 7],
  "position": "WR",
  "defenses": [
    {
      "team": "MIA",
      "rank": 1,
      "games": 4,
      "fantasy_points_allowed_per_game": 46.2,
      "per_game": {"targets": 24.5, "rec": 16.8, "rec_yds": 221.3, "rec_td": 1.5}
    }
  ],
  "rank_meaning": "1 = allows the most fantasy points per game to this position",
  "source": "ESPN box scores"
}

GET Get Target Share and Carry Share

A player's weekly usage: his targets against his team's targets (target_share_pct) and his rush attempts against his team's rush attempts (carry_share_pct), with receptions, receiving yards and snap share, plus season totals, a trailing window and the trend between them. Team totals count every player with a line in the box score, and a week he played without a target or carry counts as 0. From ESPN box scores, 2025 onward. Shares are 0–100.

Query Parameters

curl -H "x-api-key: YOUR_PRO_KEY" \
  "https://api.gridirondata.com/api/v1/usage?player_id=CeeDee%20Lamb%23WR&trend=4"

{
  "player_id": "CeeDee Lamb#WR",
  "season": "2026",
  "season_totals": {"games": 7, "targets": 63, "team_targets": 245,
                    "target_share_pct": 25.7, "carry_share_pct": 1.1},
  "recent": {"games": 4, "targets": 40, "team_targets": 140,
             "target_share_pct": 28.6, "trend_weeks": 4},
  "trend_delta": {"target_share_pct": 2.9, "carry_share_pct": 0.0},
  "weekly_usage": [
    {"week": 7, "team": "DAL", "opponent": "WAS", "targets": 11, "team_targets": 36,
     "target_share_pct": 30.6, "rec": 8, "rec_yds": 104, "rush_att": 0,
     "team_rush_att": 24, "carry_share_pct": 0.0, "snap_pct": 91.2}
  ],
  "source": "ESPN box scores; snap share from nflverse / Pro-Football-Reference"
}

POST Register or update the webhook

Body: {"url": "https://example.com/gridiron"}. The URL must use HTTPS on port 443 and resolve to public IP addresses; private, loopback, link-local and cloud metadata addresses are refused with 400 "reason": "invalid_url". The first registration answers 201 with a signing_secret (whsec_…). It is shown only once, so store it. Updating the URL keeps the secret and re-enables a disabled webhook.

GET /webhooks returns the webhook (URL, status, last delivery, a secret_hint), never the secret. DELETE /webhooks removes it. POST /webhooks/secret replaces the signing secret and shows the new one once; the old one stops working at once. POST /webhooks/test sends a "type": "test" event right away and returns delivered, status_code and duration_ms (one every 10 seconds).

curl -X POST -H "x-api-key: YOUR_PRO_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/gridiron"}' \
  "https://api.gridirondata.com/api/v1/webhooks"

What we send

A POST with Content-Type: application/json and these headers: X-GridIron-Event (injury.changes or test), X-GridIron-Event-Id, X-GridIron-Timestamp (unix seconds) and X-GridIron-Signature. The changes have the polling feed's core fields, including source (null on older changes); previous_status and status carry the source spelling (the polling feed's *_raw values). A run with more than 250 changes is split into numbered parts. Event ids are stable, so use them to drop a duplicate.

{
  "id": "evt_3f1c2a9b8d7e6f5a4b3c2d1e",
  "type": "injury.changes",
  "created_at": "2026-10-25T17:00:09Z",
  "season": "2026",
  "detected_at": "2026-10-25T17:00:05Z",
  "count": 1,
  "part": 1,
  "parts": 1,
  "changes": [
    {
      "player_id": "Josh Allen#QB",
      "player_name": "Josh Allen",
      "position": "QB",
      "team": "BUF",
      "previous_status": "Questionable",
      "status": "Out",
      "detected_at": "2026-10-25T17:00:05Z",
      "source": "espn"
    }
  ]
}

Delivery rules. Answer with any 2xx within 5 seconds. Timeouts, connection errors, 408, 429 and 5xx are retried twice, after 1 and 4 seconds; other 4xx answers aren't retried. Redirects aren't followed. After 5 failed deliveries in a row the webhook is disabled; fix the endpoint, then save the URL again on your dashboard to turn it back on. Pushes stop while a plan is paused or no longer Pro.

Verify the signature

X-GridIron-Signature is sha256= followed by the hex HMAC-SHA256 of <X-GridIron-Timestamp>.<raw request body>, keyed with your signing secret. Compute it over the raw bytes before parsing the JSON, compare in constant time, and reject old timestamps to block replays.

import hashlib, hmac, time

def verify(secret, headers, raw_body):
    ts = headers["X-GridIron-Timestamp"]
    if abs(time.time() - int(ts)) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{ts}.".encode() + raw_body,
                        hashlib.sha256).hexdigest()
    return hmac.compare_digest("sha256=" + expected, headers["X-GridIron-Signature"])

GET Get vs Opponent History

Get historical performance data for a player against a specific opponent.

Path Parameters

Alternative: Query by name and position:

curl -H "x-api-key: YOUR_KEY" \
  "https://api.gridirondata.com/api/v1/matchups/Josh%20Allen%23QB/KC"

GET Get the Schedule

Games sorted by week, then kickoff. status is scheduled, in_progress or final; home_score and away_score are null until the game is final. Scores are updated after each week's games. With team, the response adds that team's bye_week.

Betting lines (Pro). On Pro keys, each game has odds once a line is posted (DraftKings, via the ESPN scoreboard): spread_home (negative when the home team is favored), over_under, both moneylines and each team's implied points, (over_under − spread_home) / 2 for the home team. Lines are refreshed daily until kickoff and kept afterwards, so a final game shows the last line before kickoff. odds is null when no line was captured. Basic keys get the schedule without odds, and a top-level odds note says lines need Pro.

Query Parameters

curl -H "x-api-key: YOUR_KEY" \
  "https://api.gridirondata.com/api/v1/schedule?season=2026&week=8&team=GB"

{
  "season": "2026",
  "count": 1,
  "games": [
    {
      "week": 8,
      "game_id": "401873023",
      "kickoff_utc": "2026-10-30T00:15:00Z",
      "home": "GB",
      "away": "CAR",
      "status": "scheduled",
      "home_score": null,
      "away_score": null,
      "odds": {
        "provider": "DraftKings",
        "spread_home": -3.0,
        "over_under": 47.5,
        "home_moneyline": -155,
        "away_moneyline": 130,
        "implied_home_points": 25.25,
        "implied_away_points": 22.25,
        "captured_at": "2026-10-23T14:00:05Z"
      }
    }
  ],
  "updated_at": "2026-10-23T14:00:05Z",
  "source": "ESPN scoreboard",
  "week": 8,
  "team": "GB",
  "bye_week": 5
}

GET Get Bye Weeks

Each team's bye week, plus the teams on bye in each week. season defaults to the current season.

curl -H "x-api-key: YOUR_KEY" \
  "https://api.gridirondata.com/api/v1/byes?season=2026"

{
  "season": "2026",
  "byes": {"ARI": 14, "ATL": 11, "BAL": 13, "BUF": 7, ...},
  "by_week": {"5": ["CAR", "KC"], "6": ["CIN", "DET", "MIA", "MIN"], ...},
  "source": "ESPN scoreboard"
}

GET Health Check

Check API status and version.

{
  "status": "healthy",
  "version": "1.0.0",
  "default_season": "2026"
}