List stored matches (DB-backed)
Paginated match list read directly from Postgres.
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
Query parameters
ISO date (YYYY-MM-DD) as a UTC calendar day: kickoffs at or after 00:00Z that date and before 00:00Z the next. An evening game in the Americas often kicks off after 00:00Z and is listed under the NEXT date. The exact window applied is echoed in meta.date_window.
Optional IANA time zone name (e.g. America/New_York). ?date= then selects the local calendar day in that zone. Offsets such as -05:00 are rejected with 400. Example: ?sport=american_football&date=2026-09-13&tz=America/New_York.
Case-insensitive (ILIKE) match against leagues.name: "nba", "NBA", "Premier League" all work.
Season LABEL, not a calendar year: the year a season STARTS in. 2025 means the 2025-26 campaign for leagues that cross the new year (EPL, NBA, NHL) and the 2025 season for those that do not (MLB, MLS, WNBA). Filtering resolves each league's own start month. CHANGED 2026-08-31. This previously returned the calendar year and said so here - "?season=2025 returns only the 2025 half. Documented as-is." Documenting it did not make it usable: an NBA caller got 767 of 1,310 rows from another season, and an NHL caller got a complete, internally consistent, half-length season with no way to tell.
asc = oldest first (default); desc = most recent first.
Reads the derived stage column. Only playoffs is populated today (NBA/NHL via the odds ingest); regular-season rows carry NULL, so ?stage=regular returns nothing until an ingestor writes the explicit value. Documented as-is so callers don't read empty as a bug.
Response
ok. Note the non-standard shape ({ data, pagination }, no meta/error wrapper).
Changes
No recorded changes to this operation across all 3 revisions of this API.