UFC fight log and control time in the MMA Fight Data API: every action, every position, every foul
Looking for a fighter’s stats, not an API? → Record Book
Totals tell you who won the numbers. The fight log tells you what happened: every takedown, knockdown, submission attempt, reversal and referee stoppage of a UFC bout with its round and clock, from June 2013. Position stats split each fighter's control time into back, mount, side control, half guard and guard, per bout and per round, on 9,145 UFC bouts. Foul records count every confirmed eye poke, low blow and point deduction. Pro and Business plans.
Free plan: 100 requests/month, no card, never expires. Paid plans from $19/mo for 30,000 requests, cancel anytime.
Control time, finally split by position
GET /v1/fights/{id}/positions returns time at distance, in the clinch and on the ground, each fighter's control split into back, mount, side control, half guard and guard, and strikes by position and target, for the whole bout and for every round. GET /v1/fighters/{slug}/positions adds it up over a career, with control for and against in each position.
The fight as a log, not a total
GET /v1/fights/{id}/timeline lists every logged action in order with its round, elapsed seconds and wall-clock time, pairs every referee stoppage with its reason (eye poke, low blow, doctor, other) and real length, and names who committed each confirmed foul. GET /v1/fighters/{slug}/discipline is the career foul record, committed and drawn, with every incident.
Endpoints for this job
Method and path, linked to the reference. The same key covers every endpoint in the API.
| Method & path | What it returns |
|---|---|
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. |
GET /v1/fights/{id}/positions | Time at distance, in the clinch and on the ground; control time split into back, mount, side control, half guard and guard; strikes by position and target. Per bout and per round. |
GET /v1/fighters/{slug}/discipline | A fighter's confirmed fouls in UFC bouts, committed and drawn: eye pokes, low blows, other fouls, points deducted, every incident. |
GET /v1/fighters/{slug}/positions | A fighter's career position profile: share of cage time at each range and control for and against in every position. |
GET /v1/stats/leaders?org=ufc&metric=fouls_committed | Foul leaderboards: fouls committed and drawn, per 15 minutes, per fight, per card and per division (Pro and up). |
Quickstart in curl, Python and JavaScript
Complete requests against the live API. Any HTTP client works, or pip install ufcalendar for a typed Python client (source on GitHub); every response is plain JSON in a {"data": ..., "meta": ...} envelope.
$ curl "https://api.ufcalendar.com/v1/fights/82861/positions" \
-H "Authorization: Bearer $UFCAL_KEY"
{
"data": {
"totals": [
{
"fighter_id": 397,
"corner": "a",
"time": {
"standing_sec": 1082, "distance_sec": 668,
"clinch_sec": 414, "ground_sec": 418, "neutral_sec": 716
},
"control": {
"total_sec": 750, "clinch_sec": 344, "ground_sec": 406,
"back_sec": 160, "mount_sec": 0, "side_sec": 65,
"half_guard_sec": 22, "guard_sec": 0, "misc_ground_sec": 159
},
"sig_strikes": {
"distance": { "head": { "landed": 5, "attempted": 26 }, … },
"clinch": { "head": { "landed": 3, "attempted": 4 }, … },
"ground": { "head": { "landed": 1, "attempted": 1 }, … }
},
"total_strikes": { "ground": { "landed": 42, "attempted": 55 }, … }
}
// … corner "b": control.total_sec 34
],
"rounds": [ { "round": 1, "fighters": [ … ] } /* … 5 rounds */ ]
},
"meta": { "fight_id": 82861, "source": "ufc-official", "official": true }
}from ufcalendar import FightAPI
api = FightAPI() # UFCAL_KEY in the environment (Pro plan or higher)
# Where a fighter's career happens, and who holds control in each position
profile = api.fighter_positions("islam-makhachev")
print(profile["time"]["ground_share"]) # 0.458
for row in profile["control"]["by_position"]:
print(row["position"], row["for_sec"], row["against_sec"])
# back 1092 0 · mount 115 3 · side 246 26 · half_guard 1513 38 · …
# Every referee stoppage of a bout, with its reason and who committed it
log = api.fight_timeline(60458) # UFC 321, Aspinall vs Gane
for s in log["stoppages"]:
print(s["round"], s["elapsed_sec"], s["reason"], s["is_foul"], s["ended_bout"])
# 1 275 eye_poke True Trueconst h = { Authorization: `Bearer ${process.env.UFCAL_KEY}` };
// A fighter's confirmed fouls, committed and drawn, with every incident
const { data } = await fetch(
"https://api.ufcalendar.com/v1/fighters/ciryl-gane/discipline",
{ headers: h },
).then((r) => r.json());
console.log(data.committed); // { total: 7, eye_pokes: 3, low_blows: 4, other: 0 }
console.log(data.fouls_per_15); // 0.507
for (const i of data.incidents.filter((x) => x.role === "committed")) {
console.log(i.date, i.opponent.name, i.reason, `R${i.round}`, i.ended_bout ? "ended the bout" : "");
}Pricing
Free plan: 100 requests/month, no card, never expires. Paid plans from $19/mo for 30,000 requests, cancel anytime.
Who it's for
Built for indie developers, side projects and small teams. Whether you're building a fantasy app, a stats site, a Discord bot or an analytics project, our plans are priced for you. We don't sell enterprise contracts, and we don't plan to.
Questions
- Is there a UFC play-by-play or fight timeline API?
- Yes. GET /v1/fights/{id}/timeline returns the official in-fight log of a settled UFC bout: walkouts, round starts and ends, takedowns and attempts, knockdowns, submission attempts, reversals and every referee stoppage, each with its round, seconds into the round and timestamp. 7,123 UFC bouts are covered, from June 2013, Contender Series included.
- Can I get UFC control time by position (back, mount, side control)?
- Yes. GET /v1/fights/{id}/positions splits each fighter's control time into clinch and ground, and the ground into back, mount, side control, half guard, guard and other ground control, for the whole bout and for each round. It also returns time at distance, in the clinch and on the ground, and strikes by position and target. Tracked reliably from 2007; a bout the tracking missed returns null, never zero.
- How are fouls counted?
- Only confirmed fouls count: an eye poke or low blow labelled in the official log, a commission point deduction, or a result the bout ended on (a disqualification or a fight that could not continue). A stoppage the log does not label is never counted as a foul on its own. Stoppage reasons exist from December 2018. A recorded foul is not a ruling on intent.
- Which plans include the fight log and position stats?
- Pro and Business. On Free and Hobby these endpoints answer 403 tier_required. The same data is on the MCP server as get_fight_timeline, get_fight_positions, get_fighter_discipline and get_fighter_positions, and in the Python and TypeScript clients from version 0.10.0.
- Which promotions are covered?
- UFC bouts, including Dana White's Contender Series. The log is published only for settled bouts; live fight-night data is not part of these endpoints.
MMA Fight Data API guides by use case
One page per job: schedules, results, per-round statistics, rankings history, judges' scorecards and consensus odds, each with its own endpoints, sample responses and code.
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