---
title: "List stored matches (DB-backed)"
method: GET
path: "/v1/stored/matches"
tags: ["stored"]
---

# List stored matches (DB-backed)

`GET /v1/stored/matches`

## Request

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

Paginated match list read directly from Postgres.

## Query parameters

- `sport` string
- `status` 'scheduled' | 'live' | 'finished' | 'cancelled'
- `date` string
- `tz` string
- `league` string
- `season` integer
- `sort` 'asc' | 'desc'
- `stage` 'playoffs' | 'regular' | 'preseason'
- `limit` integer
- `offset` integer

## Response `200`

ok. Note the non-standard shape (`{ data, pagination }`, no meta/error wrapper).

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

## Other responses

- `400`: Invalid query parameters.

---

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