NFL GraphQL Reference

Primary Key

First day of the season (typically the start of preseason in early August).

Last day of the season (Super Bowl date or shortly after).

Calendar year in which the season starts (e.g., 2025 = the 2025-26 season).

First day of regular-season play (typically the Thursday after Labor Day).

First day of the postseason (Wild Card weekend).

Date of the Super Bowl for this season.

Number of regular-season weeks (18 since 2021; 17 in 2020 and earlier).

Primary Key

Three-letter team code (e.g., KC, NE, GB).

Official NFL team UUID from api.nfl.com

Conference assignment (AFC or NFC).

Division within the conference (e.g., AFC East, NFC West).

True for currently-active franchises; false for relocated or defunct teams retained for historical references.

Primary home stadium (FK to stadiums); null if unknown or shared.

URL to team logo image

Hex color code for the team's primary uniform color (e.g., #A71930).

Hex color code for the team's secondary uniform color.

Primary Key

Official NFL player ID (UUID) from nfl.com

Jersey number with the player's current team (string to preserve leading zeros and special codes).

Game Statistics and Information System ID (e.g. 00-0028830)

Primary roster position (e.g., QB, WR, RB, CB).

Broad position group classification used by nflverse (e.g., OFFENSE, DEFENSE, ST).

All positions the player is eligible at (semicolon-joined when multiple, e.g., RB;WR).

Current NFL team (FK to teams); null for free agents and retired players.

URL slug used on nfl.com (e.g., patrick-mahomes).

Height in inches.

Weight in pounds.

College or last football affiliation before turning pro.

Years of NFL experience (rookies = 0).

Calendar year the player was drafted; null or UDFA if undrafted.

Draft round (1-7); null or UDFA if undrafted.

Pick number within the round; null or UDFA if undrafted.

Overall pick number across all rounds (1-262); null if undrafted.

Canonical roster status, shared across leagues. NFL has the richest source vocabulary. The "on a team now" set is {active, injured_reserve, practice_squad, reserve, suspended}; free_agent/waived/retired/inactive are off-roster.

URL to player profile picture image

True for synthetic team-level entities (DST, team defense). Used to distinguish team defense 'players' from individual players.

Primary Key

Scheduled kickoff time (timezone-aware).

Official NFL game ID from league source

Game classification (Regular, Playoff, Super Bowl, Preseason).

Game status. Currently always Scheduled (status reconciliation is pending) — detect completed games via populated scores, not this field.

Actual kickoff timestamp; null before the game starts.

Actual game end timestamp; null until the game completes.

Canonical season phase. Postseason round detail (Wild Card / Divisional / Conference Championship / Super Bowl) lives in playoff_round.

Week number within the season stage — 1-18 for regular season, restarting at 1 in the postseason (1 Wild Card, 2 Divisional, 3 Conference Championship, 4 Super Bowl). Note nfl.injuries.week uses the continuous 19-22 convention instead.

Calendar day as a YYYYMMDD integer (e.g. 20240915), US Eastern.

Denormalized team abbreviation for the away side at game time (snapshot copy of teams.abbreviation).

Denormalized team abbreviation for the home side at game time (snapshot copy of teams.abbreviation).

Stadium hosting the game (FK to stadiums).

Primary broadcast network/channel (e.g., CBS, FOX, Prime Video).

Reported attendance count; null when not published.

Final away-team score; 0 (not null) until the game completes.

Final home-team score; 0 (not null) until the game completes.

Sportsbook rotation number for the home team (3-4 digit cross-book reference).

Sportsbook rotation number for the away team (3-4 digit cross-book reference).

True if the game is played at a neutral site (Super Bowl, international games, etc.).

Postseason round (WildCard, Divisional, Conference Championship, Super Bowl); null outside the postseason.

Home-team playoff seed (1-7); null outside the postseason.

Away-team playoff seed (1-7); null outside the postseason.

Display label for special games (e.g., Thanksgiving Day, Monday Night Football).

Secondary label or sub-category for the game.

Reason for postponement (e.g., Weather, COVID); null for games played as scheduled.

True if the game went to overtime.

Number of overtime periods played (1+ when overtime is true).

Primary Key

Team with possession (FK to teams)

Drive sequence number in game (1-indexed)

Corrected drive number from nflverse

Quarter when drive started

Quarter when drive ended

How possession was gained (KICKOFF, PUNT, TURNOVER, etc.)

How possession ended (PUNT, TOUCHDOWN, TURNOVER, etc.)

Drive outcome (Touchdown, Field goal, Punt, Turnover, etc.)

Starting field position (e.g., "KC 25")

Ending field position (e.g., "OPP 10")

Game clock at drive start (mm:ss)

Game clock at drive end (mm:ss)

Drive duration (mm:ss format)

Number of plays in drive

First downs gained

Penalty yards on drive

