# FastballAPI

> The baseball data API. 18 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

## 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`
- 500 free credits on signup, 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 an ESPN team id); list_teams has them. Game ids like 401569531 (an ESPN game id; find them with get_games).

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

### Time-series
- Daily 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 2024" -> 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

## 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.
- [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.
- [Pricing](https://fastballapi.com/pricing): credits per call and what a plan includes.
- [Sign up](https://fastballapi.com/signup): 500 free credits, no card.

### Live odds

- [Upcoming MLB odds](https://fastballapi.com/odds): Moneylines, run lines and totals for the next week's MLB games from the sportsbooks ESPN reports, refreshed daily.

### Other leagues

- [The college baseball API](https://fastballapi.com/college-baseball): NCAA Division I baseball from ESPN: 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, every pitch 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.

### Compared with the alternatives

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

### 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): Daily snapshots of each sportsbook's line before first pitch
- [get_ratings](https://fastballapi.com/docs/get-ratings): Our team Elo ratings, ranked

### 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 ESPN computes it, 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, joined to the result, our ratings and the box score.
- [App and AI developers](https://fastballapi.com/for/developers): Eighteen endpoints over REST and MCP: schedules, box scores, standings, players, every pitch, every plate appearance, odds and ratings.