UFC API documentation
11 MMA data endpoints over REST and MCP. One key, credits per call.
Coming from UFC Stats or ESPN's UFC feed? See how they compare.
Your first call
Sign up for a free key (500 credits every month, no card), swap it in for YOUR_API_KEY, and send this. search_fighters costs 1 credit.
Request
curl -X POST https://mcp.fighterapi.com/v1/search_fighters \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
"query": "topuria"
}'Response
{
"fighters": [
{
"fighter_id": "4350812",
"name": "Ilia Topuria",
"nickname": "El Matador",
"weight_class": "Lightweight",
"country": "Georgia",
"date_of_birth": "1997-01-21",
"pro_record": "17-1-0",
"bouts": 10,
"last_bout": "2026-06-15T00:00:00.000Z",
"ufc_bouts": 10
},
...First 14 lines. Full response and every field
REST / cURL
POST to /v1/{tool_name} with your params as JSON body. No MCP client needed:
curl -X POST https://mcp.fighterapi.com/v1/list_events \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY"With parameters:
curl -X POST https://mcp.fighterapi.com/v1/search_fighters \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{"query":"topuria"}'Save the raw JSON
Keep your key in an environment variable so it never sits in a script or a chat, and write each response to a file:
export FIGHTERAPI_API_KEY="your key here"
curl -s -X POST https://mcp.fighterapi.com/v1/search_fighters \
-H "Content-Type: application/json" \
-H "x-api-key: $FIGHTERAPI_API_KEY" \
-d '{"query":"topuria"}' \
-o search_fighters.jsonThe file holds exactly what the API returned. Tools that page their results return a next_offset; send it back as offset for the next page.
ChatGPT and Claude
Both connect to the MCP server with a sign-in instead of a key: you sign in to FighterAPI once and press Allow. Step-by-step for ChatGPT and Claude.
Python
The official client is on PyPI. It has no required dependencies. Set FIGHTERAPI_API_KEY to your key and it is picked up automatically:
pip install fighterapiThen call any endpoint as a method (the example uses pandas, pip install "fighterapi[pandas]"):
from fighterapi import Client
client = Client()
events = client.list_events(status="final", limit=3)["events"]
for e in events:
print(e["event_id"], e["event_date"], e["name"])Claude Desktop
Add to your claude_desktop_config.json:
{
"mcpServers": {
"fighterapi": {
"url": "https://mcp.fighterapi.com/mcp?key=YOUR_API_KEY"
}
}
}Claude Code
One command:
claude mcp add fighterapi https://mcp.fighterapi.com/mcp?key=YOUR_API_KEY --transport streamable-httpFind the right call
All 11 questionsWhat timestamps mean, whether lines are pre-game, and what you can do with the data: data timing and rights.
Guides
All guidesWorking Python, JavaScript and cURL for common questions, each run against the live API.
- How do I get UFC fight stats per round in Python?get_fight
- How do I get a UFC fighter's record and career striking rates in Python?get_fighter
- How do I get UFC fighter Elo ratings by weight class?get_ratings
- Who lands the most significant strikes per 15 minutes in the UFC?get_leaders
- How do I compare UFC closing odds with fight results in Python?get_odds
- How do I get UFC line movement for a fight in Python?get_line_movement
- How do I get PFL odds and results for a card in Python?get_odds
- How do I get the upcoming UFC fight schedule in Python?get_schedule
- How do I get UFC event results and the fight card in Python?get_event
- How do I get a UFC fighter's fight history in Python?get_fighter_fights
Endpoints
11 endpoints by category. Each page has parameters, requests in three formats, a full example response and every response field.
Static reference1 credit/call
Basic lookup2 credits/call
Stats + aggregation5 credits/call
- get_fight5 creditsOne fight: result, full stat sheets, round-by-round lines, ratings and odds
- get_fighter5 creditsProfile, UFC record by method, career rates, rating and recent fights
- get_fighter_fights5 creditsA fighter's full UFC history with stats, ratings and closing lines
- get_leaders5 creditsCareer leaderboards from every fight's stat sheet
- get_odds5 creditsOpening, closing and current moneylines by sportsbook for a fight (5) or a card (10)
Time-series10 credits/call
Reference
Authentication
Every request requires an API key. Pass it via header or query parameter:
x-api-key: YOUR_API_KEY
# or
Authorization: Bearer YOUR_API_KEY
# or (MCP only)
?key=YOUR_API_KEYVerify your email, then create an API key from the dashboard. Free accounts get 500 credits every month.
Base URL
https://mcp.fighterapi.comREST API: POST /v1/{tool} with JSON body. Works with cURL, Python, any HTTP client.
MCP: POST /mcp via Streamable HTTP. Works with Claude Desktop, Claude Code, Cursor, and any MCP client.
Rate limits
| Credit balance | Rate limit |
|---|---|
| 100 credits or more | 60 req/min |
| Under 100 credits | 10 req/min |
The limit is the same on every plan. It is burst protection, not the spend boundary; credits are that, and they are enforced per request. Running low slows you down so you notice before the balance reaches zero.
Error handling
| Code | Meaning | What to do |
|---|---|---|
| 400 | Invalid parameters | Check required fields and value types |
| 401 | Invalid or missing API key | Check your x-api-key header |
| 402 | Insufficient credits | Top up your wallet or upgrade your plan |
| 429 | Rate limit exceeded | Wait and retry (see limits above) |
| 500 | Server error | Retry with idempotency key. Credits auto-refund on server errors. |
Pass x-idempotency-key or x-request-id headers to make retries duplicate-safe.
Data coverage
Professional Fighters League (PFL)
FighterAPI also serves the PFL. Pass "league": "pfl" to any tool that lists it, or connect to https://mcp.fighterapi.com/mcp/pfl. PFL API coverage.
Bellator MMA (Bellator)
FighterAPI also serves the Bellator. Pass "league": "bellator" to any tool that lists it, or connect to https://mcp.fighterapi.com/mcp/bellator. Bellator API coverage.
| Data | Status | Coverage | Volume |
|---|---|---|---|
Cards and results Events, fights in card order, winner, method, round, time, judges' scores and referee. | Available | 2000 to current | Every UFC card |
Fight stat sheets Strikes by target and position, takedowns, control time, guard passes, reversals, submission attempts. A few dozen fights, mostly from 2016 to 2019 and Ultimate Fighter semifinals, have no stat sheet. | Available | 2000 to current | Per fighter per fight |
Round-by-round Each round's strikes, takedowns, control and submission attempts. A fight whose rounds do not add up to its totals is flagged. | Available | 2000 to current | Per fighter per round |
Fighters Date of birth, height, reach, stance, gym, record by method and career rates. | Available | Everyone who fought in the UFC since 2000 | Profiles and careers |
Odds Opening, closing and current moneylines and the total-rounds line, by sportsbook. UFC from June 2020; PFL from April 2023 and Bellator from January 2022 to 2024, with fewer books; moneylines and total rounds, no props. | Partial | 2020 to current | A median of 5 to 7 books per UFC fight since June 2020 |
Ratings Our Elo from UFC results, before and after every fight. | Available | 2000 to current | Every fighter, every fight |
Coverage describes the datasets FighterAPI supports. Freshness and operational health are tracked separately.
Odds snapshot definitions
opening: The first moneyline a sportsbook posted for the fight.
closing: The sportsbook's last moneyline before the fight.
Odds coverage currently documents for UFC since June 2020, Pinnacle, FanDuel, DraftKings, BetMGM and ESPN BET among the books in the sportsbook odds archive; the daily feed adds about nine books for January to June 2024 (including Bet365, DraftKings, Caesars and ESPN BET), then usually one. No opening or closing lines before June 2020, and the daily feed is one book per fight since mid-2024; the other books come from the sportsbook odds archive. Opening and closing moneylines start with the UFC cards of June 2020 (sportsbook odds archive): a median of 5 books per fight in 2020 and 6 to 7 since (including Pinnacle, FanDuel, DraftKings, BetMGM and ESPN BET). The daily feed adds lines from the November 2023 cards, usually one book per fight. There are no opening or closing lines before June 2020. Daily snapshots for each fight with a posted line from October 2026.
Response format
REST API
All successful REST responses wrap the result in a data key:
{ "data": { "events": [...], "count": 50 } }Error responses return:
{ "error": "Insufficient credits", "message": "This tool costs 5 credits, you have 2" }MCP Protocol
MCP responses follow the standard MCP tool result format. The data is returned directly (no data wrapper). Both access methods return identical data, just different envelopes.
Conventions
Seasons: 4-digit year (cards are grouped by calendar year). Example: 2025.
Fight IDs: a fight's id, e.g. 401630119 (a competition id; list a card's fights with get_event). Get them from get_event, get_schedule or get_fighter_fights.
Fighter IDs: Get them from search_fighters, by name or nickname.
Pagination: Endpoints use a limit parameter. No cursor or offset. Narrow your filters to get different slices of data.
Credits: Deducted before the request executes. Automatically refunded on server errors. Monthly credits are used first, then wallet balance.