Drive reached red zone

Drive resulted in points

play_id of first play in drive

play_id of last play in drive

Primary Key

Numeric play identifier unique to game

FK to games table

Ten digit identifier for NFL game (nflverse format)

Legacy NFL game ID format

UUID from NFL API

Quarter (1-4, 5=OT)

Seconds remaining in quarter

Seconds remaining in half

Seconds remaining in game

Half1, Half2, or Overtime

Binary quarter-end marker

Game clock at play start (mm:ss)

Play clock at snap

Kickoff time (eastern)

Play time in UTC

Game clock at play end

NFL play-ordering column

Home team abbreviation

Away team abbreviation

Possession team abbreviation

home or away

Defensive team abbreviation

FK to teams table for possession team

FK to teams table for defensive team

Team abbreviation whose side of field

Yards from opponent endzone (0-100)

Yard line string (e.g., "KC 25")

Yard line number (0-50)

Yard line at play end

Down (1-4)

Yards to first down/goal

Goal-to-go situation

Total net yards on drive

Drive number in game

FK to game_drives table

Manual drive number correction

Manual drive result correction

Scoring play indicator

Drive start time (real clock)

Number of plays in drive

Drive time of possession (mm:ss)

First downs gained in drive

Drive reached red zone

Drive resulted in score

Quarter when drive started

Quarter when drive ended

Penalty yards during drive

How possession was obtained

How drive ended

Game clock at drive start

Game clock at drive end

Yard line at drive start

Yard line at drive end

First play_id of drive

Last play_id of drive

Series counter within game

Series resulted in first down or TD

First down, Touchdown, Punt, etc.

Full play description text

pass, run, punt, field_goal, kickoff, extra_point, qb_kneel, qb_spike, no_play

NFL source play type

Special teams play indicator

Type of special teams play

Regular play (1) vs special event (0)

Special teams indicator

Play was aborted

Play was deleted

Shotgun formation

No-huddle offense

QB dropback (pass or scramble)

Rushing play indicator

Rush play (no scrambles)

left, middle, or right

end, guard, or tackle

Yards gained on play

Official rushing yards

Rusher GSIS ID

Rusher name

Rusher jersey number

FK to players table

Lateral receiver GSIS ID (rush)

Lateral receiver name (rush)

Yards after lateral (rush)

Lateral on rush play

Pass attempt (includes sacks)

Pass play indicator

short or deep

left, middle, or right

Yards in air (perpendicular to LOS)

YAC yards

Pass completed

Pass incomplete

Official passing yards

Passer GSIS ID

Passer name

Passer jersey number

FK to players table

Dropback player name (includes scrambles)

Receiver GSIS ID

Receiver name

Receiver jersey number

FK to players table

Targeted receiver name

Official receiving yards

Lateral receiver GSIS ID (pass)

Lateral receiver name (pass)

Yards after lateral (pass)

Lateral on pass play

QB scramble

QB kneel

QB spike

QB was hit

QB hitter GSIS ID

QB hitter name

Second QB hitter GSIS ID

Second QB hitter name

Sack indicator

Sacker GSIS ID

Sacker name

Half-sack player 1 GSIS ID

Half-sack player 1 name

Half-sack player 2 GSIS ID

Half-sack player 2 name

Lateral after sack GSIS ID

Lateral after sack name

Interception indicator

Interceptor GSIS ID

Interceptor name

Lateral after INT GSIS ID

Lateral after INT name

Fumble occurred

Fumble was forced

Fumble was not forced

Fumble went OOB

Fumble was lost

First fumbler GSIS ID

First fumbler name

First fumbler team

Second fumbler GSIS ID

Second fumbler name

Second fumbler team

Recovery team 1

Recovery yards 1

Recovery player 1 GSIS ID

Recovery player 1 name

Recovery team 2

Recovery yards 2

Recovery player 2 GSIS ID

Recovery player 2 name

Forced fumble team 1

Forced fumble player 1 GSIS ID

Forced fumble player 1 name

Forced fumble team 2

Forced fumble player 2 GSIS ID

Forced fumble player 2 name

Solo tackle on play

Solo tackler 1 GSIS ID

Solo tackler 1 name

Solo tackler 1 team

Solo tackler 2 GSIS ID

Solo tackler 2 name

Solo tackler 2 team

Assist tackle on play

Assist tackler 1 GSIS ID

Assist tackler 1 name

Assist tackler 1 team

Assist tackler 2 GSIS ID

Assist tackler 2 name

Assist tackler 2 team

Assist tackler 3 GSIS ID

Assist tackler 3 name

Assist tackler 3 team

Assist tackler 4 GSIS ID

Assist tackler 4 name

Assist tackler 4 team

Tackle with assistance

Tackle-assist player 1 GSIS ID

Tackle-assist player 1 name

