---
title: "Rows of one NFL snapshot surface"
method: GET
path: "/v1/nfl/surfaces/{surface}"
tags: ["nfl"]
---

# Rows of one NFL snapshot surface

`GET /v1/nfl/surfaces/{surface}`

## Request

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

Returns the stored rows of a single NFL snapshot surface, newest season
first, paginated. Use GET /v1/nfl/surfaces to list the surfaces, their
row counts and their plan floors.

Each row is `{ surface, season, week, updated_at, attributes }`.
`attributes` is the stat object for that row, keyed by the stat names
the surface uses, so the field set differs per surface by design: this
is one endpoint over 22 product families rather than 22 endpoints.
`season` and `week` are null on the surfaces that are not season- or
week-scoped (`teams`, `players_active`).

`attributes` carries NO identifiers. Our supplier's licence does not
permit redistributing its own ids, so they are removed, as are any
supplier hostnames. Join rows on player and team NAMES together with
`season` and `week`. Sportsbook names and their deep links ARE returned
on the market surfaces, under `sportsbook`, because those are the
market being quoted and not a supplier identifier.

PLAN. 17 surfaces are available on Free. `player_props`,
`opening_player_props` and `dfs_draftables` need Edge or above (the
player-props band); `opening_odds` and `dfs_slates` need Edge or above
(the odds band). A refused call returns 403 naming your current plan,
the plan required and what it unlocks.

HISTORY. `?season=` is subject to the same historical-depth
entitlement as every other season-scoped endpoint: a plan with a
limited archive is refused a season beyond its ceiling. Most surfaces
hold 2025 and 2026.

## Path parameters

- `surface` 'teams' | 'players_active' | 'games' | 'standings' | 'team_roster' | 'team_stats' | 'team_season_stats' | 'season_stats' | 'advanced_passing' | 'advanced_rushing' | 'advanced_receiving' | 'player_designations' | 'fantasy_projections' | 'fantasy_weekly_stats' | 'fantasy_rankings' | 'fantasy_adp' | 'fantasy_scoring_formats' | 'player_props' | 'opening_player_props' | 'dfs_draftables' | 'opening_odds' | 'dfs_slates', required

## Query parameters

- `season` integer
- `week` integer
- `limit` integer
- `offset` integer
- `page` integer

## Response `200`

ok. `{ data, meta }`; `meta.total` is the full match count, not the page size.

- object
  - `data` object[], required
    - `surface` string
    - `season` integer, nullable
    - `week` integer, nullable
    - `updated_at` string, date-time
    - `attributes` object: Stat object for this row. Field set varies by surface; carries no supplier identifier.
  - `meta` object
    - `count` integer
    - `total` integer
    - `limit` integer
    - `offset` integer
    - `cached` boolean
    - `cache_age_ms` integer

## Other responses

- `400`: Invalid query parameters.
- `403`: This surface requires a higher plan, or your plan's historical depth does not reach the requested season.
- `404`: Unknown surface. The response names the valid surfaces.

---

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