Skip to content
MMA Calendar
UFCalendar Fight API

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.

7,123
UFC bouts with a full fight log
9,145
UFC bouts with control by position
13,955
takedowns logged with round and clock

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.

Endpoints for this job
Method & pathWhat it returns
GET /v1/fights/{id}/timelineThe 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}/positionsTime 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}/disciplineA fighter's confirmed fouls in UFC bouts, committed and drawn: eye pokes, low blows, other fouls, points deducted, every incident.
GET /v1/fighters/{slug}/positionsA 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_committedFoul 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
$ 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 }
}
Python
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 True
JavaScript
const 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.

Pricing & plans →

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