# MLB Game Intelligence API (`fetchfinch/mlb-game-intelligence`) Actor

Cache-first MLB schedules, standings, highlights, lineups and game intelligence.

- **URL**: https://apify.com/fetchfinch/mlb-game-intelligence.md
- **Developed by:** [Fetch Finch](https://apify.com/fetchfinch) (community)
- **Categories:** Developer tools, News, AI
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 mlb data results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## 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.

```json
{
  "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.

```json
{
  "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

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

#### Games on a specific date

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

#### Current standings

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

#### Video highlights

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

#### Team profile and form

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

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

#### Head-to-head comparison

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

#### Match intelligence

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

#### Lineups and box scores

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

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

#### Player card and season statistics

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

```json
{ "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`](https://apify.com/fetchfinch/mlb-game-intelligence/examples/mlb-game-day-briefing) — games, standings, and highlights in one response.
- [`mlb-todays-games`](https://apify.com/fetchfinch/mlb-game-intelligence/examples/mlb-todays-games) — today’s scheduled and completed games.
- [`mlb-current-standings`](https://apify.com/fetchfinch/mlb-game-intelligence/examples/mlb-current-standings) — current American and National League standings.
- [`mlb-todays-highlights`](https://apify.com/fetchfinch/mlb-game-intelligence/examples/mlb-todays-highlights) — today’s available video highlights.
- [`mlb-team-directory`](https://apify.com/fetchfinch/mlb-game-intelligence/examples/mlb-team-directory) — the MLB team directory and stable IDs.
- [`mlb-giants-profile`](https://apify.com/fetchfinch/mlb-game-intelligence/examples/mlb-giants-profile) — an example team profile.
- [`mlb-giants-recent-form`](https://apify.com/fetchfinch/mlb-game-intelligence/examples/mlb-giants-recent-form) — an example last-five-games form view.
- [`mlb-giants-reds-head-to-head`](https://apify.com/fetchfinch/mlb-game-intelligence/examples/mlb-giants-reds-head-to-head) — an example team comparison.
- [`mlb-match-intelligence`](https://apify.com/fetchfinch/mlb-game-intelligence/examples/mlb-match-intelligence) — detailed match information for an example fixture.
- [`mlb-match-lineups`](https://apify.com/fetchfinch/mlb-game-intelligence/examples/mlb-match-lineups) — lineups for an example fixture.
- [`mlb-match-box-scores`](https://apify.com/fetchfinch/mlb-game-intelligence/examples/mlb-match-box-scores) — per-player box scores for an example completed game.
- [`mlb-player-card`](https://apify.com/fetchfinch/mlb-game-intelligence/examples/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.

# Actor input Schema

## `mode` (type: `string`):

Customers should use Read cache. Cache collect is reserved for private scheduled tasks.

## `resource` (type: `string`):

game\_day joins the cached schedule, standings and highlights into one response.

## `date` (type: `string`):

YYYY-MM-DD. Required for matches or highlights; defaults to today in UTC for game\_day.

## `season` (type: `integer`):

Optional MLB season, used by matches.

## `matchId` (type: `integer`):

Required by match, lineups, box scores and match statistics.

## `teamId` (type: `integer`):

Required by team, team statistics and last five games.

## `teamIdOne` (type: `integer`):

Required by head-to-head.

## `teamIdTwo` (type: `integer`):

Required by head-to-head.

## `playerId` (type: `integer`):

Required by player and player statistics.

## `timezone` (type: `string`):

IANA timezone used by matches and highlights.

## `collectorToken` (type: `string`):

Only needed by your private scheduled collector task.

## `resources` (type: `array`):

Optional batch for cache\_collect. Each item has resource and any applicable IDs/date. Defaults to the hourly game-day bundle.

## Actor input object example

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

# Actor output Schema

## `results` (type: `string`):

One structured response item per Actor run.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "date": "2026-08-24"
};

// Run the Actor and wait for it to finish
const run = await client.actor("fetchfinch/mlb-game-intelligence").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "date": "2026-08-24" }

# Run the Actor and wait for it to finish
run = client.actor("fetchfinch/mlb-game-intelligence").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "date": "2026-08-24"
}' |
apify call fetchfinch/mlb-game-intelligence --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,fetchfinch/mlb-game-intelligence"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/rTRSDbSqvSeiS2AA2/builds/B0UYo9AbHXXrej5PO/openapi.json