Tackle-assist player 1 team

Tackle-assist player 2 GSIS ID

Tackle-assist player 2 name

Tackle-assist player 2 team

Tackle for loss

TFL player 1 GSIS ID

TFL player 1 name

TFL player 2 GSIS ID

TFL player 2 name

Pass defense player 1 GSIS ID

Pass defense player 1 name

Pass defense player 2 GSIS ID

Pass defense player 2 name

Field goal attempt

made, missed, or blocked

Kick distance in yards

Kicker GSIS ID

Kicker name

Blocked kick player GSIS ID

Blocked kick player name

Extra point attempt

good, failed, blocked, safety, aborted

Two-point conversion attempt

success, failure, safety, return

Defense two-point attempt

Defense two-point conversion success

Defense extra point attempt

Defense extra point success

Kickoff attempt

Kickoff returner GSIS ID

Kickoff returner name

Kickoff inside 20

Kickoff in endzone

Kickoff OOB

Kickoff downed

Kickoff fair catch

Lateral kickoff returner GSIS ID

Lateral kickoff returner name

Own kickoff recovery

Own kickoff recovery TD

Own kickoff recovery player GSIS ID

Own kickoff recovery player name

Punt attempt

Punter GSIS ID

Punter name

Punt returner GSIS ID

Punt returner name

Punt blocked

Punt inside 20

Punt in endzone

Punt OOB

Punt downed

Punt fair catch

Lateral punt returner GSIS ID

Lateral punt returner name

Returning team

Return yards

Lateral on return

Touchdown scored

Passing touchdown

Rushing touchdown

Return touchdown

Team scoring TD

TD scorer name

TD scorer GSIS ID

Safety scored

Safety scorer name

Safety scorer GSIS ID

Touchback

Ran/pushed/sacked out of bounds

First down achieved

Rushing first down

Passing first down

First down via penalty

Third down conversion

Third down failure

Fourth down conversion

Fourth down failure

Penalty on play

Penalized team

Penalized player GSIS ID

Penalized player name

Penalty yards

Type of penalty

Replay/challenge occurred

Replay result

Timeout called

Team calling timeout

Home timeouts remaining

Away timeouts remaining

Possession team timeouts

Defensive team timeouts

Home score at play start

Away score at play start

Possession team score at start

Defense team score at start

Score gap at play start

Possession team score at end

Defense team score at end

Score gap at play end

Total home points

Total away points

Probability of no score

Opponent FG probability

Opponent safety probability

Opponent TD probability

FG probability

Safety probability

TD probability

Extra point probability

Two-point conversion probability

Expected points before play

Expected points added

Cumulative home EPA

Cumulative away EPA

Cumulative home rushing EPA

Cumulative away rushing EPA

Cumulative home passing EPA

Cumulative away passing EPA

EPA from air yards

EPA from yards after catch

Completion air EPA

Completion YAC EPA

Cumulative home completion air EPA

Cumulative away completion air EPA

Cumulative home completion YAC EPA

Cumulative away completion YAC EPA

Cumulative home raw air EPA

Cumulative away raw air EPA

Cumulative home raw YAC EPA

Cumulative away raw YAC EPA

QB EPA credit

Expected EPA after catch

Average expected YAC

Median expected YAC

Positive EPA probability

First down probability (xYAC)

Win probability for possession team

Win probability for defense

Home team win probability

Away team win probability

Win probability added

Vegas-adjusted WPA

Vegas home WPA

Home WP after play

Away WP after play

Vegas win probability

Vegas home win probability

Cumulative home rushing WPA

Cumulative away rushing WPA

Cumulative home passing WPA

Cumulative away passing WPA

WPA from air yards

WPA from yards after catch

Completion air WPA

Completion YAC WPA

Cumulative home completion air WPA

Cumulative away completion air WPA

Cumulative home completion YAC WPA

Cumulative away completion YAC WPA

Cumulative home raw air WPA

Cumulative away raw air WPA

Cumulative home raw YAC WPA

Cumulative away raw YAC WPA

Completion probability

Completion percentage over expected

Dropback probability

Dropback percent over expected

Play success (based on down/distance)

Primary player name (passer or rusher)

Primary player jersey

Primary player GSIS ID

Fantasy designation player name

Fantasy designation player ID

Fantasy designation

Fantasy identifier

Stadium name

Stadium ID

Game stadium name

Home or Neutral

dome, outdoors, closed, open

Playing surface type

Temperature

Wind speed (mph)

Weather conditions description

Home team head coach

Away team head coach

Division game

Vegas spread line

Vegas total line

Home score - Away score

Home score + Away score

Home team had opening kickoff

Primary Key

Play identifier matching play_by_plays.play_id for the same game.

Team in possession on this play (FK to teams).

Offensive formation alignment (e.g., SHOTGUN, SINGLEBACK, I_FORM, PISTOL).

