MLB Game Intelligence API

Structured, cache-aware Major League Baseball data for dashboards, newsletters, fantasy tools, analytics pipelines, and AI agents.

This Actor turns a broad MLB data feed into simple, repeatable workflows. Use it to retrieve a game-day briefing, current standings, team information, recent form, head-to-head history, match detail, lineups, box scores, player profiles, and season statistics.

Start here

The default mode is read_cache. It is safe to run repeatedly and returns the latest available cached record. Every response tells you whether the requested record was found, when it was collected, and when it should be refreshed.

{
  "mode": "read_cache",
  "resource": "game_day"
}

The Actor maintains a shared cache so repeated requests are fast and predictable. If a requested item is not currently available, the Actor returns cacheHit: false instead of returning made-up data.

Capabilities

Resource	What it returns	Common identifiers
game_day	Combined games, standings, and highlights briefing	date, timezone
matches	Scheduled and completed MLB games, scores, state, teams, and inning lines	date, season
highlights	Available video highlights and match associations	date
standings	American and National League standings with detailed stat fields	season
teams	MLB team directory, abbreviations, logos, and stable IDs	—
team	A single team profile	teamId
team_statistics	Team totals plus home/away performance splits	teamId, date
last_five_games	A team’s latest five completed games	teamId
head_to_head	Recent results between two teams	teamIdOne, teamIdTwo
match	Match detail including venue, forecast, officials, rosters, plays, and stats	matchId
lineups	Home and away lineups for a match	matchId
box_scores	Per-player batting and pitching performance for a match	matchId
match_statistics	Team-level match statistics	matchId
player	Player profile and current team information	playerId
player_statistics	Per-season player batting and pitching statistics	playerId

How requests work

Requests use the read_cache mode. It reads the named resource and writes one structured item to the default dataset.

{
  "mode": "read_cache",
  "resource": "matches",
  "date": "2026-08-24",
  "timezone": "America/New_York"
}

Responses include:

• cacheHit: whether a matching record exists.
• stale: whether the refresh deadline has passed.
• cachedAt: collection timestamp.
• refreshAfter: recommended next refresh timestamp.
• data: the original structured data for the resource.

Input reference

Field	Type	Used by	Notes
mode	string	all	Use read_cache; it is the default
resource	string	all	Select one resource from the capability table
date	string	matches, highlights	YYYY-MM-DD; defaults to the current UTC date
season	integer	matches, standings	Optional season year
timezone	string	matches, highlights	IANA timezone, default America/New_York
matchId	integer	match, lineups, box scores, match statistics	Stable match ID from matches
teamId	integer	team, team statistics, last five games	Stable team ID from teams or matches
teamIdOne	integer	head-to-head	First stable team ID
teamIdTwo	integer	head-to-head	Second stable team ID
playerId	integer	player, player statistics	Stable player ID from box scores or player data

Customer examples

Today’s game-day briefing

{ "mode": "read_cache", "resource": "game_day" }

Games on a specific date

{
  "mode": "read_cache",
  "resource": "matches",
  "date": "2026-08-24",
  "timezone": "America/New_York"
}

Current standings

{ "mode": "read_cache", "resource": "standings" }

Video highlights

{
  "mode": "read_cache",
  "resource": "highlights",
  "date": "2026-08-24"
}

Team profile and form

{ "mode": "read_cache", "resource": "team", "teamId": 10291183 }

{ "mode": "read_cache", "resource": "last_five_games", "teamId": 10291183 }

Head-to-head comparison

{
  "mode": "read_cache",
  "resource": "head_to_head",
  "teamIdOne": 10291183,
  "teamIdTwo": 10291186
}

Match intelligence

{ "mode": "read_cache", "resource": "match", "matchId": 1598849 }

Lineups and box scores

{ "mode": "read_cache", "resource": "lineups", "matchId": 1598849 }

{ "mode": "read_cache", "resource": "box_scores", "matchId": 1598050 }

Player card and season statistics

{ "mode": "read_cache", "resource": "player", "playerId": 73769102 }

{ "mode": "read_cache", "resource": "player_statistics", "playerId": 73769102 }

Data freshness

The Actor serves shared cached records and includes freshness metadata with every response. This keeps customer runs fast and predictable while making it easy to display a “last updated” label or retry when a record is not yet available.

Finding IDs

1. Run teams once to build a team lookup table.
2. Run matches for a date to obtain match IDs and both team IDs.
3. Use a match box score to discover player IDs for player profile and season-stat lookups.
4. Pass those stable IDs to the detail resources.

Output and downstream use

The Actor writes JSON items to the default dataset. Nested structures are preserved so no statistical detail is discarded. Dataset output can be exported from Apify as JSON, CSV, Excel, XML, or consumed through the Apify API and MCP integrations.

Cache metadata is intentionally included with every item. Applications can accept fresh records, display a “last updated” label, or queue a refresh when stale is true.

Saved task catalog

The Actor includes twelve ready-to-run saved read tasks:

• mlb-game-day-briefing — games, standings, and highlights in one response.
• mlb-todays-games — today’s scheduled and completed games.
• mlb-current-standings — current American and National League standings.
• mlb-todays-highlights — today’s available video highlights.
• mlb-team-directory — the MLB team directory and stable IDs.
• mlb-giants-profile — an example team profile.
• mlb-giants-recent-form — an example last-five-games form view.
• mlb-giants-reds-head-to-head — an example team comparison.
• mlb-match-intelligence — detailed match information for an example fixture.
• mlb-match-lineups — lineups for an example fixture.
• mlb-match-box-scores — per-player box scores for an example completed game.
• mlb-player-card — an example player profile lookup.

The first four tasks use the default game-day cache. Identifier-based examples depend on the requested match, team, and player records being available in the shared cache.

Troubleshooting

cacheHit: false — The requested record is not currently available, or the requested date/ID combination differs from the cached key. Retry later or try another date or identifier.

A detail resource is empty — Some records are naturally unavailable before a game starts. Try a completed match for box scores and match statistics, and query lineups close to game time.

Wrong date or timezone — Dates are interpreted with the selected IANA timezone for date-based resources. Use an explicit timezone when building a daily dashboard.

Need a new resource — The Actor is designed to add cacheable resources without changing the customer-facing read pattern. Request the resource and include the expected IDs and freshness requirements.

Important notes

• This Actor is for MLB data workflows and does not currently expose betting-odds resources.
• Cache freshness depends on the refresh cadence for the requested resource.
• A cache miss is reported honestly; the Actor never fabricates a result or silently performs an unplanned live request.