---
title: "Live and scheduled MLB games"
method: GET
path: "/v1/mlb/games"
tags: ["MLB"]
---

# Live and scheduled MLB games

`GET /v1/mlb/games`

## Request

- Base URL: `https://api.playcallerapp.com`
- URL: `https://api.playcallerapp.com/v1/mlb/games`
- Auth: API key in header `X-PlayCaller-Key`

Live inning-by-inning game state from the MLB Stats API pipeline. Defaults to today's games. Scores update on a polling cycle throughout the game day.

**Tier access:** Developer Sandbox, Build, Growth, Pro Insights, Syndicate Alpha

## Query parameters

- `date` string, date
- `state` 'pre_game' | 'scheduled' | 'in_progress' | 'final' | 'completed' | 'postponed'
- `limit` integer

## Response `200`

MLB game states

- object
  - `success` boolean
  - `endpoint` string
  - `count` integer
  - `data` MLBGame[]
    - `game_pk` string: MLB Stats API game ID — returned as a string, not numeric
    - `game_date` string, date-time
    - `game_time` string, date-time, nullable
    - `state` 'pre_game' | 'scheduled' | 'in_progress' | 'final' | 'completed' | 'postponed': Real values from mlb_game_states — not the previously-documented live/final/preview enum
    - `home_team` object
      - `id` integer
      - `name` string
      - `score` integer, nullable
    - `away_team` object
      - `id` integer
      - `name` string
      - `score` integer, nullable
    - `inning` integer, nullable
    - `inning_state` string, nullable
    - `lineup_posted` boolean
    - `is_final` boolean
    - `status_code` string
    - `last_polled` string, date-time
  - `meta` ResponseMeta
    - `sport` string
    - `league` string: Present on multi-sport (ESPN-backed) endpoints; mirrors sport unless a sport has sub-leagues (e.g. soccer: epl/mls).
    - `tier` string
    - `calls_remaining_this_month` integer
    - `documentation_url` string, uri

## Other responses

- `401`: Missing or invalid API key
- `429`: Rate limit or monthly quota exceeded
- `500`: Internal server error

---

[API](https://skmtc.dev/playcallerapp/apis/playcaller-data-api.md) · [All operations](https://skmtc.dev/playcallerapp/apis/playcaller-data-api/llms.txt) · [OpenAPI document](https://skmtc.dev/playcallerapp/apis/playcaller-data-api/revisions/100c0a3ffbfe?raw)