# MLB API

> MLB returns baseball scores, standings, and player stats as a workflow and API.

MLB returns scores and scheduled games through Get scores, using a date, days, optional team, and time zone. Get standings returns MLB regular-season division standings for a season, defaulting to the current year. Get player stats returns a player profile and regular-season stats, using a player name and optional season.

- Page: https://fous.com/workflows/mlb
- Handle: `@mlb`
- Category: [Sports](https://fous.com/workflows/category/sports)
- Source website: https://mlb.com
- Last verified: Sep 29, 2026
- Fous is not affiliated with MLB.

## Methods

### Get player stats

Operation `get_player_stats`, version 1. 1 credit per call.

Get a baseball player’s profile and MLB regular-season hitting and pitching statistics for a selected season and career. If no season is given, uses the current season when available, otherwise the latest MLB season.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `player` | string | yes | `"Shohei Ohtani"` | Baseball player name, for example Shohei Ohtani. |
| `season` | integer | no | `2025` | MLB season year, for example 2025. Defaults to the current season if the player has stats, otherwise the latest season. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "player"
  ],
  "properties": {
    "player": {
      "type": "string",
      "minLength": 1,
      "description": "Baseball player name, for example Shohei Ohtani.",
      "examples": [
        "Shohei Ohtani",
        "Babe Ruth",
        "Aaron Judge"
      ]
    },
    "season": {
      "type": "integer",
      "maximum": 2100,
      "minimum": 1871,
      "description": "MLB season year, for example 2025. Defaults to the current season if the player has stats, otherwise the latest season.",
      "examples": [
        2025,
        2024
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "player": "Shohei Ohtani",
      "season": 2025
    },
    {
      "player": "Shohei Ohtani"
    },
    {
      "player": "Babe Ruth"
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `age` | integer or null | `32` | Age listed in the MLB player profile. |
| `bats` | string or null | `"Left"` | Batting side. |
| `name` | string | `"Shohei Ohtani"` | Player name. |
| `team` | string or null | `"Los Angeles Dodgers"` | Season team, or listed team when the selected season has no stats. |
| `season` | integer | `2025` | Season used for season statistics. |
| `throws` | string or null | `"Right"` | Throwing hand. |
| `position` | string or null | `"Two-Way Player"` | Player position. |
| `player_id` | integer | `660271` | MLB player ID. |
| `player_link` | string | `"https://www.mlb.com/player/shohei-ohtani-660271"` | MLB.com player page. |
| `career_hitting` | object or null |  | MLB regular-season stats, or null when the player has none in this category. |
| `career_hitting.hits` | integer or null | `1194` | Hits. |
| `career_hitting.games` | integer or null | `1172` | Games. |
| `career_hitting.at_bats` | integer or null | `4253` | At bats. |
| `career_hitting.home_runs` | integer or null | `310` | Home runs. |
| `career_hitting.stolen_bases` | integer or null | `176` | Stolen bases. |
| `career_hitting.runs_batted_in` | integer or null | `750` | Runs batted in. |
| `career_hitting.batting_average` | number or null | `0.281` | Batting average. |
| `career_hitting.on_base_percentage` | number or null | `0.375` | On base percentage. |
| `career_hitting.slugging_percentage` | number or null | `0.574` | Slugging percentage. |
| `career_hitting.on_base_plus_slugging` | number or null | `0.949` | On base plus slugging. |
| `season_hitting` | object or null |  | MLB regular-season stats, or null when the player has none in this category. |
| `season_hitting.hits` | integer or null | `172` | Hits. |
| `season_hitting.games` | integer or null | `158` | Games. |
| `season_hitting.at_bats` | integer or null | `611` | At bats. |
| `season_hitting.home_runs` | integer or null | `55` | Home runs. |
| `season_hitting.stolen_bases` | integer or null | `20` | Stolen bases. |
| `season_hitting.runs_batted_in` | integer or null | `102` | Runs batted in. |
| `season_hitting.batting_average` | number or null | `0.282` | Batting average. |
| `season_hitting.on_base_percentage` | number or null | `0.392` | On base percentage. |
| `season_hitting.slugging_percentage` | number or null | `0.622` | Slugging percentage. |
| `season_hitting.on_base_plus_slugging` | number or null | `1.014` | On base plus slugging. |
| `career_pitching` | object or null |  | MLB regular-season stats, or null when the player has none in this category. |
| `career_pitching.wins` | integer or null | `47` | Wins. |
| `career_pitching.saves` | integer or null | `0` | Saves. |
| `career_pitching.walks` | integer or null | `208` | Walks. |
| `career_pitching.losses` | integer or null | `22` | Losses. |
| `career_pitching.strikeouts` | integer or null | `765` | Strikeouts. |
| `career_pitching.innings_pitched` | string or null | `"614.1"` | Baseball innings notation (for example 47.1 means 47 innings and one out). |
| `career_pitching.earned_run_average` | number or null | `2.83` | Earned run average. |
| `career_pitching.walks_plus_hits_per_inning_pitched` | number or null | `1.06` | Walks plus hits per inning pitched. |
| `season_pitching` | object or null |  | MLB regular-season stats, or null when the player has none in this category. |
| `season_pitching.wins` | integer or null | `1` | Wins. |
| `season_pitching.saves` | integer or null | `0` | Saves. |
| `season_pitching.walks` | integer or null | `9` | Walks. |
| `season_pitching.losses` | integer or null | `1` | Losses. |
| `season_pitching.strikeouts` | integer or null | `62` | Strikeouts. |
| `season_pitching.innings_pitched` | string or null | `"47.0"` | Baseball innings notation (for example 47.1 means 47 innings and one out). |
| `season_pitching.earned_run_average` | number or null | `2.87` | Earned run average. |
| `season_pitching.walks_plus_hits_per_inning_pitched` | number or null | `1.04` | Walks plus hits per inning pitched. |
| `headshot_image_link` | string | `"https://img.mlbstatic.com/mlb-photos/image/upload/v1/people/660271/headshot/67/current"` | Player headshot image link. |

**Example input**

```json
{
  "player": "Shohei Ohtani",
  "season": 2025
}
```

**Example output**

```json
{
  "age": 32,
  "bats": "Left",
  "name": "Shohei Ohtani",
  "team": "Los Angeles Dodgers",
  "season": 2025,
  "throws": "Right",
  "position": "Two-Way Player",
  "player_id": 660271,
  "player_link": "https://www.mlb.com/player/shohei-ohtani-660271",
  "career_hitting": {
    "hits": 1194,
    "games": 1172,
    "at_bats": 4253,
    "home_runs": 310,
    "stolen_bases": 176,
    "runs_batted_in": 750,
    "batting_average": 0.281,
    "on_base_percentage": 0.375,
    "slugging_percentage": 0.574,
    "on_base_plus_slugging": 0.949
  },
  "season_hitting": {
    "hits": 172,
    "games": 158,
    "at_bats": 611,
    "home_runs": 55,
    "stolen_bases": 20,
    "runs_batted_in": 102,
    "batting_average": 0.282,
    "on_base_percentage": 0.392,
    "slugging_percentage": 0.622,
    "on_base_plus_slugging": 1.014
  },
  "career_pitching": {
    "wins": 47,
    "saves": 0,
    "walks": 208,
    "losses": 22,
    "strikeouts": 765,
    "innings_pitched": "614.1",
    "earned_run_average": 2.83,
    "walks_plus_hits_per_inning_pitched": 1.06
  },
  "season_pitching": {
    "wins": 1,
    "saves": 0,
    "walks": 9,
    "losses": 1,
    "strikeouts": 62,
    "innings_pitched": "47.0",
    "earned_run_average": 2.87,
    "walks_plus_hits_per_inning_pitched": 1.04
  },
  "headshot_image_link": "https://img.mlbstatic.com/mlb-photos/image/upload/v1/people/660271/headshot/67/current"
}
```

### Get scores

Operation `get_scores`, version 1. 1 credit per call.

Get MLB scores and scheduled games for a date or up to seven days, optionally for one team. Start times use the requested time zone; unannounced times and unavailable game details are null.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `date` | string | no | `"2026-09-29"` | First calendar date to show, for example 2026-09-29. Defaults to today. |
| `days` | integer | no | `1` | Number of consecutive calendar days to show, for example 7. |
| `team` | string | no | `"Yankees"` | Team name to include, for example New York Yankees or Yankees. |
| `time_zone` | string | no | `"America/Los_Angeles"` | Time zone for game start times, for example US Eastern or America/Los_Angeles. |

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "date": {
      "type": "string",
      "format": "date",
      "description": "First calendar date to show, for example 2026-09-29. Defaults to today.",
      "examples": [
        "2026-09-29",
        "2026-09-27"
      ]
    },
    "days": {
      "type": "integer",
      "default": 1,
      "maximum": 7,
      "minimum": 1,
      "description": "Number of consecutive calendar days to show, for example 7.",
      "examples": [
        1,
        7
      ]
    },
    "team": {
      "type": "string",
      "description": "Team name to include, for example New York Yankees or Yankees.",
      "examples": [
        "Yankees",
        "New York Yankees",
        "Mets"
      ]
    },
    "time_zone": {
      "type": "string",
      "default": "US Eastern",
      "description": "Time zone for game start times, for example US Eastern or America/Los_Angeles.",
      "examples": [
        "America/Los_Angeles"
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "date": "2026-09-29",
      "days": 1
    },
    {
      "date": "2026-09-27",
      "team": "Yankees"
    },
    {
      "date": "2026-09-29",
      "team": "New York Yankees"
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `games` | array |  | Games in start-time order. |
| `games[].date` | string | `"2026-09-29"` | Official game date. |
| `games[].inning` | string or null |  | Current half-inning for live games. |
| `games[].status` | string | `"scheduled"` | Scheduled, live, final, postponed or cancelled. |
| `games[].game_id` | integer | `849845` | MLB game ID. |
| `games[].ballpark` | string or null | `"Truist Park"` |  |
| `games[].away_runs` | integer or null | `4` |  |
| `games[].away_team` | string | `"Philadelphia Phillies"` |  |
| `games[].game_link` | string | `"https://www.mlb.com/gameday/849845"` |  |
| `games[].home_runs` | integer or null | `6` |  |
| `games[].home_team` | string | `"Atlanta Braves"` |  |
| `games[].start_time` | string or null | `"2026-09-29T14:00:00-04:00"` | Scheduled start in the selected time zone; null when not announced. |
| `games[].tv_channels` | array |  |  |
| `games[].losing_pitcher` | string or null | `"Sean Manaea"` |  |
| `games[].winning_pitcher` | string or null | `"Will Dion"` |  |
| `games[].away_probable_pitcher` | string or null | `"Jesús Luzardo"` |  |
| `games[].home_probable_pitcher` | string or null | `"Chris Sale"` |  |

**Example input**

```json
{
  "date": "2026-09-29",
  "days": 1
}
```

**Example output**

```json
{
  "games": [
    {
      "date": "2026-09-29",
      "inning": null,
      "status": "scheduled",
      "game_id": 849845,
      "ballpark": "Truist Park",
      "away_runs": null,
      "away_team": "Philadelphia Phillies",
      "game_link": "https://www.mlb.com/gameday/849845",
      "home_runs": null,
      "home_team": "Atlanta Braves",
      "start_time": "2026-09-29T14:00:00-04:00",
      "tv_channels": [
        "NBC/Peacock",
        "Universo/ Peacock"
      ],
      "losing_pitcher": null,
      "winning_pitcher": null,
      "away_probable_pitcher": "Jesús Luzardo",
      "home_probable_pitcher": "Chris Sale"
    },
    {
      "date": "2026-09-29",
      "inning": null,
      "status": "scheduled",
      "game_id": 849849,
      "ballpark": "Daikin Park",
      "away_runs": null,
      "away_team": "Chicago White Sox",
      "game_link": "https://www.mlb.com/gameday/849849",
      "home_runs": null,
      "home_team": "Houston Astros",
      "start_time": "2026-09-29T17:00:00-04:00",
      "tv_channels": [
        "Peacock/NBCSN",
        "Universo/ Peacock"
      ],
      "losing_pitcher": null,
      "winning_pitcher": null,
      "away_probable_pitcher": "Hagen Smith",
      "home_probable_pitcher": "AJ Blubaugh"
    },
    {
      "date": "2026-09-29",
      "inning": null,
      "status": "scheduled",
      "game_id": 849851,
      "ballpark": "Yankee Stadium",
      "away_runs": null,
      "away_team": "Boston Red Sox",
      "game_link": "https://www.mlb.com/gameday/849851",
      "home_runs": null,
      "home_team": "New York Yankees",
      "start_time": "2026-09-29T20:00:00-04:00",
      "tv_channels": [
        "NBC/Peacock",
        "Universo/ Peacock"
      ],
      "losing_pitcher": null,
      "winning_pitcher": null,
      "away_probable_pitcher": "Payton Tolle",
      "home_probable_pitcher": "Cam Schlittler"
    }
  ]
}
```

### Get standings

Operation `get_standings`, version 1. 1 credit per call.

Get MLB regular-season division standings for a season, including team records, streaks, last 10 games, and wild-card games back when available. Defaults to the current year.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `season` | integer | no | `2025` | MLB season year, for example 2025. Defaults to the current year. |

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "season": {
      "type": "integer",
      "minimum": 1876,
      "description": "MLB season year, for example 2025. Defaults to the current year.",
      "examples": [
        2025
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "season": 2025
    },
    {}
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `teams` | array |  | Teams ordered by league, division, and division rank. |
| `teams[].rank` | integer | `1` |  |
| `teams[].team` | string | `"Toronto Blue Jays"` |  |
| `teams[].wins` | integer | `94` |  |
| `teams[].league` | string | `"American League"` |  |
| `teams[].losses` | integer | `68` |  |
| `teams[].streak` | string or null | `"Won 4"` |  |
| `teams[].last_10` | string or null | `"5-5"` |  |
| `teams[].division` | string | `"AL East"` |  |
| `teams[].page_url` | string | `"https://www.mlb.com/bluejays"` |  |
| `teams[].games_back` | string or null | `"-"` |  |
| `teams[].win_percentage` | number | `0.58` |  |
| `teams[].wild_card_games_back` | string or null | `"+7.0"` |  |
| `season` | integer | `2025` | Standings season year. |

**Example input**

```json
{
  "season": 2025
}
```

**Example output**

```json
{
  "teams": [
    {
      "rank": 1,
      "team": "Toronto Blue Jays",
      "wins": 94,
      "league": "American League",
      "losses": 68,
      "streak": "Won 4",
      "last_10": "5-5",
      "division": "AL East",
      "page_url": "https://www.mlb.com/bluejays",
      "games_back": "-",
      "win_percentage": 0.58,
      "wild_card_games_back": null
    },
    {
      "rank": 2,
      "team": "New York Yankees",
      "wins": 94,
      "league": "American League",
      "losses": 68,
      "streak": "Won 8",
      "last_10": "9-1",
      "division": "AL East",
      "page_url": "https://www.mlb.com/yankees",
      "games_back": "-",
      "win_percentage": 0.58,
      "wild_card_games_back": "+7.0"
    },
    {
      "rank": 3,
      "team": "Boston Red Sox",
      "wins": 89,
      "league": "American League",
      "losses": 73,
      "streak": "Won 1",
      "last_10": "6-4",
      "division": "AL East",
      "page_url": "https://www.mlb.com/redsox",
      "games_back": "5.0",
      "win_percentage": 0.549,
      "wild_card_games_back": "+2.0"
    }
  ],
  "season": 2025
}
```

## Quick start

Call the API with a Fous API key (`FOUS_API_KEY`). To create one, turn on Developer mode in Fous Studio, then open Keys & connections → API keys (https://app.fous.com/keys).

```bash
# First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
: "${FOUS_API_KEY:?Set FOUS_API_KEY before running this example}"

curl 'https://api.fous.com/v1/query' \
  --fail-with-body --silent --show-error --max-time 120 \
  -H "Authorization: Bearer $FOUS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "api": "@mlb",
  "visibility": "public",
  "operation": "get_player_stats",
  "version": 1,
  "input": {
    "player": "Shohei Ohtani",
    "season": 2025
  },
  "response": {
    "format": "json"
  }
}'
```

```python
# Save as fous.py and run with python3 fous.py. No packages needed.
# First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
import json
import os
import urllib.error
import urllib.request

api_key = os.environ.get("FOUS_API_KEY")
if not api_key:
    raise RuntimeError("Set FOUS_API_KEY before running this example")

body = json.loads("{\n  \"api\": \"@mlb\",\n  \"visibility\": \"public\",\n  \"operation\": \"get_player_stats\",\n  \"version\": 1,\n  \"input\": {\n    \"player\": \"Shohei Ohtani\",\n    \"season\": 2025\n  },\n  \"response\": {\n    \"format\": \"json\"\n  }\n}")
request = urllib.request.Request(
    "https://api.fous.com/v1/query",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=120) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    raise RuntimeError(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}") from error
if result.get("success") is False:
    raise RuntimeError(result.get("error", {}).get("message", "Request failed"))
print(json.dumps(result["data"]["output"], indent=2))
```

```typescript
// Save as fous.mts and run with npx tsx fous.mts.
// First set your key: export FOUS_API_KEY='YOUR_FOUS_API_KEY'
const apiKey = process.env.FOUS_API_KEY;
if (!apiKey) throw new Error("Set FOUS_API_KEY before running this example");

const response = await fetch("https://api.fous.com/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  signal: AbortSignal.timeout(120_000),
  body: JSON.stringify({
  "api": "@mlb",
  "visibility": "public",
  "operation": "get_player_stats",
  "version": 1,
  "input": {
    "player": "Shohei Ohtani",
    "season": 2025
  },
  "response": {
    "format": "json"
  }
}),
});
type ApiResult = { success: boolean; data?: { output: unknown }; error?: { message: string } };
const result: ApiResult = await response.json();
if (!response.ok || result.success === false) {
  throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
if (!result.data) throw new Error("Missing API response data");
console.log(result.data.output);
```

Or describe the data in plain language: send `{"api":"@mlb","prompt":"Describe the data you need, with every detail"}` to the same URL. Fous fills in the input, runs the method that fits and returns only the fields you asked for; `data.route.calls[].request` is the exact call it made. Routing is free; the run costs the same.

## Use cases

- Track scores and scheduled games by date or team
- Review division standings for a selected season
- Compare team records, streaks, and recent results
- Look up a player's season and career stats

## FAQ

### Is Fous affiliated with MLB?

No. Fous is not affiliated with MLB. This workflow reads the public mlb.com website and returns its data.

### How much does it cost?

Each run costs 1 credit. With pay-as-you-go, a credit costs 1¢; monthly plans cost less per credit.

### Do I need a MLB account?

No. You only need a Fous account.

### How current is the data?

Fous gets the data from mlb.com when you run it; repeating the same request within a day may return the saved result. Fous checks this workflow automatically; it last passed a check on Sep 29, 2026.

### What are today's scores and scheduled games?

Get scores returns scores and scheduled games for a date or up to seven days, optionally filtered by team.

### How are teams ranked in a season?

Get standings returns regular-season division rankings and team records for a selected season.

### What are a player's hitting and pitching stats?

Get player stats returns a player's profile and regular-season hitting and pitching statistics for a selected season and career.

## Related

- [Yahoo Sports API](https://fous.com/workflows/yahoo-sports.md): Yahoo Sports returns date-based scores and schedules, seasonal standings, and player regular-season and career stats when Yahoo provides them; unavailable data may be missing.
- [NHL API](https://fous.com/workflows/nhl.md): NHL provides games, schedules, and scores when published, standings by date, and player profiles with regular-season stats; dates outside a season have no teams, and unavailable stats are null.
- [ESPN API](https://fous.com/workflows/espn.md): ESPN provides daily scores and schedules, team results, player statistics, matchup summaries, and latest topic-specific headlines; coverage and published details vary, especially for college and soccer.
- [NFL API](https://fous.com/workflows/nfl.md): NFL provides weekly scores and schedules, regular-season standings, current rosters, and player season and career stats; released players are excluded, and ages or stats may be unavailable.
- [NBA API](https://fous.com/workflows/nba.md): NBA provides up-to-seven-day schedules and scores, seasonal standings, player bios and available regular-season averages, plus matchup box scores, with undated matchups showing the latest.
- [Sports Reference API](https://fous.com/workflows/sports-reference.md): Sports Reference provides regular-season career stats, awards and season records across basketball, football, baseball and hockey, plus season leaders using the latest published season if unspecified.
- [Premier League API](https://fous.com/workflows/premier-league.md): Premier League provides current/chosen-season tables and recent form, date-range fixtures/results (up to 380), player profiles and stats, and seasonal leaders; older-season stats may be limited.
- [NCAA API](https://fous.com/workflows/ncaa.md): NCAA provides college sports scores and schedules from NCAA.com, including date-based games or football weeks, plus latest NCAA.com Top 25 rankings where published.
- [All Sports workflows](https://fous.com/workflows/category/sports)