# FastballAPI

> The baseball data API. 20 baseball data tools for AI agents. REST API + MCP server.

Full reference with response shapes: https://fastballapi.com/llms-full.txt
MCP server setup: https://fastballapi.com/llms-install.md
MCP server for AI agents (clients, prompts, every tool): https://fastballapi.com/mcp
Datasets with live coverage by season: https://fastballapi.com/docs/atlas
Tool catalogue with JSON Schema: https://mcp.fastballapi.com/v1/tools
OpenAPI 3.1 spec: https://mcp.fastballapi.com/openapi.json

## Quick Start

- API base URL: https://mcp.fastballapi.com
- Auth: `Authorization: Bearer YOUR_API_KEY` or `x-api-key: YOUR_API_KEY`
- MCP server: `https://mcp.fastballapi.com/mcp?key=YOUR_API_KEY`
- Python client: `pip install fastballapi` (https://pypi.org/project/fastballapi/). Reads FASTBALLAPI_API_KEY.
- 500 free credits every month, no credit card required
- REST API responses include `X-Credits-Used` and `X-Credits-Remaining` headers
- Seasons: a 4-digit year. Team codes like NYY, LAD, BOS (or a team id); list_teams has them. Game ids like 401569531 (a game id; find them with get_games).

## Data timing and rights

- Odds and props are pre-game only. captured_at is when a line was captured (the page says exactly what it means for each kind of row); where props are held, rows also carry scheduled_start and minutes_before_scheduled_start (negative when captured after the scheduled start).
- Records are overwritten when sources correct them; no revision history is kept.
- You may store the data, train models, backtest, and build commercial products that show your users what you derive. You may not redistribute the data, or odds as a raw feed, as a dataset or API of its own. After an account closes, stored data is for internal use only.
- FastballAPI is independent, not an official league partner, and grants no league rights.
- Full answers: https://fastballapi.com/docs/timing-and-rights

## Which Tool Should I Use?

### Static reference
- Team ids, abbreviations and colours for a season -> list_teams (1 cr)
- Find players by name -> search_players (1 cr)

### Basic lookup
- Games with runs, hits and errors by season, date, range or team -> get_games (2 cr)
- Upcoming games with the median line across sportsbooks -> get_schedule (2 cr)
- Standings from every final game, with run differential and Pythagorean record -> get_standings (2 cr)
- The latest injury report -> get_injuries (2 cr)
- Our team Elo ratings, ranked -> get_ratings (2 cr)

### Stats + aggregation
- One game: every batting and pitching line, each book's line, win probability -> get_game (5 cr)
- Season batting (AVG, OBP, SLG, OPS, RE24) and pitching (ERA, WHIP, K/9) -> get_player (5 cr)
- A player's full batting and pitching game log -> get_player_games (5 cr)
- Season leaders among qualified batters and pitchers -> get_leaders (5 cr)
- Runs for and against, team batting and opponents' batting -> get_team_stats (5 cr)
- A pitcher's arsenal: usage, velocity, whiff rate per pitch type -> get_pitch_mix (5 cr)
- Every sportsbook's moneyline, run line and total for a game (5) or a day (10) -> get_odds (5 cr)

### Multi-table
- Plate-appearance play-by-play with base-out state, batted ball, win probability, RE24 -> get_plate_appearances (10 cr)
- Pitch-by-pitch: count, type, velocity, location, result -> get_pitches (10 cr)
- Where a batter or team hits the ball, by trajectory and field -> get_spray_chart (10 cr)
- Player prop lines by sportsbook: the closing line (one pre-game capture per line before October 2026) -> get_player_props (10 cr)
- A player's prop lines against the result, game by game -> get_prop_history (10 cr)

### Time-series
- Snapshots of each sportsbook's line before first pitch -> get_line_movement (10 cr)

## Intents

- "Last night's MLB scores" -> get_games
- "This week's games and the lines" -> get_schedule
- "Box score and every book's line for one game" -> get_game
- "Who is on the injured list?" -> get_injuries
- "What is Bryce Harper's player id?" -> search_players
- "Harper's OPS by season" -> get_player
- "Every game Harper played in 2025" -> get_player_games
- "Who led the league in OPS, or ERA?" -> get_leaders
- "Which team scored the most runs per game?" -> get_team_stats
- "Every plate appearance with runners in scoring position" -> get_plate_appearances
- "Every pitch a pitcher threw" -> get_pitches
- "What does this pitcher throw, and how hard?" -> get_pitch_mix
- "Where does Harper hit the ball?" -> get_spray_chart
- "Did the favourite win, and did the total go over?" -> get_odds
- "How did the line move before first pitch?" -> get_line_movement
- "Who is the best team right now?" -> get_ratings
- "The standings and run differential" -> get_standings
- "Team ids and abbreviations" -> list_teams
- "What was the closing hits line for this player, and which book had the best price?" -> get_player_props
- "How often does this player go over his hits line?" -> get_prop_history

## Pages

- [Docs](https://fastballapi.com/docs): every endpoint, with parameters and a live example response.
- [Data changelog](https://fastballapi.com/changelog): when each dataset was last refreshed and what it runs through, read from the database.
- [Status](https://fastballapi.com/status): measured uptime for the website and MCP server over 24 hours, 7 days and 90 days, probed every five minutes from outside our own infrastructure, with incidents and data freshness.
- [Data atlas](https://fastballapi.com/docs/atlas): what exists, which endpoints expose it, and where coverage is partial.
- [Teams](https://fastballapi.com/teams): a page per club with its record, season figures and recent games.
- [Players](https://fastballapi.com/players): a page per MLB player with prop history: the over/under record against the closing line in each market (hits, home runs, total bases, RBI, pitcher strikeouts and more) and the last games.
- [Data timing and rights](https://fastballapi.com/docs/timing-and-rights): what timestamps mean, when each dataset updates, whether lines are pre-game, and what the terms allow.
- [Pricing](https://fastballapi.com/pricing): credits per call and what a plan includes.
- [Sign up](https://fastballapi.com/signup): 500 free credits every month, no card.

### Live odds

- [Upcoming MLB odds](https://fastballapi.com/odds): Moneylines, run lines and totals for the next week's MLB games by sportsbook, captured daily and every hour for games in the next four days.
- [MLB player props today](https://fastballapi.com/props): Today's MLB player props: hits, home runs, total bases, RBIs, pitcher strikeouts and pitcher outs, with the consensus line and the best over and under price across sportsbooks.

### Other leagues

- [The college baseball API](https://fastballapi.com/college-baseball): NCAA Division I baseball: the postseason since 2010, scores since 2015, box scores and plate appearances since 2020 for part of each season. REST and MCP. MCP: https://mcp.fastballapi.com/mcp/ncaabase

### Datasets

- [MLB pitch-by-pitch data](https://fastballapi.com/data/mlb-pitch-by-pitch): MLB pitch-by-pitch since 2015 (about 98% of games to 2017, all from 2018): pitch type, velocity, location and the count, with the plate appearance. REST or MCP.
- [MLB spray chart data](https://fastballapi.com/data/mlb-spray-chart-data): Where every ball in play went, with its trajectory (ground ball, line drive, fly ball, pop-up) and result, for any batter or team. REST or MCP.
- [MLB odds history](https://fastballapi.com/data/mlb-odds-history): Each sportsbook's moneyline, run line and total for MLB games, with whether the favourite won and the total went over. Built for backtests. REST or MCP.
- [MLB player props by sportsbook, from 2023](https://fastballapi.com/data/player-props): MLB player prop lines by sportsbook since May 2023: the closing line, and the opening line where held, with each player's history against his line. REST or MCP.

### Compared with the alternatives

- [The MLB API: free endpoints, Statcast and FastballAPI](https://fastballapi.com/compare/mlb-api): The MLB Stats API, Baseball Savant, pybaseball and Retrosheet are free but not equal. Where each fits, what the terms allow, and how FastballAPI differs. (checked 2026-10-14)
- [FastballAPI vs pybaseball](https://fastballapi.com/compare/pybaseball): pybaseball is a free Python package that scrapes several public baseball sites. FastballAPI is a hosted API with pitch-level data, sportsbook lines and an MCP server. (checked 2026-10-07)
- [FastballAPI vs BallDontLie](https://fastballapi.com/compare/balldontlie-mlb): BallDontLie is a multi-sport API with plans sold per sport. FastballAPI is baseball only, with every pitch and plate appearance, per-book lines and run values. (checked 2026-10-07)
- [FastballAPI vs Sportradar](https://fastballapi.com/compare/sportradar-mlb): Sportradar sells official, real-time league data under enterprise contracts. FastballAPI is a self-serve historical and daily API with per-book lines. (checked 2026-10-07)
- [FastballAPI vs the MLB Stats API](https://fastballapi.com/compare/mlb-stats-api): The MLB Stats API is undocumented JSON, and MLB's use policy allows only individual, non-commercial, non-bulk use. FastballAPI is a keyed, documented API. (checked 2026-10-09)
- [Historical MLB player prop odds APIs, compared](https://fastballapi.com/compare/mlb-player-prop-odds-api): Five APIs that serve MLB player props, by how far back the history goes, whether they return results, books, price and MCP support. Checked against each provider's site. (checked 2026-10-21)

### Endpoint pages

- [list_teams](https://fastballapi.com/docs/list-teams): Team ids, abbreviations and colours for a season
- [get_games](https://fastballapi.com/docs/get-games): Games with runs, hits and errors by season, date, range or team
- [get_schedule](https://fastballapi.com/docs/get-schedule): Upcoming games with the median line across sportsbooks
- [get_game](https://fastballapi.com/docs/get-game): One game: every batting and pitching line, each book's line, win probability
- [get_standings](https://fastballapi.com/docs/get-standings): Standings from every final game, with run differential and Pythagorean record
- [get_injuries](https://fastballapi.com/docs/get-injuries): The latest injury report
- [search_players](https://fastballapi.com/docs/search-players): Find players by name
- [get_player](https://fastballapi.com/docs/get-player): Season batting (AVG, OBP, SLG, OPS, RE24) and pitching (ERA, WHIP, K/9)
- [get_player_games](https://fastballapi.com/docs/get-player-games): A player's full batting and pitching game log
- [get_leaders](https://fastballapi.com/docs/get-leaders): Season leaders among qualified batters and pitchers
- [get_team_stats](https://fastballapi.com/docs/get-team-stats): Runs for and against, team batting and opponents' batting
- [get_plate_appearances](https://fastballapi.com/docs/get-plate-appearances): Plate-appearance play-by-play with base-out state, batted ball, win probability, RE24
- [get_pitches](https://fastballapi.com/docs/get-pitches): Pitch-by-pitch: count, type, velocity, location, result
- [get_pitch_mix](https://fastballapi.com/docs/get-pitch-mix): A pitcher's arsenal: usage, velocity, whiff rate per pitch type
- [get_spray_chart](https://fastballapi.com/docs/get-spray-chart): Where a batter or team hits the ball, by trajectory and field
- [get_odds](https://fastballapi.com/docs/get-odds): Every sportsbook's moneyline, run line and total for a game (5) or a day (10)
- [get_line_movement](https://fastballapi.com/docs/get-line-movement): Snapshots of each sportsbook's line before first pitch
- [get_ratings](https://fastballapi.com/docs/get-ratings): Our team Elo ratings, ranked
- [get_player_props](https://fastballapi.com/docs/get-player-props): Player prop lines by sportsbook: the closing line (one pre-game capture per line before October 2026)
- [get_prop_history](https://fastballapi.com/docs/get-prop-history): A player's prop lines against the result, game by game

### Metric definitions

- [RE24](https://fastballapi.com/glossary/re24): The runs a plate appearance added or cost: the change in run expectancy for the base-out state, plus any runs that scored.
- [Run expectancy](https://fastballapi.com/glossary/run-expectancy): The average number of runs a team scores from a given base-out state to the end of the inning.
- [Base-out state](https://fastballapi.com/glossary/base-out-state): The number of outs and which bases are occupied: the situation a plate appearance starts in.
- [OPS](https://fastballapi.com/glossary/ops): On-base percentage plus slugging percentage: how often a hitter reaches and how much damage the hits do, in one number.
- [Strikeout rate](https://fastballapi.com/glossary/strikeout-rate): Strikeouts as a share of plate appearances; walk rate is the same for walks.
- [Whiff rate](https://fastballapi.com/glossary/whiff-rate): Swinging strikes as a share of swings: how often a pitch makes hitters miss when they go after it.
- [Pitch mix](https://fastballapi.com/glossary/pitch-mix): What a pitcher throws and how often: each pitch type's share, velocity and results.
- [Spray chart](https://fastballapi.com/glossary/spray-chart): Where a hitter's balls in play go, as points on the field, with their trajectory.
- [Batted ball trajectory](https://fastballapi.com/glossary/batted-ball-trajectory): Whether a ball in play was a ground ball, a line drive, a fly ball or a pop-up.
- [Pythagorean record](https://fastballapi.com/glossary/pythagorean-record): The win percentage a team's runs scored and allowed predict, which says how much of its record was luck in close games.
- [Elo rating](https://fastballapi.com/glossary/elo-rating): Our running team strength number: up after a win, down after a loss, by more when the result was a surprise.
- [Win probability](https://fastballapi.com/glossary/win-probability): The home team's chance of winning after each plate appearance, as computed upstream, from 2019.
- [Implied probability](https://fastballapi.com/glossary/implied-probability): The win chance a moneyline implies, with the book's margin still in it.
- [Closing line](https://fastballapi.com/glossary/closing-line): A sportsbook's last price before first pitch, the market's final word on the game.
- [Line movement](https://fastballapi.com/glossary/line-movement): How a game's price changed between opening and first pitch.
- [Run line](https://fastballapi.com/glossary/run-line): Baseball's point spread: almost always a run and a half, with the price doing the work.

### By what you are building

- [Analysts and researchers](https://fastballapi.com/for/analysts): Pitch type, velocity, location and count for every pitch; base-out state, batted ball and RE24 for every plate appearance.
- [Bettors and modelers](https://fastballapi.com/for/bettors): Moneyline, run line and total from 4 to 13 books per game from 2015 to 2023, with opening and closing lines from 6 to 8 books since July 2020, joined to the result, our ratings and the box score.
- [App and AI developers](https://fastballapi.com/for/developers): 20 endpoints over REST and MCP: schedules, box scores, standings, players, every pitch, every plate appearance, odds and ratings.

### Code guides

Python, JavaScript and cURL for common questions, each run against the live API (code verified 2026-10-21). Index: https://fastballapi.com/guides

- [Where do I get MLB pitch-by-pitch data for a model?](https://fastballapi.com/guides/mlb-pitch-data-for-a-model): Every pitch a pitcher threw, with count, type, velocity, location and result, loaded into pandas with a swinging-strike label ready for a classifier. Tool: get_pitches.
- [How do I get a pitcher's pitch mix and whiff rate in Python?](https://fastballapi.com/guides/mlb-pitch-mix-and-whiff-rate-python): A pitcher's arsenal for a season: how often each pitch is thrown, how hard, and how often it draws a swing and a miss. Tool: get_pitch_mix.
- [How do I build an MLB spray chart in Python?](https://fastballapi.com/guides/mlb-spray-chart-python): Where a hitter puts the ball in play, by trajectory and field, plus the x and y of every ball in play if you want to draw it. Tool: get_spray_chart.
- [How do I find MLB teams that over- or underperformed their run differential?](https://fastballapi.com/guides/mlb-pythagorean-standings-pandas): Standings from every final game, with run differential and the Pythagorean win percentage, so you can see who won more or fewer games than their runs say. Tool: get_standings.
- [How do I measure a hitter's run value with runners in scoring position?](https://fastballapi.com/guides/mlb-run-value-with-runners-in-scoring-position): Every plate appearance with a runner on second or third, with the base-out state before it, the result, and the run value it added or cost. Tool: get_plate_appearances.
- [How do I backtest MLB closing moneylines and run totals in Python?](https://fastballapi.com/guides/backtest-mlb-moneylines-and-totals-python): A day of games with each sportsbook's opening and closing moneyline, run line and total, next to the result. It counts favourite wins and overs. Tool: get_odds.
- [How do I get MLB pitcher strikeout prop lines and results?](https://fastballapi.com/guides/mlb-pitcher-strikeout-prop-lines-python): One row per start with the strikeout line at open and close, the over and under prices and the strikeouts he recorded. Tarik Skubal went over in 12 of 25. Tool: get_prop_history.
- [How do I get MLB scores and the schedule in Python?](https://fastballapi.com/guides/mlb-scores-and-schedule-python): MLB results for a date range with runs by team and the winner. Eight postseason games were final from October 6 to 10. Tool: get_games.
- [How do I get MLB home run leaders and stat leaders in Python?](https://fastballapi.com/guides/mlb-home-run-leaders-python): MLB home run leaders for 2026 among qualified hitters, with batting line and strikeout rate. Kyle Schwarber and Pete Crow-Armstrong tied at 45. Tool: get_leaders.
- [How do I get the MLB injury report in Python?](https://fastballapi.com/guides/mlb-injury-report-python): The MLB injury report as of October 11: 283 listed players with status, injury and expected return, 171 of them on the 60-day injured list. Tool: get_injuries.
- [How often does an MLB hitter go over his total bases line?](https://fastballapi.com/guides/mlb-total-bases-prop-history-python): One row per game with a hitter's total bases line, the price, what he recorded and the result. Aaron Judge went over 1.5 in 27 of 63 graded games in 2026. Tool: get_prop_history.
- [How often does an MLB slugger hit a home run when it is priced?](https://fastballapi.com/guides/mlb-home-run-prop-history-python): Every game's home run price for a hitter against whether he went deep. Shohei Ohtani homered in 28 of 139 graded games in 2026, usually priced +150 to +300. Tool: get_prop_history.
- [How often does an MLB hitter go over his hits line?](https://fastballapi.com/guides/mlb-hits-prop-history-python): One row per game with a hitter's hits line, the price and his hits. Bobby Witt Jr. went over in 48 of 136 graded games in 2026, with the line set at 0.5 or 1.5. Tool: get_prop_history.

### Claude skills

16 free Claude skills (SKILL.md files) wired to these tools: https://github.com/noahowsh/fastballapi-mcp/tree/main/skills. Overview: https://fastballapi.com/skills

- game-lookup (Data Exploration): Scores, schedules and full box scores for MLB and college baseball.
- team-analysis (Data Exploration): Standings, team batting and run prevention, and Elo power ratings.
- player-scouting (Data Exploration): Player lines, game logs, season leaders and injuries, compared fairly.
- odds-explorer (Data Exploration): Best price, opening vs closing and line movement across sportsbooks.
- game-preview (Data Exploration): One-matchup pre-game report: form, ratings, injuries and the market.
- pitch-mix-analysis (Baseball Analytics): Pitch usage, velocity and whiff rate per swing for any MLB pitcher.
- run-value-analysis (Baseball Analytics): RE24, base-out state, RISP splits and win probability by plate appearance.
- spray-chart-analysis (Baseball Analytics): Where a batter hits the ball: trajectory, field, HR per fly ball, x/y plots.
- pythagorean-record (Baseball Analytics): Expected record from runs scored and allowed, and how much is luck.
- walk-forward-validation (Methodology): Leakage-safe features, time-ordered splits, baselines and calibration.
- odds-analysis (Methodology): Convert odds and remove the margin with multiplicative, power and Shin methods.
- edge-detection (Betting): Expected value, fractional Kelly, line shopping and closing line value.
- backtesting (Betting): Test a strategy on closing lines and prop history with honest intervals.
- prop-modeling (Betting): Pitcher strikeout, hits and total bases projections vs the devigged market.
- dispatch (Workflow): Routes a baseball request to the right two or three skills.
- fastballapi-tool (Infrastructure): All 20 tools, credit costs, coverage limits and the data response envelope.