---
title: "NHL play-by-play"
method: GET
path: "/v1/nhl/games/{game_id}/plays"
tags: ["nhl"]
---

# NHL play-by-play

`GET /v1/nhl/games/{game_id}/plays`

## Request

- Base URL: `https://api.bigballsdata.com`
- URL: `https://api.bigballsdata.com/v1/nhl/games/{game_id}/plays`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

**Pro plan or higher**: all NHL play-by-play requires Pro; Free /
Solo / Trio / Edge receive a 403 naming the tier and linking the docs
and pricing pages. Mirrors NFL and NBA play-by-play's tier ("all play
by play is pro"); NBA's Edge-and-up gate was retired on 2026-09-18.

`nhl_play_by_play` mirrors `nba_play_by_play`'s schema (migration
057). Two columns the migration declares are 0% populated in
production (verified against all 434,815 rows) and are never served:
`text` and `score_value`. `team_id` (~84%) and `coordinate_x`/
`coordinate_y` (~83%) are null on faceoffs/stoppages with no team or
spatial attribution; `home_score`/`away_score` (~2%) are stamped only
on the goal event itself. `shooting_only=true` turns the response into
a shot-chart feed and adds our licensed play-derived xG, distance,
angle, rebound, rush and empty-net fields where the xG model covers
the event. Coverage includes the complete 2025-26 season; the licensed
2026-27 feed begins with the September 29 regular-season opener.

## Path parameters

- `game_id` string, uuid, required

## Query parameters

- `play_type` string
- `period` integer
- `scoring_only` boolean
- `shooting_only` boolean
- `limit` integer
- `offset` integer

## Response `200`

ok. `{ data, pagination, meta }`; `meta.pbp_available: false` when the match exists but this vendor never covered it.

- object
  - `data` object[]
  - `pagination` object
    - `total` integer
    - `limit` integer
    - `offset` integer

## Other responses

- `403`: plan_required (Pro or higher)
- `404`: NHL match not found

---

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