---
title: "NFL season leaderboard"
method: GET
path: "/v1/nfl/leaders"
tags: ["nfl"]
---

# NFL season leaderboard

`GET /v1/nfl/leaders`

## Request

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

Season leaderboard over stored weekly NFL player statistics. The route
sums the selected stat across the requested season and season type,
then ranks players in descending order. `season` defaults to the newest
populated season for that season type. `player_id` is the established
NFL player identifier also used by `/v1/nfl/players/{id}/stats`, not a
BigBalls player UUID. Responses are cached for five minutes.

This code-only stage deliberately makes no `data_as_of` claim. The base
table records real value-change timestamps, but production's public
view does not expose that column until migration 285 is separately
applied. A missing freshness field is more accurate than substituting a
row-creation timestamp or cron heartbeat.

## Query parameters

- `stat` 'fantasy_points_ppr' | 'fantasy_points' | 'passing_yards' | 'passing_tds' | 'rushing_yards' | 'rushing_tds' | 'receiving_yards' | 'receiving_tds' | 'receptions' | 'targets' | 'interceptions_thrown' | 'sacks' | 'tackles_solo'
- `season` integer
- `season_type` 'REG' | 'POST'
- `min_games` integer
- `limit` integer

## Response `200`

Season leaderboard and cache metadata.

- object
  - `data` object, required
  - `meta` object
    - `cached` boolean
    - `cache_age_ms` integer

## Other responses

- `400`: Invalid query parameters.
- `404`: No NFL player statistics are available for any season.

---

[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)