How do I get a UFC fighter's fouls (eye pokes, low blows, point deductions)?
Request a fighter's discipline record from the MMA Fight Data API: api.fighter_discipline(slug) in Python or fighterDiscipline(slug) in JavaScript. It returns the confirmed fouls the fighter committed and the ones committed against them, split into eye pokes, low blows and other fouls, with points deducted, fouls per 15 minutes and every incident: opponent, round, clock, how long the fight was stopped and whether it ended the bout. fight_timeline(fight_id) gives the same for one bout. Pro and Business plans; UFC bouts since 8 December 2018.
Free plan: 100 requests a month, no card. Paid plans from $19/mo.
Endpoints used
| Method & path | What it returns | Plan |
|---|---|---|
GET /v1/fighters/{idOrSlug}/discipline | A fighter's confirmed fouls in UFC bouts, committed and drawn: eye pokes, low blows, other fouls, points deducted, every incident. | Pro and up |
GET /v1/fights/{id}/timeline | The in-fight log of a UFC bout: every takedown, knockdown, submission attempt and referee stoppage with its round and clock, plus confirmed fouls and who committed them. | Pro and up |
GET /v1/fights/{id}/scorecards | Judges' scorecards for any bout: every official, their score for each round, card totals, decision type and point deductions. | All plans |
The code
curl fetches Leon Edwards's discipline record. The Python block prints his totals and each foul he committed, then walks every referee stoppage of Edwards vs Usman 3 at UFC 286 and shows which were confirmed fouls; the JavaScript block does the same with the TypeScript client.
Every block runs as shown with your API key in the UFCAL_API_KEY environment variable. Python uses pip install ufcalendar and JavaScript or TypeScript uses npm install @ufcalendar/sdk; any HTTP client works too.
curl "https://api.ufcalendar.com/v1/fighters/leon-edwards/discipline" \
-H "Authorization: Bearer $UFCAL_API_KEY"# pip install ufcalendar (0.10.0 or later; Pro plan or higher)
from ufcalendar import FightAPI
api = FightAPI() # reads UFCAL_API_KEY from the environment
# One fighter: confirmed fouls committed and drawn, with every incident
rec = api.fighter_discipline("leon-edwards")
print("committed", rec["committed"]) # {'total': 7, 'eye_pokes': 3, 'low_blows': 3, 'other': 1}
print("drawn", rec["drawn"], "points lost", rec["points_deducted"])
print("per 15 min", rec["fouls_per_15"], "over", rec["tracked_fights"], "tracked fights")
for i in rec["incidents"]:
if i["role"] == "committed":
took_point = f", -{i['points_deducted']} point" if i["points_deducted"] else ""
print(i["date"], "vs", i["opponent"]["name"], i["reason"],
f"R{i['round']}", f"confirmed by {i['basis']}{took_point}")
# One bout: every referee stoppage, and which of them is a confirmed foul
log = api.fight_timeline(59652) # UFC 286, Edwards vs Usman 3
for s in log["stoppages"]:
print(f"R{s['round']} {s['elapsed_sec']}s", s["reason"], "->", s["foul"] or "not a foul")
print(log["fouls"]["a"], log["fouls"]["b"])// npm install @ufcalendar/sdk@^0.10.0 (Pro plan or higher)
import { FightAPI } from "@ufcalendar/sdk";
const api = new FightAPI({ apiKey: process.env.UFCAL_API_KEY });
const rec = await api.fighterDiscipline("leon-edwards");
if (rec) {
console.log(rec.committed, rec.drawn, rec.points_deducted, rec.fouls_per_15);
for (const i of rec.incidents.filter((x) => x.role === "committed")) {
console.log(i.date, i.opponent.name, i.reason, `R${i.round}`, i.basis);
}
}
// The fouls of one bout, each with its round, clock and who committed it
const log = await api.fightTimeline(59652); // UFC 286
console.table(log.incidents);Sample response
The documented payload, filled with real values from the same bout. … marks a value left out.
{
"data": {
"tracked_fights": 10,
"cage_seconds": 11549,
"committed": { "total": 7, "eye_pokes": 3, "low_blows": 3, "other": 1 },
"drawn": { "total": 0, "eye_pokes": 0, "low_blows": 0, "other": 0 },
"points_deducted": 1,
"stoppage_sec": 166,
"fouls_per_15": 0.546,
"incidents": [
{
"fight_id": 59652,
"date": "2023-03-18",
"event": { "slug": "ufc-286-2023-03-18", "title": "UFC 286: Edwards vs Usman 3" },
"opponent": { "slug": "kamaru-usman", "name": "Kamaru Usman" },
"role": "committed",
"reason": "fence",
"basis": "deduction",
"round": 3,
"elapsed_sec": 90,
"stoppage_sec": 48,
"points_deducted": 1,
"ended_bout": false
},
{
"fight_id": 59652,
"date": "2023-03-18",
"event": { … },
"opponent": { … },
"role": "committed",
"reason": "low_blow",
"basis": "log",
"round": 3,
"elapsed_sec": 175,
"stoppage_sec": 23,
"points_deducted": 0,
"ended_bout": false
},
…
]
},
"meta": {
"fighter_id": 401,
"source": "ufc-official",
"coverage_since": "2018-12-08",
"weight_class": "Welterweight",
"note": "UFC bouts only. Counts fouls on the official record: … A recorded foul is not a ruling on intent. fouls_per_15 needs 5 tracked bouts and 30 minutes of cage time."
}
}Notes and pitfalls
- basis says which record confirms a foul: log (the in-fight log labels the stoppage an eye poke or a low blow), deduction (a commission took a point) or result (the bout ended on it). A stoppage the log calls generic with no such record behind it is never counted.
- committed_by names the fighter who committed the foul, not the one who was hit. A foul the record names nobody for is listed on the bout and counts for no fighter.
- Coverage starts on 8 December 2018, when the log began recording why a fight was stopped. Earlier bouts are left out, not counted as foul-free; zero with tracked fights is a real zero. A recorded foul is not a ruling on intent.
- On Free and Hobby plans these endpoints answer 403 tier_required. The foul leaderboards are GET /v1/stats/leaders?org=ufc&metric=fouls_committed (also eye_pokes_committed, low_blows_committed, fouls_drawn and fouls_per_15), Pro and up.
Related pages
More code guides
UFCalendar is an independent publication, not affiliated with UFC/Zuffa/TKO, PFL, OKTAGON MMA, BKFC, RIZIN FF or any promotion. Organization names are used to describe the data. Terms of service · Refund Policy