Offensive personnel grouping in RB-TE-WR shorthand (e.g., 1 RB, 2 TE, 2 WR → 12 personnel).

Number of defenders within ~8 yards of the line of scrimmage at the snap.

Defensive personnel grouping (e.g., 4 DL, 2 LB, 5 DB).

Number of defenders who rushed the passer on this play (Next Gen Stats).

GSIS IDs of every player on the field for this play (comma-separated or JSON-encoded depending on source vintage).

GSIS IDs of offensive players on the field for this play.

GSIS IDs of defensive players on the field for this play.

Count of offensive players on the field (typically 11).

Count of defensive players on the field (typically 11).

Air yards traveled by the pass from the line of scrimmage to where the receiver caught/dropped it (Next Gen Stats).

Time from snap to pass release in seconds (Next Gen Stats).

True if the quarterback faced pass-rush pressure on this play.

Route the targeted receiver ran (e.g., GO, SLANT, OUT, POST).

Man- vs. zone-coverage classification (MAN, ZONE).

Specific coverage scheme (e.g., COVER_1, COVER_2_MAN, COVER_3, COVER_4).

Primary Key

Possessions reaching the red zone (inside the opponent's 20-yard line).

Red-zone trips that ended in a touchdown.

Third-down attempts converted to a first down or touchdown.

Total third-down plays attempted.

Fourth-down attempts converted to a first down or touchdown.

Total fourth-down plays attempted (excludes punts and field-goal attempts).

Possessions lost via interception or fumble.

Sacks recorded by this team's defense (half-sacks supported as decimals).

Touchdowns scored by the defense (interception return + fumble recovery TD); excludes special-teams returns.

Primary Key

True if player's team is the home team

Player position at time of game

Position group (QB, RB, WR, TE, etc.)

Expected points added from passing

Passer air conversion ratio

DAKOTA: adjusted completion % + EPA metric

Expected points added from rushing

Expected points added from receiving

Receiver air conversion ratio

Percentage of team targets

Percentage of team air yards

Weighted opportunity rating

Standard fantasy points (nflverse calculation)

PPR fantasy points (nflverse calculation)

Passer rating

Longest pass completion (yards)

Completion percentage

Longest rush (yards)

Rushing yards per attempt

Longest reception (yards)

Yards per reception

Reception percentage (receptions/targets)

Number of punt returns

Total punt return yards

Punt return touchdowns

Longest punt return (yards)

Number of kick returns

Total kick return yards

Kick return touchdowns

Longest kick return (yards)

Solo tackles

Assisted tackles

Tackles for loss

Defensive sacks (can be half sacks)

Quarterback hits

Passes defended

Forced fumbles

Fumbles recovered

Defensive interceptions

Interception return yards

Interception return touchdowns

Safeties

Field goals made

Field goals attempted

Field goal percentage

Longest field goal made (yards)

Field goals made 0-19 yards

Field goals made 20-29 yards

Field goals made 30-39 yards

Field goals made 40-49 yards

Field goals made 50+ yards

Extra points made

Extra points attempted

Number of punts

Total punt yards

Punt average (yards)

Punts inside 20 yard line

Punt touchbacks

Longest punt (yards)

Offensive snaps played

Defensive snaps played

Special teams snaps played

Depth chart position (QB1, RB2, etc.) - joined from depth charts

Depth order within position (1=starter, 2=backup, etc.) - joined from depth charts

Total team offensive snaps (for calculating snap %)

Total team defensive snaps (for calculating snap %)

Total team special teams snaps (for calculating snap %)

Yards lost on defensive sacks

Fumble return yards

Fumble return touchdowns

Blocked kicks (FG, XP, punts)

Total defensive touchdowns (INT + fumble return TDs)

Punt return average (yards per return)

Fair catches on punt returns

Kick return average (yards per return)

Fair catches on kick returns

Blocked kick return yards

Blocked kick return touchdowns

Field goal return yards (missed FG returns)

Field goal return touchdowns

Solo tackles on special teams

Assisted tackles on special teams

Fumbles forced on special teams

Fumbles recovered on special teams

Miscellaneous solo tackles

Miscellaneous assisted tackles

Miscellaneous fumbles forced

Miscellaneous fumbles recovered

Own fumbles recovered

Fumbles out of bounds

Field goals blocked by opponent

Extra points blocked by opponent

Net punt average (gross - return yards)

Punts blocked by opponent

Net punt yards (gross - return yards)

Two-point conversion returns (defensive)

Stadium name

Playing surface type (grass, turf, etc.)

Game temperature (Fahrenheit)

Humidity percentage

Wind speed (mph)

Fumbles on punt returns (includes muffs)

Fumbles lost on punt returns

Fumbles on kick returns

Fumbles lost on kick returns

Primary Key

True if team is the home team