MLB APIbaseballsavant.mlb.com ↗
Access MLB Statcast batting leaderboard and player power stats via API. Barrel rate, exit velocity, xwOBA, hard-hit %, and swing speed for qualified batters.
What is the MLB API?
This API exposes two endpoints covering Baseball Savant's Statcast batting leaderboard and individual player power metrics, returning over 15 distinct stat fields per batter. The get_batting_leaderboard endpoint retrieves sortable, filterable leaderboard data for all qualified MLB batters in a given season, while get_player_power_stats returns per-player detail including barrel count, xwOBA, xSLG, walk total, and plate appearance splits down to the single and double level.
curl -X GET 'https://api.parse.bot/scraper/50ea5f20-7d11-4dc2-8879-d61e60e9c422/get_batting_leaderboard?sort=home_run&year=2025&limit=20&min_pa=q&sort_dir=asc' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace baseballsavant-mlb-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Baseball Savant batting power stats — bounded, re-runnable."""
from parse_apis.Baseball_Savant_Batting_Stats_API import (
BaseballSavant, SortField, SortDirection, MinPA, PlayerNotFound
)
client = BaseballSavant()
# Search for top HR hitters, sorted by home runs descending
for batter in client.batters.search(sort=SortField.HOME_RUN, sort_dir=SortDirection.DESC, min_pa=MinPA.QUALIFIED, limit=5):
print(f"{batter.player_name}: {batter.home_run} HR, barrel%={batter.barrel_batted_rate}, xwOBA={batter.xwoba}")
# Drill into the top power hitter by exit velocity
top = client.batters.search(sort=SortField.EXIT_VELOCITY_AVG, sort_dir=SortDirection.DESC, limit=1).first()
if top:
print(f"\nHardest hitter: {top.player_name}, EV={top.exit_velocity_avg}, HR={top.home_run}")
# Refresh to get full detail
detail = top.refresh()
print(f" Doubles: {detail.double}, Triples: {detail.triple}, ISO: {detail.isolated_power}")
# Get a specific player by ID
try:
player = client.batters.get(player_id="592450")
print(f"\n{player.player_name}: {player.home_run} HR, swing speed={player.avg_swing_speed}, fast_swing_rate={player.fast_swing_rate}")
except PlayerNotFound as exc:
print(f"Player not found: {exc}")
print("\nexercised: batters.search / batters.get / batter.refresh")
Retrieve the Statcast custom batting leaderboard with power and home run metrics. Returns qualified batters sorted by the specified stat field. Includes advanced Statcast metrics like barrel rate, exit velocity, hard-hit percentage, swing speed, and expected stats (xwOBA, xSLG). Data is sourced from the current MLB season's Statcast tracking system. One page of results; use limit to control count.
| Param | Type | Description |
|---|---|---|
| sort | string | Stat field to sort the leaderboard by. |
| year | string | MLB season year (4-digit, e.g. 2025, 2024, 2023). |
| limit | integer | Maximum number of players to return. |
| min_pa | string | Minimum plate appearances filter. 'q' means qualified (league-defined threshold). |
| sort_dir | string | Sort direction. |
{
"type": "object",
"fields": {
"sort": "string",
"year": "string",
"total": "integer",
"min_pa": "string",
"players": "array of batter stat objects with power metrics",
"sort_dir": "string"
},
"sample": {
"sort": "home_run",
"year": "2025",
"total": 5,
"min_pa": "q",
"players": [
{
"ab": 596,
"pa": 705,
"walk": 97,
"woba": ".392",
"xslg": ".547",
"year": 2025,
"xwoba": ".371",
"barrel": 80,
"double": 24,
"single": 63,
"triple": 0,
"home_run": 60,
"k_percent": 26.7,
"player_id": 663728,
"strikeout": 188,
"bb_percent": 13.8,
"player_age": 28,
"batting_avg": ".247",
"player_name": "Raleigh, Cal",
"slg_percent": ".589",
"pull_percent": 54.5,
"avg_best_speed": "103.037930049",
"isolated_power": "0.342",
"avg_hyper_speed": "96.182622409",
"avg_swing_speed": "75.2",
"fast_swing_rate": 54.7,
"on_base_percent": ".359",
"flyballs_percent": 41.8,
"hard_hit_percent": 49.6,
"launch_angle_avg": "25.2",
"on_base_plus_slg": "0.948",
"exit_velocity_avg": "91.3",
"barrel_batted_rate": 19.5,
"sweet_spot_percent": 35.3
}
],
"sort_dir": "desc"
}
}About the MLB API
Leaderboard Endpoint
The get_batting_leaderboard endpoint returns a ranked list of MLB batters with Statcast power metrics for a specified season. Pass a year (e.g. 2024, 2025) and a sort field such as xwoba, barrel_batted_rate, or hard_hit_percent to order results. Set min_pa to q to restrict to league-qualified plate appearance thresholds, or supply a numeric minimum. The sort_dir parameter controls ascending vs. descending order. The response includes a total count alongside a players array, each element containing advanced fields like barrel rate, expected slugging, whiff percentage, swing percentage, and average swing speed (avg_best_speed, avg_hyper_speed).
Player Power Stats Endpoint
get_player_power_stats accepts a required player_id — the numeric MLB identifier found in leaderboard results — and an optional year. The response breaks down individual offensive production into discrete counts: ab, pa, walk, single, double, barrel, plus rate stats woba, xwoba, and xslg. This makes it straightforward to compute derived ratios or correlate expected stats against actual results for a specific batter across seasons.
Coverage and Filtering Notes
Both endpoints are scoped to batting data only. The leaderboard players array and the player-level response share a compatible field set, so IDs from leaderboard results feed directly into get_player_power_stats without additional lookup. Season coverage depends on year availability in the Baseball Savant Statcast database; the year parameter accepts four-digit season strings. Players with fewer than 10 plate appearances are excluded from get_player_power_stats results.
The MLB API is a managed, monitored endpoint for baseballsavant.mlb.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when baseballsavant.mlb.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official baseballsavant.mlb.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Rank all qualified batters by barrel rate for a given season to identify elite contact quality
- Track a specific player's xwOBA vs. wOBA gap across multiple seasons to detect regression or breakout candidates
- Filter hitters by hard-hit percentage to build power-hitting tiers for fantasy baseball draft tools
- Compare swing speed metrics (
avg_best_speed,avg_hyper_speed) across the leaderboard to evaluate raw bat speed - Pull single, double, and barrel counts for a player to build custom wRC+ or ISO models
- Monitor year-over-year xSLG trends for a roster of players using repeated
get_player_power_statscalls - Feed leaderboard data into a dashboard showing walk rate and whiff rate distributions across all MLB batters
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Baseball Savant have an official developer API?+
What does get_batting_leaderboard return and how do I filter it?+
players array where each entry includes fields like woba, xwoba, xslg, barrel_batted_rate, hard_hit_percent, whiff_percent, swing_percent, avg_best_speed, and avg_hyper_speed. Use the sort parameter to order by any of these fields, sort_dir for direction, min_pa to enforce a plate appearance floor (use q for the qualified threshold), year for season, and limit to cap result count.Does the API cover pitching Statcast metrics or only batting?+
Can I retrieve game-level or at-bat-level data rather than season aggregates?+
What is the minimum plate appearance threshold enforced by get_player_power_stats?+
min_pa=q to enforce the league-defined qualified threshold, or supply an explicit numeric value.