Guide
Dynasty and off-season research with seven seasons of data
Quick answer: /players returns every season a player has (2020 through 2026) in the same row, so one sweep of RBs, WRs and TEs (about 14 requests) is a complete dynasty database. The most useful thing to measure is whether a role jump sticks. In our data it usually does: 34 players gained 15+ points of snap share from 2023 to 2024 (+4.0 PPR per game), and 23 of the 31 who played 8+ games in 2025 kept the role, with their scoring gain intact.
- Seasons
- 2020–2026
- Sweep
- ~14 requests
- Plan
- Basic
- Role jumps kept
- 23 of 31
What data is there for dynasty and off-season research?
Every weekly stat line and every weekly snap share since 2020, plus the current season. On a /players row, seasons is keyed by year, and each year carries weekly_stats (points by scoring format and the opponent) and snap_counts.weekly (offensive snap share, 0–100). For one player, /stats/{player_id}/{season} returns the same weeks with snap_pct joined on.
Age and draft capital are there too. Every /players row carries a career map: draft year, round, pick and team, age at the draft, college, birth date and rookie season (from nflverse), plus age and years_in_league worked out when you ask. What isn't there is the contract. The career profile section below shows the one-request version.
Two data details will save you an hour. First, 2025 weekly rows carry a single fantasy_points value, while other seasons break out fantasy_points_ppr and _half; read fantasy_points_ppr, then fall back to points and fantasy_points, as the code below does. Second, some seasons have no season_totals block, so sum the weekly rows yourself instead of trusting the totals to be there.
How do I pull one player's career arc?
One /stats call per season. This prints games, PPR per game and average snap share for every season a player has, and skips the years before he entered the league:
import os
from urllib.parse import quote
import requests
API = "https://api.gridirondata.com/api/v1"
H = {"x-api-key": os.environ.get("GRIDIRON_API_KEY", "YOUR_KEY")}
def career(player_id, seasons=range(2020, 2027)):
"""One /stats call per season: games, PPR per game and snap share."""
rows = []
for season in seasons:
r = requests.get(f"{API}/stats/{quote(player_id)}/{season}", headers=H, timeout=30)
if r.status_code == 404:
continue # not in the league yet
r.raise_for_status()
weeks = r.json().get("weekly_stats") or {}
pts = [w["points"] for w in weeks.values() if w.get("points") is not None]
snaps = [w["snap_pct"] for w in weeks.values() if w.get("snap_pct")]
if pts:
rows.append((season, len(pts), sum(pts) / len(pts),
sum(snaps) / len(snaps) if snaps else None))
return rows
for season, games, ppg, snap in career("Trey McBride#TE"):
snap_txt = " -" if snap is None else f"{snap:3.0f}%"
print(f"{season} {games:2d} games {ppg:5.1f} PPR/g snaps {snap_txt}")
Trey McBride, from a run on November 20, 2026 (the 2026 row is ten games deep; yours will have the full season):
2022 12 games 5.1 PPR/g snaps 68%
2023 17 games 10.7 PPR/g snaps 69%
2024 16 games 15.2 PPR/g snaps 90%
2025 17 games 18.6 PPR/g snaps 91%
2026 10 games 17.1 PPR/g snaps 90%
This is the dynasty shape you want to find early. The role came first: 90% of snaps in 2024, the year his scoring jumped from 10.7 to 15.2 PPR a game. Then the production kept climbing on a flat, full-time share, to 18.6 in 2025, and it has held near there (17.1) through ten games of 2026. A player whose snaps are at 90% is no longer waiting for opportunity. His value from there is efficiency and target share, not role.
Can I get age, draft slot and the season totals in one request?
Yes. GET /players/{player_id}/career (Basic) returns the player's career profile and his fantasy points season by season, with games, points per game and career totals, in the scoring you ask for:
r = requests.get(f"{API}/players/{quote('Trey McBride#TE')}/career",
headers=H, params={"scoring": "ppr"}, timeout=30)
career = r.json()
print(career["profile"])
for s in career["seasons"]:
print(s["season"], s["games"], s["points"], s["points_per_game"])
McBride's profile, from nflverse's player and draft-pick files: drafted in 2022, round 2, pick 55, by Arizona, out of Colorado State, at 22. Born November 22, 1999, so 26 on the day we wrote this, in his fifth season. That puts the arc above in context: he reached a full-time role in his third season, at 24.
profile holds drafted, draft_year, draft_round, draft_pick (overall), draft_team, age_at_draft, college, birth_date, rookie_season, age and years_in_league (his rookie season through the current one, both counted). The same career map rides on every /players row, so the league-wide sweep below already has age and draft slot for every player, with no extra requests. Each season row says whether its total came from the stored season totals or the sum of its weekly rows (points_from). A season whose weekly rows hold one points value for every scoring, as 2025's do, carries a scoring_note.
Do role gains stick from one season to the next?
This is the question that decides most dynasty trades: is last year's breakout a new baseline or a one-year spike? Snap share answers it better than points, because a coach's role decision is more persistent than a touchdown rate. Here's a league-wide test: find everyone whose snap share jumped 15+ points from one season to the next, then check whether they held it the season after.
import os, statistics
import requests
API = "https://api.gridirondata.com/api/v1"
H = {"x-api-key": os.environ.get("GRIDIRON_API_KEY", "YOUR_KEY")}
Y0, Y1, Y2 = "2023", "2024", "2025" # baseline, the jump, the year after
def sweep(position):
out, cursor = [], None
while True:
params = {"position": position, "limit": 100, **({"cursor": cursor} if cursor else {})}
r = requests.get(f"{API}/players", headers=H, params=params, timeout=60)
r.raise_for_status()
body = r.json()
out += body["players"]
cursor = body.get("next_cursor")
if not cursor:
return out
def ppr(row):
for k in ("fantasy_points_ppr", "points", "fantasy_points"):
if row and row.get(k) is not None:
return float(row[k])
return None
def season_line(p, season, min_games=8):
"""(PPR per game, snap share) for one season, or None under min_games."""
block = p.get("seasons", {}).get(season) or {}
pts = [x for x in map(ppr, (block.get("weekly_stats") or {}).values()) if x is not None]
snaps = [r["offense_pct"] for r in ((block.get("snap_counts") or {}).get("weekly") or {}).values()
if r.get("offense_pct")]
if len(pts) < min_games or len(snaps) < min_games:
return None
return sum(pts) / len(pts), sum(snaps) / len(snaps)
jumpers = []
for pos in ("RB", "WR", "TE"): # ~14 requests for all three
for p in sweep(pos):
a, b = season_line(p, Y0), season_line(p, Y1)
if a and b and b[1] - a[1] >= 15: # +15 points of snap share
jumpers.append((p["player_name"], pos, a, b, season_line(p, Y2)))
print(f"{len(jumpers)} players gained 15+ points of snap share from {Y0} to {Y1}; "
f"PPR/g {statistics.mean(b[0] - a[0] for _, _, a, b, _ in jumpers):+.1f}")
after = [j for j in jumpers if j[4]]
held = [j for j in after if j[4][1] >= j[3][1] - 10]
print(f"{len(after)} played 8+ games in {Y2}: {len(held)} kept the role (within 10 points); "
f"PPR/g vs {Y1}: {round(statistics.mean(c[0] - b[0] for *_, b, c in after), 1) + 0.0:+.1f}")
print(f"Biggest jumps: snap share {Y0} -> {Y1} -> {Y2} (snaps / PPR per game)")
for name, pos, a, b, c in sorted(jumpers, key=lambda j: j[3][1] - j[2][1], reverse=True)[:8]:
tail = f"{c[1]:3.0f}% / {c[0]:4.1f}" if c else " -"
print(f" {name:<22}{pos} snaps {a[1]:3.0f}% -> {b[1]:3.0f}% -> {tail}")
The output from a real run, 2023 → 2024 → 2025:
34 players gained 15+ points of snap share from 2023 to 2024; PPR/g +4.0
31 played 8+ games in 2025: 23 kept the role (within 10 points); PPR/g vs 2024: +0.0
Biggest jumps: snap share 2023 -> 2024 -> 2025 (snaps / PPR per game)
Ray-Ray McCloud III WR snaps 30% -> 85% -> -
Tre Tucker WR snaps 33% -> 87% -> 95% / 10.1
Andrei Iosivas WR snaps 26% -> 78% -> 76% / 6.1
Chase Brown RB snaps 13% -> 63% -> 67% / 16.6
Sterling Shepard WR snaps 15% -> 53% -> 56% / 6.0
Demarcus Robinson WR snaps 44% -> 82% -> 47% / 4.5
Jalen Tolbert WR snaps 40% -> 76% -> 51% / 8.2
Rico Dowdle RB snaps 22% -> 58% -> 56% / 12.7
Three quarters of the role jumpers held their role, and the group kept every bit of its +4.0 PPR per game gain. The misses are instructive too. Demarcus Robinson went 44% → 82% → 47% after moving from the Rams to the 49ers. Jalen Tolbert went 40% → 76% → 51% without changing teams. When a role jump reverses, check the depth chart before you blame the player.
The same pattern shows up in simple year-over-year correlations. Across RBs, WRs and TEs with 8+ games in consecutive seasons, snap share correlated at 0.63 to 0.80 from one year to the next (2023–24 and 2024–25), about as sticky as PPR per game (0.68 to 0.79). The difference is timing. Snap share moves first, often mid-season, which is exactly when a dynasty manager can still buy.
What should I run this off-season?
- Re-run the stickiness test on the newest seasons. Set
Y0, Y1, Y2 = "2024", "2025", "2026". The 2025 jumpers who held their role through 2026 are the ones with a track record. The 2026 jumpers are next year's buy-or-sell question. - List full-time players with flat production. 85%+ of snaps and PPR per game that hasn't moved in two seasons is a ceiling, not a trend. Those are sell candidates if your league still pays for the name.
- Screen for early-career role jumps. A player whose snap share jumps 20+ points in his second or third season is the shape to look for: McBride went from 69% to 90% in his third year, and his scoring rose 4.5 PPR a game with it.
- Watch committee backfields across years. The handcuffs and committees guide counts committee weeks per team. A back who ends a season leading a committee is often next year's workhorse, or next year's timeshare.
For the mid-season version of the same idea, the snap share guide shows how Amon-Ra St. Brown's role showed up weeks before his 2021 breakout did.
How many requests does it cost?
The stickiness study is about 14 requests, one sweep of RBs (4 pages), WRs (6) and TEs (4) with every season attached. A single career arc is one request per season: 7 for 2020 through 2026, including the two 404s for seasons before McBride's rookie year. Save the sweep to a JSON file and every other off-season question you ask is free. The off-season is also when the data is still: stats land about 11:00 am ET the day after games during the season, and between seasons the historical rows don't change, so one pull lasts all spring. More tools are in the guides, and every field is in the API reference.
Frequently asked questions
Which seasons does the API cover?
Actuals from 2020 through 2026, and snap share for the same seasons. Each /players row carries a block per season, so one sweep returns every season a player has, with no extra requests.
Does the API include player age or draft position?
Yes. Every /players row carries a career map with draft year, round, pick and team, age at the draft, college, birth date, rookie season, age and years in the league, from nflverse. GET /players/{player_id}/career (Basic) adds fantasy points season by season from 2020.
Do snap-share gains carry over to the next season?
Mostly, in our data. Of 31 skill players who gained 15+ points of snap share from 2023 to 2024 and played 8+ games in 2025, 23 kept the role within 10 points, and as a group they kept their scoring gain.
How many requests does an off-season study take?
About 14 for every running back, wide receiver and tight end with all their seasons attached, or one /stats call per season for a single player's career. Both take Basic ($9/month, 5,000 requests a month): past seasons, stats and snap rows are not on the free plan.