---
title: "Stored lineups for a match"
method: GET
path: "/v1/stored/matches/{id}/lineups"
tags: ["stored"]
---

# Stored lineups for a match

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

## Request

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

Home and away lineup entries from the best stored lineup data available for the match. MLB responses include player names, positions, jersey numbers and starter flags, including starting pitcher identification. MLB lineups (baseball) and NHL lineups (ice hockey) require the Edge plan or higher. Access for every other sport on this shared route is unchanged, including the soccer and cricket lineups served on Free. Coverage is partial, so matches without lineup data return empty arrays with `meta.available=false` and a coverage note.
NHL (ice hockey) entries are a POST-GAME record and are never a pre-game projection. A match gains entries only after it has been played: they are the dressed skaters, both dressed goalies and the scratches, and `starter` is true for the one goalie per side who actually started the game. That is not a confirmed or projected pre-game starting goalie, and no tier returns one before puck drop. NHL entries also carry no forward-line number, no defence pairing and no power-play unit membership, because the upstream record does not express them.

## Path parameters

- `id` string, uuid, required

## Response `200`

ok. `{ data: { home, away }, meta: { available, coverage_note? } }`, a route-specific meta, not the standard ResponseMeta (no error wrapper).

- object
  - `data` object, required
    - `home` object[], required
      - `player_id` string
      - `name` string
      - `position` string
      - `jersey_number` integer
      - `starter` boolean
      - `field` string
      - `value` unknown
    - `away` object[], required
      - `player_id` string
      - `name` string
      - `position` string
      - `jersey_number` integer
      - `starter` boolean
      - `field` string
      - `value` unknown
    - `bench` object: Non-starters from the same stored observation, on the `lineup_shape=players` baseball shape only. Added 2026-10-05: these rows used to be returned INSIDE `home`/`away` carrying `starter: false`, so a lineup included players who did not start. They are not removed from the response, only moved here.
      - `home` object[]
        - `player_id` string
        - `name` string
        - `position` string
        - `jersey_number` integer
        - `starter` boolean
      - `away` object[]
        - `player_id` string
        - `name` string
        - `position` string
        - `jersey_number` integer
        - `starter` boolean
  - `meta` object, required
    - `available` boolean, required
    - `lineup_shape` 'players' | 'raw_stats'
    - `coverage_note` string
    - `team_attribution` object: How each player was attributed to home or away, on the `lineup_shape=players` baseball shape. `team_at_match` means every row carried the team the ingested box score put the player on for THIS match; `current_team` means every row fell back to the player's present roster team, which cannot distinguish a player who has since moved; `mixed` means both. `side_uncertain` is true whenever any row used the fallback.
      - `basis` 'team_at_match' | 'current_team' | 'mixed'
      - `team_at_match_rows` integer
      - `current_team_fallback_rows` integer
      - `side_uncertain` boolean
    - `partial` boolean: Present and true only when stored starter rows existed for this match but could not be served, so the lineup returned is known to be incomplete. Absent otherwise.
    - `dropped` object: Per-reason counts of the rows behind `partial`. Present only alongside `partial`.
      - `total` integer
      - `unparseable_starter_value` integer
      - `no_team_attribution` integer
      - `team_not_in_this_match` integer

## Other responses

- `400`: Invalid match id.
- `403`: MLB starting lineups require the Edge plan or higher.

---

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