--- title: "List play_by_plays for NFL" method: GET path: "/api/v1/nfl/play_by_plays" tags: ["NFL"] --- # List play_by_plays for NFL `GET /api/v1/nfl/play_by_plays` ## Request - Base URL: `https://api.stat-api.com` - URL: `https://api.stat-api.com/api/v1/nfl/play_by_plays` - Auth: HTTP bearer ## Query parameters - `game_id` integer, required - `possession_team_id` integer - `defensive_team_id` integer - `drive_id` integer - `limit` integer - `from_id` integer - `format` 'json' | 'csv' ## Response `200` play_by_plays rows matching the declared filter set. - NFLPlayByPlaysListResponse - `has_more` boolean, required: True when a full page came back, so more rows can exist. - `limit` integer, required: Page size used for this response. - `next_from_id` integer, nullable, required: Pass this as `from_id` on the next request to page forward. `null` on the terminal page, and on a first page requested without `from_id` (that page uses the default sort): to walk every row, start with `from_id=0`. - `play_by_plays` NFLPlayByPlays[], required - `aborted_play` boolean, required: Play was aborted - `air_epa` number, double, nullable: EPA from air yards - `air_wpa` number, double, nullable: WPA from air yards - `air_yds` integer, nullable: Yards in air (perpendicular to LOS) - `assist_tackle` boolean, required: Assist tackle on play - `assist_tackle_1_player_id` string, nullable: Assist tackler 1 GSIS ID - `assist_tackle_1_player_name` string, nullable: Assist tackler 1 name - `assist_tackle_1_team` string, nullable: Assist tackler 1 team - `assist_tackle_2_player_id` string, nullable: Assist tackler 2 GSIS ID - `assist_tackle_2_player_name` string, nullable: Assist tackler 2 name - `assist_tackle_2_team` string, nullable: Assist tackler 2 team - `assist_tackle_3_player_id` string, nullable: Assist tackler 3 GSIS ID - `assist_tackle_3_player_name` string, nullable: Assist tackler 3 name - `assist_tackle_3_team` string, nullable: Assist tackler 3 team - `assist_tackle_4_player_id` string, nullable: Assist tackler 4 GSIS ID - `assist_tackle_4_player_name` string, nullable: Assist tackler 4 name - `assist_tackle_4_team` string, nullable: Assist tackler 4 team - `away_coach` string, nullable: Away team head coach - `away_score` integer, nullable: Total away points - `away_team` string, nullable: Away team abbreviation - `away_timeouts_remaining` integer, nullable: Away timeouts remaining - `away_wp` number, double, nullable: Away team win probability - `away_wp_post` number, double, nullable: Away WP after play - `blocked_player_id` string, nullable: Blocked kick player GSIS ID - `blocked_player_name` string, nullable: Blocked kick player name - `comp_air_epa` number, double, nullable: Completion air EPA - `comp_air_wpa` number, double, nullable: Completion air WPA - `comp_yac_epa` number, double, nullable: Completion YAC EPA - `comp_yac_wpa` number, double, nullable: Completion YAC WPA - `complete_pass` boolean, required: Pass completed - `cp` number, double, nullable: Completion probability - `cpoe` number, double, nullable: Completion percentage over expected - `def_wp` number, double, nullable: Win probability for defense - `defensive_extra_point_attempt` boolean, required: Defense extra point attempt - `defensive_extra_point_conv` boolean, required: Defense extra point success - `defensive_team_id` integer, nullable: FK to teams table for defensive team - `defensive_two_point_attempt` boolean, required: Defense two-point attempt - `defensive_two_point_conv` boolean, required: Defense two-point conversion success - `defteam` string, nullable: Defensive team abbreviation - `defteam_score` integer, nullable: Defense team score at start - `defteam_score_post` integer, nullable: Defense team score at end - `defteam_timeouts_remaining` integer, nullable: Defensive team timeouts - `desc` string, nullable: Full play description text - `div_game` boolean, required: Division game - `down` integer, nullable: Down (1-4) - `drive` integer, nullable: Drive number in game - `drive_end_transition` string, nullable: How drive ended - `drive_end_yard_line` string, nullable: Yard line at drive end - `drive_ended_with_score` boolean, required: Drive resulted in score - `drive_first_downs` integer, nullable: First downs gained in drive - `drive_game_clock_end` string, nullable: Game clock at drive end - `drive_game_clock_start` string, nullable: Game clock at drive start - `drive_id` integer, nullable: FK to game_drives table - `drive_inside20` boolean, required: Drive reached red zone - `drive_play_count` integer, nullable: Number of plays in drive - `drive_play_id_ended` string, nullable: Last play_id of drive - `drive_play_id_started` string, nullable: First play_id of drive - `drive_quarter_end` integer, nullable: Quarter when drive ended - `drive_quarter_start` integer, nullable: Quarter when drive started - `drive_real_start_time` string, nullable: Drive start time (real clock) - `drive_start_transition` string, nullable: How possession was obtained - `drive_start_yard_line` string, nullable: Yard line at drive start - `drive_time_of_possession` string, nullable: Drive time of possession (mm:ss) - `drive_yds_penalized` integer, nullable: Penalty yards during drive - `end_clock_time` string, nullable: Game clock at play end - `end_yard_line` string, nullable: Yard line at play end - `ep` number, double, nullable: Expected points before play - `epa` number, double, nullable: Expected points added - `extra_point_attempt` boolean, required: Extra point attempt - `extra_point_prob` number, double, nullable: Extra point probability - `extra_point_result` string, nullable: good, failed, blocked, safety, aborted - `fantasy` string, nullable: Fantasy designation - `fantasy_id` string, nullable: Fantasy identifier - `fantasy_player_id` string, nullable: Fantasy designation player ID - `fantasy_player_name` string, nullable: Fantasy designation player name - `fg_prob` number, double, nullable: FG probability - `field_goal_attempt` boolean, required: Field goal attempt - `field_goal_result` string, nullable: made, missed, or blocked - `first_down` boolean, required: First down achieved - `first_down_pass` boolean, required: Passing first down - `first_down_penalty` boolean, required: First down via penalty - `first_down_rush` boolean, required: Rushing first down - `fixed_drive` integer, nullable: Manual drive number correction - `fixed_drive_result` string, nullable: Manual drive result correction - `forced_fumble_player_1_player_id` string, nullable: Forced fumble player 1 GSIS ID - `forced_fumble_player_1_player_name` string, nullable: Forced fumble player 1 name - `forced_fumble_player_1_team` string, nullable: Forced fumble team 1 - `forced_fumble_player_2_player_id` string, nullable: Forced fumble player 2 GSIS ID - `forced_fumble_player_2_player_name` string, nullable: Forced fumble player 2 name - `forced_fumble_player_2_team` string, nullable: Forced fumble team 2 - `fourth_down_converted` boolean, required: Fourth down conversion - `fourth_down_failed` boolean, required: Fourth down failure - `fumble` boolean, required: Fumble occurred - `fumble_forced` boolean, required: Fumble was forced - `fumble_lost` boolean, required: Fumble was lost - `fumble_not_forced` boolean, required: Fumble was not forced - `fumble_out_of_bounds` boolean, required: Fumble went OOB - `fumble_recovery_1_player_id` string, nullable: Recovery player 1 GSIS ID - `fumble_recovery_1_player_name` string, nullable: Recovery player 1 name - `fumble_recovery_1_team` string, nullable: Recovery team 1 - `fumble_recovery_1_yds` integer, nullable: Recovery yards 1 - `fumble_recovery_2_player_id` string, nullable: Recovery player 2 GSIS ID - `fumble_recovery_2_player_name` string, nullable: Recovery player 2 name - `fumble_recovery_2_team` string, nullable: Recovery team 2 - `fumble_recovery_2_yds` integer, nullable: Recovery yards 2 - `fumbled_1_player_id` string, nullable: First fumbler GSIS ID - `fumbled_1_player_name` string, nullable: First fumbler name - `fumbled_1_team` string, nullable: First fumbler team - `fumbled_2_player_id` string, nullable: Second fumbler GSIS ID - `fumbled_2_player_name` string, nullable: Second fumbler name - `fumbled_2_team` string, nullable: Second fumbler team - `game_half` string, nullable: Half1, Half2, or Overtime - `game_id` integer, required: FK to games table - `game_seconds_remaining` integer, required: Seconds remaining in game - `game_stadium` string, nullable: Game stadium name - `goal_to_go` boolean, required: Goal-to-go situation - `half_sack_1_player_id` string, nullable: Half-sack player 1 GSIS ID - `half_sack_1_player_name` string, nullable: Half-sack player 1 name - `half_sack_2_player_id` string, nullable: Half-sack player 2 GSIS ID - `half_sack_2_player_name` string, nullable: Half-sack player 2 name - `half_seconds_remaining` integer, required: Seconds remaining in half - `home_coach` string, nullable: Home team head coach - `home_opening_kickoff` boolean, required: Home team had opening kickoff - `home_score` integer, nullable: Total home points - `home_team` string, nullable: Home team abbreviation - `home_timeouts_remaining` integer, nullable: Home timeouts remaining - `home_wp` number, double, nullable: Home team win probability - `home_wp_post` number, double, nullable: Home WP after play - `id` integer, required: Primary Key - `incomplete_pass` boolean, required: Pass incomplete - `interception` boolean, required: Interception indicator - `interception_player_id` string, nullable: Interceptor GSIS ID - `interception_player_name` string, nullable: Interceptor name - `jersey_number` integer, nullable: Primary player jersey - `kick_distance` integer, nullable: Kick distance in yards - `kicker_player_id` string, nullable: Kicker GSIS ID - `kicker_player_name` string, nullable: Kicker name - `kickoff_attempt` boolean, required: Kickoff attempt - `kickoff_downed` boolean, required: Kickoff downed - `kickoff_fair_catch` boolean, required: Kickoff fair catch - `kickoff_in_endzone` boolean, required: Kickoff in endzone - `kickoff_inside_twenty` boolean, required: Kickoff inside 20 - `kickoff_out_of_bounds` boolean, required: Kickoff OOB - `kickoff_returner_player_id` string, nullable: Kickoff returner GSIS ID - `kickoff_returner_player_name` string, nullable: Kickoff returner name - `lateral_interception_player_id` string, nullable: Lateral after INT GSIS ID - `lateral_interception_player_name` string, nullable: Lateral after INT name - `lateral_kickoff_returner_player_id` string, nullable: Lateral kickoff returner GSIS ID - `lateral_kickoff_returner_player_name` string, nullable: Lateral kickoff returner name - `lateral_punt_returner_player_id` string, nullable: Lateral punt returner GSIS ID - `lateral_punt_returner_player_name` string, nullable: Lateral punt returner name - `lateral_receiver_player_id` string, nullable: Lateral receiver GSIS ID (pass) - `lateral_receiver_player_name` string, nullable: Lateral receiver name (pass) - `lateral_receiving_yds` integer, nullable: Yards after lateral (pass) - `lateral_reception` boolean, required: Lateral on pass play - `lateral_return` boolean, required: Lateral on return - `lateral_rush` boolean, required: Lateral on rush play - `lateral_rusher_player_id` string, nullable: Lateral receiver GSIS ID (rush) - `lateral_rusher_player_name` string, nullable: Lateral receiver name (rush) - `lateral_rushing_yds` integer, nullable: Yards after lateral (rush) - `lateral_sack_player_id` string, nullable: Lateral after sack GSIS ID - `lateral_sack_player_name` string, nullable: Lateral after sack name - `location` string, nullable: Home or Neutral - `name` string, nullable: Primary player name (passer or rusher) - `nfl_api_id` string, nullable: UUID from NFL API - `no_huddle` boolean, required: No-huddle offense - `no_score_prob` number, double, nullable: Probability of no score - `old_game_id` string, nullable: Legacy NFL game ID format - `opp_fg_prob` number, double, nullable: Opponent FG probability - `opp_safety_prob` number, double, nullable: Opponent safety probability - `opp_td_prob` number, double, nullable: Opponent TD probability - `order_sequence` number, double, nullable: NFL play-ordering column - `out_of_bounds` boolean, required: Ran/pushed/sacked out of bounds - `own_kickoff_recovery` boolean, required: Own kickoff recovery - `own_kickoff_recovery_player_id` string, nullable: Own kickoff recovery player GSIS ID - `own_kickoff_recovery_player_name` string, nullable: Own kickoff recovery player name - `own_kickoff_recovery_td` boolean, required: Own kickoff recovery TD - `pass` boolean, required: Pass play indicator - `pass_attempt` boolean, required: Pass attempt (includes sacks) - `pass_defense_1_player_id` string, nullable: Pass defense player 1 GSIS ID - `pass_defense_1_player_name` string, nullable: Pass defense player 1 name - `pass_defense_2_player_id` string, nullable: Pass defense player 2 GSIS ID - `pass_defense_2_player_name` string, nullable: Pass defense player 2 name - `pass_length` string, nullable: short or deep - `pass_location` string, nullable: left, middle, or right - `pass_oe` number, double, nullable: Dropback percent over expected - `pass_touchdown` boolean, required: Passing touchdown - `passer` string, nullable: Dropback player name (includes scrambles) - `passer_id` integer, nullable: FK to players table - `passer_jersey_number` integer, nullable: Passer jersey number - `passer_player_id` string, nullable: Passer GSIS ID - `passer_player_name` string, nullable: Passer name - `passing_yds` integer, nullable: Official passing yards - `penalty` boolean, required: Penalty on play - `penalty_player_id` string, nullable: Penalized player GSIS ID - `penalty_player_name` string, nullable: Penalized player name - `penalty_team` string, nullable: Penalized team - `penalty_type` string, nullable: Type of penalty - `penalty_yds` integer, nullable: Penalty yards - `play` boolean, required: Regular play (1) vs special event (0) - `play_clock` integer, nullable: Play clock at snap - `play_deleted` boolean, required: Play was deleted - `play_id` string, required: Numeric play identifier unique to game - `play_type` string, nullable: pass, run, punt, field_goal, kickoff, extra_point, qb_kneel, qb_spike, no_play - `play_type_nfl` string, nullable: NFL source play type - `possession_team_id` integer, nullable: FK to teams table for possession team - `posteam` string, nullable: Possession team abbreviation - `posteam_score` integer, nullable: Possession team score at start - `posteam_score_post` integer, nullable: Possession team score at end - `posteam_timeouts_remaining` integer, nullable: Possession team timeouts - `posteam_type` string, nullable: home or away - `primary_player_gsis_id` string, nullable: Primary player GSIS ID - `punt_attempt` boolean, required: Punt attempt - `punt_blocked` boolean, required: Punt blocked - `punt_downed` boolean, required: Punt downed - `punt_fair_catch` boolean, required: Punt fair catch - `punt_in_endzone` boolean, required: Punt in endzone - `punt_inside_twenty` boolean, required: Punt inside 20 - `punt_out_of_bounds` boolean, required: Punt OOB - `punt_returner_player_id` string, nullable: Punt returner GSIS ID - `punt_returner_player_name` string, nullable: Punt returner name - `punter_player_id` string, nullable: Punter GSIS ID - `punter_player_name` string, nullable: Punter name - `qb_dropback` boolean, required: QB dropback (pass or scramble) - `qb_epa` number, double, nullable: QB EPA credit - `qb_hit` boolean, required: QB was hit - `qb_hit_1_player_id` string, nullable: QB hitter GSIS ID - `qb_hit_1_player_name` string, nullable: QB hitter name - `qb_hit_2_player_id` string, nullable: Second QB hitter GSIS ID - `qb_hit_2_player_name` string, nullable: Second QB hitter name - `qb_kneel` boolean, required: QB kneel - `qb_scramble` boolean, required: QB scramble - `qb_spike` boolean, required: QB spike - `quarter` integer, required: Quarter (1-4, 5=OT) - `quarter_end` boolean, required: Binary quarter-end marker - `quarter_seconds_remaining` integer, required: Seconds remaining in quarter - `receiver` string, nullable: Targeted receiver name - `receiver_id` integer, nullable: FK to players table - `receiver_jersey_number` integer, nullable: Receiver jersey number - `receiver_player_id` string, nullable: Receiver GSIS ID - `receiver_player_name` string, nullable: Receiver name - `receiving_yds` integer, nullable: Official receiving yards - `replay_or_challenge` boolean, required: Replay/challenge occurred - `replay_or_challenge_result` string, nullable: Replay result - `result` integer, nullable: Home score - Away score - `return_team` string, nullable: Returning team - `return_touchdown` boolean, required: Return touchdown - `return_yds` integer, nullable: Return yards - `roof` string, nullable: dome, outdoors, closed, open - `run_gap` string, nullable: end, guard, or tackle - `run_location` string, nullable: left, middle, or right - `rush` boolean, required: Rush play (no scrambles) - `rush_attempt` boolean, required: Rushing play indicator - `rush_touchdown` boolean, required: Rushing touchdown - `rusher_id` integer, nullable: FK to players table - `rusher_jersey_number` integer, nullable: Rusher jersey number - `rusher_player_id` string, nullable: Rusher GSIS ID - `rusher_player_name` string, nullable: Rusher name - `rushing_yds` integer, nullable: Official rushing yards - `sack` boolean, required: Sack indicator - `sack_player_id` string, nullable: Sacker GSIS ID - `sack_player_name` string, nullable: Sacker name - `safety` boolean, required: Safety scored - `safety_player_id` string, nullable: Safety scorer GSIS ID - `safety_player_name` string, nullable: Safety scorer name - `safety_prob` number, double, nullable: Safety probability - `score_differential` integer, nullable: Score gap at play start - `score_differential_post` integer, nullable: Score gap at play end - `series` integer, nullable: Series counter within game - `series_result` string, nullable: First down, Touchdown, Punt, etc. - `series_success` boolean, required: Series resulted in first down or TD - `shotgun` boolean, required: Shotgun formation - `side_of_field` string, nullable: Team abbreviation whose side of field - `solo_tackle` boolean, required: Solo tackle on play - `solo_tackle_1_player_id` string, nullable: Solo tackler 1 GSIS ID - `solo_tackle_1_player_name` string, nullable: Solo tackler 1 name - `solo_tackle_1_team` string, nullable: Solo tackler 1 team - `solo_tackle_2_player_id` string, nullable: Solo tackler 2 GSIS ID - `solo_tackle_2_player_name` string, nullable: Solo tackler 2 name - `solo_tackle_2_team` string, nullable: Solo tackler 2 team - `sp` boolean, required: Scoring play indicator - `special` boolean, required: Special teams indicator - `special_teams_play` boolean, required: Special teams play indicator - `spread_line` number, double, nullable: Vegas spread line - `st_play_type` string, nullable: Type of special teams play - `stadium` string, nullable: Stadium name - `stadium_id` integer, nullable: Stadium ID - `start_time` string, nullable: Kickoff time (eastern) - `success` boolean, nullable: Play success (based on down/distance) - `surface` string, nullable: Playing surface type - `tackle_for_loss_1_player_id` string, nullable: TFL player 1 GSIS ID - `tackle_for_loss_1_player_name` string, nullable: TFL player 1 name - `tackle_for_loss_2_player_id` string, nullable: TFL player 2 GSIS ID - `tackle_for_loss_2_player_name` string, nullable: TFL player 2 name - `tackle_with_assist` boolean, required: Tackle with assistance - `tackle_with_assist_1_player_id` string, nullable: Tackle-assist player 1 GSIS ID - `tackle_with_assist_1_player_name` string, nullable: Tackle-assist player 1 name - `tackle_with_assist_1_team` string, nullable: Tackle-assist player 1 team - `tackle_with_assist_2_player_id` string, nullable: Tackle-assist player 2 GSIS ID - `tackle_with_assist_2_player_name` string, nullable: Tackle-assist player 2 name - `tackle_with_assist_2_team` string, nullable: Tackle-assist player 2 team - `tackled_for_loss` boolean, required: Tackle for loss - `td_player_id` string, nullable: TD scorer GSIS ID - `td_player_name` string, nullable: TD scorer name - `td_prob` number, double, nullable: TD probability - `td_team` string, nullable: Team scoring TD - `temp` integer, nullable: Temperature - `third_down_converted` boolean, required: Third down conversion - `third_down_failed` boolean, required: Third down failure - `time` string, nullable: Game clock at play start (mm:ss) - `time_of_day` string, nullable: Play time in UTC - `timeout` boolean, required: Timeout called - `timeout_team` string, nullable: Team calling timeout - `total` integer, nullable: Home score + Away score - `total_away_comp_air_epa` number, double, nullable: Cumulative away completion air EPA - `total_away_comp_air_wpa` number, double, nullable: Cumulative away completion air WPA - `total_away_comp_yac_epa` number, double, nullable: Cumulative away completion YAC EPA - `total_away_comp_yac_wpa` number, double, nullable: Cumulative away completion YAC WPA - `total_away_epa` number, double, nullable: Cumulative away EPA - `total_away_pass_epa` number, double, nullable: Cumulative away passing EPA - `total_away_pass_wpa` number, double, nullable: Cumulative away passing WPA - `total_away_raw_air_epa` number, double, nullable: Cumulative away raw air EPA - `total_away_raw_air_wpa` number, double, nullable: Cumulative away raw air WPA - `total_away_raw_yac_epa` number, double, nullable: Cumulative away raw YAC EPA - `total_away_raw_yac_wpa` number, double, nullable: Cumulative away raw YAC WPA - `total_away_rush_epa` number, double, nullable: Cumulative away rushing EPA - `total_away_rush_wpa` number, double, nullable: Cumulative away rushing WPA - `total_away_score` integer, nullable: Away score at play start - `total_home_comp_air_epa` number, double, nullable: Cumulative home completion air EPA - `total_home_comp_air_wpa` number, double, nullable: Cumulative home completion air WPA - `total_home_comp_yac_epa` number, double, nullable: Cumulative home completion YAC EPA - `total_home_comp_yac_wpa` number, double, nullable: Cumulative home completion YAC WPA - `total_home_epa` number, double, nullable: Cumulative home EPA - `total_home_pass_epa` number, double, nullable: Cumulative home passing EPA - `total_home_pass_wpa` number, double, nullable: Cumulative home passing WPA - `total_home_raw_air_epa` number, double, nullable: Cumulative home raw air EPA - `total_home_raw_air_wpa` number, double, nullable: Cumulative home raw air WPA - `total_home_raw_yac_epa` number, double, nullable: Cumulative home raw YAC EPA - `total_home_raw_yac_wpa` number, double, nullable: Cumulative home raw YAC WPA - `total_home_rush_epa` number, double, nullable: Cumulative home rushing EPA - `total_home_rush_wpa` number, double, nullable: Cumulative home rushing WPA - `total_home_score` integer, nullable: Home score at play start - `total_line` number, double, nullable: Vegas total line - `touchback` boolean, required: Touchback - `touchdown` boolean, required: Touchdown scored - `two_point_attempt` boolean, required: Two-point conversion attempt - `two_point_conv_result` string, nullable: success, failure, safety, return - `two_point_conversion_prob` number, double, nullable: Two-point conversion probability - `vegas_home_wp` number, double, nullable: Vegas home win probability - `vegas_home_wpa` number, double, nullable: Vegas home WPA - `vegas_wp` number, double, nullable: Vegas win probability - `vegas_wpa` number, double, nullable: Vegas-adjusted WPA - `weather` string, nullable: Weather conditions description - `wind` integer, nullable: Wind speed (mph) - `wp` number, double, nullable: Win probability for possession team - `wpa` number, double, nullable: Win probability added - `xpass` number, double, nullable: Dropback probability - `xyac_epa` number, double, nullable: Expected EPA after catch - `xyac_fd` number, double, nullable: First down probability (xYAC) - `xyac_mean_yardage` number, double, nullable: Average expected YAC - `xyac_median_yardage` number, double, nullable: Median expected YAC - `xyac_success` number, double, nullable: Positive EPA probability - `yac_epa` number, double, nullable: EPA from yards after catch - `yac_wpa` number, double, nullable: WPA from yards after catch - `yard_line` integer, nullable: Yard line number (0-50) - `yardline_100` integer, nullable: Yards from opponent endzone (0-100) - `yds_after_catch` integer, nullable: YAC yards - `yds_gained` integer, nullable: Yards gained on play - `ydsnet` integer, nullable: Total net yards on drive - `ydstogo` integer, nullable: Yards to first down/goal - `yrdln` string, nullable: Yard line string (e.g., "KC 25") ## Other responses - `400`: No declared filter set was satisfied by the request — see `accepted` in the body for the valid combinations. --- [API](https://skmtc.dev/stat-api/apis/sports-db-public-api.md) · [All operations](https://skmtc.dev/stat-api/apis/sports-db-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/stat-api/apis/sports-db-public-api/revisions/601ff9eaca3f?raw)