---
title: "List games for MLB"
method: GET
path: "/api/v1/mlb/games"
tags: ["MLB"]
---

# List games for MLB

`GET /api/v1/mlb/games`

## Request

- Base URL: `https://api.stat-api.com`
- URL: `https://api.stat-api.com/api/v1/mlb/games`
- Auth: HTTP bearer

## Query parameters

- `season_id` integer
- `home_team_id` integer
- `away_team_id` integer
- `status` string
- `day` integer
- `day__gte` integer
- `day__lte` integer
- `day__between` integer
- `limit` integer
- `from_id` integer
- `format` 'json' | 'csv'

## Response `200`

games rows matching the declared filter set.

- MLBGamesListResponse
  - `games` MLBGames[], required
    - `attendance` integer, nullable
    - `away_team_id` integer, required
    - `away_team_score` integer, required
    - `channel` string, nullable
    - `day` integer, required
    - `day_night` string, nullable: D=Day, N=Night
    - `doubleheader` boolean, required
    - `duration_minutes` integer, nullable: Total game duration in minutes
    - `end_time` string, date-time, nullable
    - `game_label` string, nullable
    - `game_number` integer, required: For doubleheaders: 1 or 2
    - `game_time` string, date-time, required: Canonical game start time. The ONLY one on any games table — nba and nfl carried a duplicate `start_time` until 2026-08-27 and nhl carried `date_time` and `date_time_utc`; all four sports now expose `game_time` alone.
    - `game_type` string, required: R=Regular, S=Spring, F=Wild Card, D=Division, L=League, W=World Series, E=Exhibition, A=All-Star
    - `home_team_id` integer, required
    - `home_team_score` integer, required
    - `id` integer, required: Primary Key
    - `if_necessary` boolean, nullable
    - `league_game_id` integer, nullable: Official MLB gamePk (issued by the league)
    - `league_id` string, nullable: Official MLB game identifier
    - `losing_pitcher_id` integer, nullable: Losing pitcher of record
    - `neutral_venue` boolean, required
    - `postponed_status` string, nullable
    - `save_pitcher_id` integer, nullable: Save pitcher (if any)
    - `season_id` integer, required
    - `season_type` string, required: Canonical season phase. Postseason round detail (Wild Card/Division/LCS/World Series) is in the league-native `game_type` code.
    - `series_game_number` string, nullable
    - `series_name` string, nullable
    - `series_text` string, nullable
    - `status` string, required: Final, Live, Scheduled, Postponed, Suspended, Cancelled
    - `venue_id` integer, nullable
    - `winning_pitcher_id` integer, nullable: Winning pitcher of record
  - `has_more` boolean, required: True when a full page came back, so more rows can exist.
  - `limit` integer, required: Page size used for this response.
  - `next_from_id` integer, nullable, required: Pass this as `from_id` on the next request to page forward. `null` on the terminal page, and on a first page requested without `from_id` (that page uses the default sort): to walk every row, start with `from_id=0`.

## Other responses

- `400`: No declared filter set was satisfied by the request — see `accepted` in the body for the valid combinations.

---

[API](https://skmtc.dev/stat-api/apis/sports-db-public-api.md) · [All operations](https://skmtc.dev/stat-api/apis/sports-db-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/stat-api/apis/sports-db-public-api/revisions/0c8484d5fc29?raw)