How do I get UFC control time by position (back, mount, side control)?
Request a bout's position stats from the MMA Fight Data API: api.fight_positions(fight_id) in Python or fightPositions(fightId) in JavaScript. Each fighter's control comes split 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 every round, with time at distance, in the clinch and on the ground. fighter_positions(slug) adds it up over a career. Pro and Business plans; UFC bouts, tracked reliably from 2007.
Free plan: 100 requests a month, no card. Paid plans from $19/mo.
Endpoints used
| Method & path | What it returns | Plan |
|---|---|---|
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. | Pro and up |
GET /v1/fighters/{idOrSlug}/positions | A fighter's career position profile: share of cage time at each range and control for and against in every position. | 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}/stats | Per-fight totals for both corners: strikes by target and position, takedowns, control time · plus UFCalendar fantasy points per corner and data-quality flags. | All plans |
The code
curl fetches the position stats of Islam Makhachev vs Ian Machado Garry at UFC 330. The Python block prints each fighter's control split by position, then round by round, then Makhachev's career control for and against in each position; 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/fights/82861/positions" \
-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
POSITIONS = ("back", "mount", "side", "half_guard", "guard", "misc_ground")
# One bout: each fighter's control, split by position
bout = api.fight_positions(82861) # UFC 330, Makhachev vs Machado Garry
for line in bout["totals"]:
c = line["control"]
split = ", ".join(f"{p} {c[p + '_sec']}s" for p in POSITIONS if c[p + "_sec"])
print(line["corner"], f"{c['total_sec']}s in control:", split or "none on the ground")
# Round by round, for a chart
for r in bout["rounds"]:
a = r["fighters"][0]["control"]
print(f"R{r['round']}", a["total_sec"], "s, back", a["back_sec"], "s")
# A whole career: control for and against in each position
career = api.fighter_positions("islam-makhachev")
for row in career["control"]["by_position"]:
print(f"{row['position']:<11} for {row['for_sec']:>5}s against {row['against_sec']:>4}s")// 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 bout = await api.fightPositions(82861); // UFC 330
for (const line of bout.totals) {
const c = line.control;
console.log(line.corner, {
total: c.total_sec, back: c.back_sec, mount: c.mount_sec,
side: c.side_sec, halfGuard: c.half_guard_sec, guard: c.guard_sec,
});
}
// Where a fighter's fights happen: share of cage time at each range
const career = await api.fighterPositions("islam-makhachev");
console.log(career?.time); // distance_share, clinch_share, ground_shareSample response
The documented payload, filled with real values from the same bout. … marks a value left out.
{
"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": { … },
"total_strikes": { … }
},
{
"fighter_id": 387,
"corner": "b",
"time": { … },
"control": {
"total_sec": 34,
"clinch_sec": 22,
"ground_sec": 12,
"back_sec": 0,
"mount_sec": 0,
"side_sec": 0,
"half_guard_sec": 0,
"guard_sec": 0,
"misc_ground_sec": 12
},
…
}
],
"rounds": [
{
"round": 1,
"fighters": [
{ "fighter_id": 397, "corner": "a", "control": { "total_sec": 218, "clinch_sec": 136, "ground_sec": 82, … }, … },
…
]
},
…
]
},
"meta": {
"fight_id": 82861,
"source": "ufc-official",
"official": true,
"note": "null means not tracked for this bout; 0 is a real zero. Time fields are whole seconds."
}
}Notes and pitfalls
- control.total_sec is clinch_sec plus ground_sec, and ground_sec is back, mount, side, half guard, guard and misc_ground added up. misc_ground_sec is ground control the tracking does not assign to one of the five named positions.
- The time block (standing, distance, clinch, ground, neutral) is shared by both fighters; control is each fighter's own. standing_sec is distance_sec plus clinch_sec.
- null means the position was not tracked for that bout; 0 is a real zero. Older bouts can carry totals without the position split, so test for null before you chart.
- On Free and Hobby plans these endpoints answer 403 tier_required. The bout's ordinary totals, including a single control-time figure per fighter, are on GET /v1/fights/{id}/stats on every plan.
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