---
title: "Play-by-play for a stored match"
method: GET
path: "/v1/stored/matches/{id}/plays"
tags: ["stored"]
---

# Play-by-play for a stored match

`GET /v1/stored/matches/{id}/plays`

## Request

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

Stored plays for any covered match. The full soccer minute-by-minute
stream and NBA, NHL and NFL play-by-play all require Pro; lower tiers
receive a 403 naming the tier. A match whose sport cannot be resolved
is treated as Pro. For Free soccer scoring events, use
`GET /v1/matches/{id}/events` with its default `type=goals` view.

## Path parameters

- `id` string, uuid, required

## Query parameters

- `scoring_only` boolean
- `period` integer
- `limit` integer

## Response `200`

ok. `{ data }`, an array of plays; no meta/error wrapper.

- object
  - `data` object[], required
    - `id` string
    - `sequence_number` integer
    - `period` integer
    - `period_display` string
    - `clock` string
    - `type` string
    - `description` string
    - `team_id` string, uuid, nullable
    - `player_id` string, uuid, nullable
    - `scoring_play` boolean
    - `score_value` integer, nullable
    - `home_score` integer, nullable
    - `away_score` integer, nullable
    - `coordinate_x` number, nullable: Shot/play location. For soccer shots this is the SHOOTER's position on a 0-100 normalised pitch, not where the ball crossed the goal line.
    - `coordinate_y` number, nullable
    - `xg` number, nullable: Expected goals for this shot, 0-1. Populated on soccer shot rows; `null` on plays whose source does not model xG. A null means "not supplied", never "zero chance".
    - `xgot` number, nullable: Expected goals on target. Populated only for shots that were on target, so it is `null` for misses and blocks by design.
    - `wallclock` string, date-time, nullable

## Other responses

- `400`: Invalid match id or query.
- `403`: plan_required (Pro or higher for covered play-by-play sports)

---

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