# MLB Starting Lineups & Probable Pitchers API + Change Alerts (`ichigowa/mlb-lineups-alert`) Actor

Daily MLB schedule with probable pitchers and starting lineups as clean JSON, plus change alerts diffed against the previous run: pitcher changes, lineups first posted, batting-order swaps. Optional webhook. Run on a schedule. Unofficial; data (c) MLB Advanced Media.

- **URL**: https://apify.com/ichigowa/mlb-lineups-alert.md
- **Developed by:** [kyle herman](https://apify.com/ichigowa) (community)
- **Categories:** Sports, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

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 Starting Lineups & Probable Pitchers API + Change Alerts

Get today's **MLB starting lineups** and **probable pitchers** as clean, normalized JSON — plus automatic **change alerts** every time you run it. This actor is a scheduled-run-friendly **mlb lineups api**: it fetches the daily MLB schedule (hydrated with probable pitchers and posted lineups), emits one row per game, and diffs against the previous run's snapshot to detect:

- 🔁 **Probable pitcher changed** (scratches, swaps)
- 📋 **Lineup first posted** (the moment a starting lineup drops)
- 🔀 **Lineup player changed** (late swaps, batting-order changes)

Perfect for fantasy baseball tools, DFS pipelines, betting models, Discord/Slack bots, and anyone searching for an **mlb starting lineup api**, **probable pitchers api**, or **mlb lineup alerts** feed without scraping.

### How it works

1. Fetches the MLB StatsAPI daily schedule for today (plus optional `days_ahead` extra days).
2. Emits one `lineup-row` per game: teams, status, probable pitchers, and full home/away starting lineups (with batting order and positions) when posted. **Before lineups are posted, `home_lineup`/`away_lineup` are empty arrays and `lineups_posted` is `false` — that's normal pre-game.**
3. Diffs each game against the previous run's snapshot (stored per-game in the named key-value store `mlb-lineups-snapshots`) and emits `change-alert` rows.
4. Optionally POSTs alerts to your `webhook_url`.

**Run it on a schedule** (e.g. every 10–15 minutes on game days) to catch lineups the moment they're posted and pitchers the moment they're scratched.

### Input

All fields optional — `{}` works out of the box.

| Field | Type | Default | Description |
|---|---|---|---|
| `days_ahead` | integer | `0` | Extra days of schedule beyond today (max 7). |
| `webhook_url` | string | `""` | If set, alerts are POSTed there as `{"alerts": [...]}`. |
| `include_unchanged` | boolean | `true` | When `false`, only change-alert rows are pushed (alert-only mode). |

### Output

#### `lineup-row` (one per game)

```json
{
  "type": "lineup-row",
  "gamePk": 823337,
  "game_date": "2026-09-03T16:35:00Z",
  "status": "Scheduled",
  "home_team": "Pittsburgh Pirates",
  "away_team": "San Francisco Giants",
  "home_probable_pitcher": { "id": 669199, "name": "Lake Bachar" },
  "away_probable_pitcher": { "id": 694918, "name": "Blade Tidwell" },
  "home_lineup": [
    { "id": 699302, "name": "Héctor Rodríguez", "position": "RF", "batting_order": 1 }
  ],
  "away_lineup": [],
  "lineups_posted": false,
  "fetched_at": "2026-09-03T02:55:41Z"
}
```

#### `change-alert` (one per detected change)

```json
{
  "type": "change-alert",
  "gamePk": 822853,
  "change_kind": "probable_pitcher_changed",
  "field": "home_probable_pitcher",
  "old_value": "Old Guy",
  "new_value": "Cal Quantrill",
  "detected_at": "2026-09-03T02:56:08Z"
}
```

`change_kind` values: `probable_pitcher_changed`, `lineup_posted`, `lineup_player_changed`. For `lineup_posted`, `new_value` is a human-readable batting order (`["1. Player (RF)", ...]`); for player changes, `field` includes the batting slot (e.g. `home_lineup[3]`).

The **first time a game is seen, it seeds the baseline** — alerts start from the second run onward.

### Pricing (pay per event)

- `lineup-row` — one normalized game row pushed
- `change-alert` — one detected change pushed

### Notes & attribution

- Off-days / offseason: zero games is handled gracefully (nothing pushed).
- This actor is **unofficial** and not affiliated with, endorsed by, or sponsored by MLB. Data is sourced from the public MLB StatsAPI and is subject to MLB's terms: **data © MLB Advanced Media, L.P.** ("Copyright 2026 MLB Advanced Media, L.P. Use of any content on this page acknowledges agreement to the terms posted at http://gdx.mlb.com/components/copyright.txt"). Use for personal, non-commercial informational purposes per MLBAM's notice.

# Actor input Schema

## `days_ahead` (type: `integer`):

Extra days of schedule to fetch beyond today (0 = today only, max 7). Probable pitchers are usually available a few days out; starting lineups only shortly before first pitch.

## `webhook_url` (type: `string`):

Optional URL to POST change alerts to as JSON ({"alerts": \[...]}). Leave empty to disable.

## `include_unchanged` (type: `boolean`):

When true (default), every game's normalized lineup row is pushed each run in addition to change alerts. When false, only change-alert rows are pushed — useful for alert-only pipelines.

## Actor input object example

```json
{
  "days_ahead": 0,
  "webhook_url": "",
  "include_unchanged": true
}
```

# Actor output Schema

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

No description

# 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 = {
    "days_ahead": 0,
    "include_unchanged": true
};

// Run the Actor and wait for it to finish
const run = await client.actor("ichigowa/mlb-lineups-alert").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 = {
    "days_ahead": 0,
    "include_unchanged": True,
}

# Run the Actor and wait for it to finish
run = client.actor("ichigowa/mlb-lineups-alert").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 '{
  "days_ahead": 0,
  "include_unchanged": true
}' |
apify call ichigowa/mlb-lineups-alert --silent --output-dataset

```

## MCP server setup

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

```

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/XCGtntrm5WhUUdMYq/builds/waQX0B31Hk26TT4Wg/openapi.json