---
title: "NFL team-week totals - offence, defence, kicking, returns and fumbles"
method: GET
path: "/v1/nfl/team-stats"
tags: ["nfl"]
---

# NFL team-week totals - offence, defence, kicking, returns and fumbles

`GET /v1/nfl/team-stats`

## Request

- Base URL: `https://api.bigballsdata.com`
- URL: `https://api.bigballsdata.com/v1/nfl/team-stats`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Passing, rushing and receiving totals per team per week, with EPA and CPOE, plus kicking, return and fumble blocks. 3,386 rows covering 2020-2025 - 544 per 17-game season, which is every team in every game. Omit season to get the newest available; meta.resolved names what was served.
NO DERIVED `turnovers` FIELD. Sum passing.interceptions with whichever offensive fumbles-lost columns your scoring rules use. fumbles.lost_total is NOT that number - it also counts return fumbles, which the offence is not charged with.
NULL AND 0 DIFFER. kicking.fg_long is null when every attempt missed, because the stat records the longest MADE kick - absent, not zero. A null on a season that predates a load means not-loaded, never zero.
`fg_pct` is deliberately not published - it is derivable from fg_made and fg_att, and the stored value is a fraction in [0,1] despite the name.
DEFENSE. Each row carries a `defense` object: what this team's defence did in the game, derived from the OPPONENT's row in the same game, this team's summed defender credits and the final score. It is not a separate dataset, so it is available exactly where the row is. Sacks, sack yards, interceptions and yards allowed come from the opponent's offensive totals rather than summed defender credits, because a sack with no defender named is still a sack. Every defense field is null, not 0, when its input has not loaded yet (for example the opponent's row for a game still being processed).
passing_yards_allowed is NET: the opponent's passing.yards is gross, and the yards its passers lost to sacks are subtracted. total_yards_allowed is passing_yards_allowed plus rushing_yards_allowed.
THREE DEFENSIVE FIELDS ARE NOT PUBLISHED. fumble_recoveries: no stored data records who recovered a fumble. safeties: about a third of safeties (33 of 92 in 2020-2025) are team safeties from penalties enforced in the end zone, which no defender is credited with, so a credited count would silently miss them. defensive_tds: the stored defender touchdown count includes interception returns only, never fumble returns, so it is published as interception_return_tds and not as a defensive touchdown total.

## Query parameters

- `season` integer
- `week` integer
- `team` string
- `season_type` 'REG' | 'POST' | 'WC' | 'DIV' | 'CON' | 'SB'
- `limit` integer
- `offset` integer

## Response `200`

ok

- object
  - `data` object[]
    - `team` string
    - `opponent_team` string, nullable
    - `defense` object: This team's defence in the game, derived from the opponent's row. Every field is null when its input has not loaded.
      - `sacks` number, nullable: Opponent's sacks suffered. A number because a sack can be shared.
      - `sack_yards` number, nullable: Yards the opponent's passers lost to sacks, as a positive number.
      - `interceptions` integer, nullable: Opponent's interceptions thrown.
      - `forced_fumbles` integer, nullable: Fumbles forced, summed over this team's defenders. Forcing is not recovering.
      - `interception_return_tds` integer, nullable: Interception-return touchdowns by this team's defenders. Fumble-return touchdowns are not included.
      - `blocked_kicks` integer, nullable: blocked_punts plus blocked_field_goals plus blocked_extra_points; null if any part is null.
      - `blocked_punts` integer, nullable: Punts blocked, summed over this team's defenders.
      - `blocked_field_goals` integer, nullable: The opponent's field-goal attempts that were blocked.
      - `blocked_extra_points` integer, nullable: The opponent's extra-point attempts that were blocked.
      - `points_allowed` integer, nullable: The opponent's final score, all phases. Null until the game has a final score.
      - `passing_yards_allowed` integer, nullable: Net of sack yardage.
      - `rushing_yards_allowed` integer, nullable
      - `total_yards_allowed` integer, nullable: passing_yards_allowed plus rushing_yards_allowed.
  - `pagination` object
    - `total` integer
    - `limit` integer
    - `offset` integer
  - `meta` object
    - `resolved` object, nullable
      - `season` integer
      - `defaulted` boolean
    - `data_as_of` string, date-time, nullable

---

[API](https://skmtc.dev/bigballsdata/apis/big-ball-sports-api.md) · [All operations](https://skmtc.dev/bigballsdata/apis/big-ball-sports-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bigballsdata/apis/big-ball-sports-api/revisions/31fb54ac414e?raw)