UFC APIstatleaders.ufc.com ↗
Access UFC career, fight, round, and event stat leaderboards plus fighter and fight search/details via the statleaders.ufc.com API. 10 endpoints.
What is the UFC API?
This API exposes 10 endpoints covering UFC statistical leaderboards and fighter/fight records sourced from statleaders.ufc.com and the UFC JSON:API. The get_career_stats_leaders endpoint returns top-3 ranked records across categories like Total Fights, Wins, Finishes, Striking, and Grappling, with optional filters for country, weight class, and fighter status. Separate endpoints cover single-fight records, combined two-fighter stats, round-level records, and event-level achievements.
curl -X GET 'https://api.parse.bot/scraper/b2309d6f-3760-4fc9-9cb6-1bc89af26115/get_career_stats_leaders?country=US&weight_class=Lightweight&fighter_status=0' \ -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 statleaders-ufc-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: UFC Stats & Fights API — bounded, re-runnable; every call capped."""
from parse_apis.ufc_stats_fights_api import UFC, Fighter, Fight, Leaderboard, ResourceNotFound
ufc = UFC()
# Fetch career stat leaderboards (top 3 per category)
career = ufc.leaderboards.career(weight_class="Lightweight")
print(career.categories)
# Fetch event leaderboards (no filters)
event = ufc.leaderboards.event()
print(event.categories)
# Search for a fighter by name
for fighter in ufc.fighters.search(name="Conor McGregor", limit=3):
print(fighter.id, fighter.title, fighter.nickname)
# Drill-down: get full fighter details
detail = ufc.fighters.get(id="f48cc930-1c99-4c3c-bd24-05898cd9664c")
print(detail.title, detail.dob, detail.stats_height)
# Search fights by keyword
fight = ufc.fights.search(title="McGregor", limit=1).first()
if fight:
print(fight.title, fight.fight_final_method, fight.fight_final_round)
# Typed error handling on get-by-id
try:
full_fight = ufc.fights.get(id="4ac965ae-a3b5-4fab-8b56-caabf3564f39")
print(full_fight.title, full_fight.fight_outcome, full_fight.blue_corner_fight_record)
except ResourceNotFound as exc:
print(f"Fight not found: {exc}")
print("exercised: leaderboards.career / leaderboards.event / fighters.search / fighters.get / fights.search / fights.get")
Retrieve career-level stat leaderboards including Total Fights, Wins, Finishes, KO/TKO Wins, Submission Wins, Decision Wins, Win Streak, Title Fight Wins, Striking, Grappling categories. Returns top 3 records per category. Filterable by country, weight class, and fighter status.
| Param | Type | Description |
|---|---|---|
| country | string | Filter by country code (e.g., 'US', 'BR', 'IE'). |
| weight_class | string | Filter by weight class slug as used on statleaders.ufc.com (e.g., 'Flyweight', 'Bantamweight', 'Featherweight', 'Lightweight', 'Welterweight', 'Middleweight', 'Light_Heavyweight', 'Heavyweight'). |
| fighter_status | string | Fighter status filter. Accepted values: '0' (all), '1' (active), '2' (retired). |
{
"type": "object",
"fields": {
"<category_id>": "object containing title (string), subtitle (string), and records (array of objects with rank, fighters, value, extra)"
},
"sample": {
"data": {
"TotalFights": {
"title": "Total Fights",
"records": [
{
"rank": "1",
"extra": "",
"value": "47",
"fighters": [
{
"link": "http://www.ufc.com/athlete/Jim-Miller",
"name": "Jim Miller"
}
]
}
],
"subtitle": ""
}
},
"status": "success"
}
}About the UFC API
Leaderboard Endpoints
Four leaderboard scopes are available: career (get_career_stats_leaders), single-fight (get_fight_stat_leaders), single-round (get_round_stat_leaders), and event-level (get_event_stat_leaders). Each returns a map of category IDs to objects containing a title, subtitle, and a records array. Every record includes rank, fighters, value, and extra fields. Career leaderboards accept country (e.g., 'US', 'BR'), weight_class, and fighter_status ('0' for all, '1' for active, '2' for retired). Fight and round endpoints accept country and weight_class. Event leaderboards take no filter parameters.
Combined Leaderboards
Two additional endpoints — get_fight_combined_stat_leaders and get_round_combined_stat_leaders — return records representing the combined output of both fighters in a single fight or round, rather than one fighter's individual performance. These accept a weight_class filter but not a country filter. Useful for identifying historically high-output fights by total significant strikes, takedowns, or similar two-fighter aggregate metrics.
Fighter and Fight Search
search_fighters accepts a name string and returns an array of UFC JSON:API athlete nodes, each with an id, type, attributes (including title, nickname, dob, and stats), and relationships. The id from those results feeds directly into get_fighter_details to retrieve a full fighter profile. Similarly, search_fights uses partial (CONTAINS) matching on fight titles (formatted as Fighter A vs Fighter B) and returns fight nodes with fight_final_method, fight_final_round, and fight_final_time. The fight id feeds into get_fight_details for complete fight data including finish method, round, and time.
Response Structure Notes
All JSON:API-based endpoints (search_fighters, get_fighter_details, search_fights, get_fight_details) include a jsonapi metadata object and a links object with pagination and self references. Leaderboard endpoints return a flat object keyed by category ID — the category IDs are not fixed strings documented in this spec, so callers should treat them as dynamic keys and rely on the title and subtitle fields within each category object for display labeling.
The UFC API is a managed, monitored endpoint for statleaders.ufc.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when statleaders.ufc.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 statleaders.ufc.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?+
- Build a UFC record book page showing top-3 career leaderboards filtered by weight class and fighter status.
- Identify which country produces the most finishes by filtering
get_career_stats_leaderswith acountrycode. - Find the highest-output fights in UFC history using
get_fight_combined_stat_leadersranked by combined significant strikes. - Look up a fighter's biographical data and career stats by chaining
search_fighterswithget_fighter_details. - Retrieve the finishing method, round, and time of any historical UFC fight using
search_fightsandget_fight_details. - Track single-round performance records broken down by weight class via
get_round_stat_leaders. - Display event-level records such as most KO/TKO wins or shortest event using
get_event_stat_leaders.
| 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 UFC have an official developer API?+
How many records does each leaderboard category return, and can I get beyond the top 3?+
Can I filter career leaderboards by both country and weight class at the same time?+
get_career_stats_leaders accepts country, weight_class, and fighter_status as independent optional parameters, and you can combine them in a single request to narrow results to, for example, active Brazilian middleweights.Does the API return full fight-by-fight history for a fighter?+
get_fighter_details returns fighter attributes including stats and bio, but does not return a structured list of individual past fights for that fighter. The fight endpoints (search_fights, get_fight_details) are separate lookups by fight title keyword or UUID. You can fork the API on Parse and revise to add an endpoint that queries a fighter's fight history by their UUID.What does `fighter_status` actually filter in `get_career_stats_leaders`?+
'1' limits results to currently active fighters, '2' to retired fighters, and '0' (or omitting the parameter) includes both. This filter only applies to the career leaderboard endpoint; fight and round leaderboards do not expose a status filter.