---
title: "Plays"
method: POST
path: "/v1/get_plays"
tags: ["Multi-table"]
---

# Plays

`POST /v1/get_plays`

## Request

- Base URL: `https://mcp.puckapi.com`
- URL: `https://mcp.puckapi.com/v1/get_plays`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Use for play-by-play events: goals, shots, misses, blocks, faceoffs, hits, giveaways, takeaways, penalties, with rink coordinates, strength state (5v5, 5v4), zone, and the players involved. Filter by game, season, team, player (any role), event type, strength, zone, or period. Requires at least one of game_id, season or player_id. Paginate with offset. Costs 10 credits.

## Request body

- object
  - `game_id` string: NHL game ID (e.g. 2025020887)
  - `season` string: Season ID, 8-digit (e.g. 20242025).
  - `team` string: Team abbreviation that owns the event (e.g. BUF)
  - `player_id` integer: NHL player ID; matches the player in any role on the event
  - `type` 'goal' | 'shot-on-goal' | 'missed-shot' | 'blocked-shot' | 'faceoff' | 'hit' | 'giveaway' | 'takeaway' | 'penalty' | 'delayed-penalty' | 'stoppage' | 'period-start' | 'period-end' | 'game-end' | 'shootout-complete' | 'failed-shot-attempt': Event type
  - `strength` string: Skater strength from the event owner's view, e.g. 5v5, 5v4, 4v5
  - `zone` 'O' | 'N' | 'D': Zone: O offensive, N neutral, D defensive
  - `period` integer: Period number (4+ is overtime)
  - `shot_attempts_only` boolean: Only goals, shots on goal, missed shots and blocked shots (Corsi events)
  - `limit` integer: Max events (default 200)
  - `offset` integer: Pagination offset
  - `league` 'nhl' | 'pwhl' | 'ohl' | 'whl' | 'qmjhl' | 'echl' | 'ahl' | 'ushl': League. Defaults to nhl. One of: nhl, pwhl, ohl, whl, qmjhl, echl, ahl, ushl.

## Response `200`

The result, wrapped in data.

- object
  - `data` object, required
    - `plays` object[], required
    - `summary` object, required
    - `count` number, required
    - `next_offset` number, nullable, required

## Other responses

- `400`: Invalid arguments.
- `401`: Missing or invalid API key.
- `402`: Not enough credits.
- `429`: Rate limited.

---

[API](https://skmtc.dev/puckapi/apis/puckapi-api.md) · [All operations](https://skmtc.dev/puckapi/apis/puckapi-api/llms.txt) · [OpenAPI document](https://skmtc.dev/puckapi/apis/puckapi-api/revisions/99b3e5171ab4?raw)