ufcalendar — MMA Fight Data API client for Python

UFC, PFL, OKTAGON, BKFC and RIZIN events, fight stats, results, rankings history and judges' scorecards from one Python client.

The MMA Fight Data API by UFCalendar (the UFCalendar Fight API) is a REST API for MMA data: UFC, PFL, OKTAGON, BKFC and RIZIN events, full fight cards, results within minutes, per-fight and round-by-round statistics, complete fighter careers, the only MMA data API with point-in-time UFC rankings history back to 2013, and the only one serving judges' scorecards — every official, every round: UFC back to 1995, PFL to 2018, OKTAGON to 2025 and RIZIN 2019–2022 and from March 2026 — plus the UFCalendar consensus odds line (current, opening and closing on every plan, line movement on Pro). This package is a thin requests wrapper over it — one method per endpoint, cursor pagination handled for you.

pip install ufcalendar

Get a free key at https://www.ufcalendar.com/account/api?trial=1 — the free plan is 1,000 requests a month, no card, never expires. Paid plans from $19/month for 30,000 requests (Pro $49 for 200,000, Business $149 for 1,000,000), hard caps, no overage.

Quickstart in 3 lines

from ufcalendar import FightAPI
api = FightAPI("ufcalendar_...")                       # free-plan key, no card
print(next(api.events(org="ufc", limit=1))["title"])   # the next UFC card

Quickstart

from ufcalendar import FightAPI

api = FightAPI("ufcalendar_...")            # or export UFCAL_API_KEY=...

# Upcoming UFC schedule, soonest first
for ev in api.events(org="ufc", limit=5):
    print(ev["starts_at"], ev["title"], "PPV" if ev["is_ppv"] else "")

# Full card + results of the newest completed UFC event
latest = next(api.events(org="ufc", status="completed", limit=1))
card = api.event(latest["slug"])
for f in card["card"]:
    r = f.get("result")
    if r:
        print(f["fighter_a"]["name"], "vs", f["fighter_b"]["name"], "->", r["method"], f"R{r['round']} {r['time']}")

# Round-by-round statistics for one bout
rounds = api.fight_rounds(card["card"][0]["id"])

# UFC rankings on any date since February 2013 (rank 0 = champion)
board = api.rankings("ufc", date="2016-11-14")
lw = next(d for d in board["divisions"] if d["division"] == "lightweight")
print(board["snapshot_date"], [e["name"] for e in lw["entries"][:5]])

# A fighter's complete multi-promotion career
history = api.fighter_history("islam-makhachev")

What's covered

Full reference: https://api.ufcalendar.com/docs · OpenAPI 3.1: https://api.ufcalendar.com/openapi.json · Also on npm (TypeScript client), RapidAPI Hub, Postman and the hosted MCP server

Consensus odds

o = api.fight_odds(83379)
print(o["consensus"]["a"]["american"], o["consensus"]["b"]["american"], o["consensus"]["sources"])
print(o["movement"]["delta_points_a"], o["closing"])   # closing = last line before the start (settled bouts)

for point in api.fight_odds_history(83379):               # Pro plans and up
    print(point["recorded_at"], point["a"]["american"], point["b"]["american"])

One anonymised UFCalendar consensus line per corner across the sportsbooks we track; book identities are never exposed. Information only, not betting advice.

Webhooks instead of polling (Pro and up)

ep = api.create_webhook_endpoint("https://example.com/hooks/ufcal", ["fight.result", "card.changed"])
print(ep["secret"])   # shown once; verify X-UFCalendar-Signature with it

odds.moved fires when the consensus line on an upcoming bout moves 5+ implied-probability points on corner a, or the favourite flips, measured against the last line delivered, so a slow drift arrives once. Information only, not betting advice.

Errors and rate limits

Every error raises FightAPIError with .status, .code, .message, .request_id. After each call api.last_rate_limit holds the X-RateLimit-* headers.

Rate-limited reads are waited out for you. When a GET hits the per-minute limit (429 rate_limited, Retry-After of 60 s or less; the free plan allows 10 requests a minute) the client sleeps for Retry-After plus a little jitter and tries again, up to max_retries times (default 3), so a script that walks a few pages does not die mid-run. A 429'd request does not count against your month.

api = FightAPI("ufcalendar_...", max_retries=5)   # wait out more per-minute 429s
api = FightAPI("ufcalendar_...", max_retries=0)   # never wait: raise FightAPIError on the first 429

The monthly quota (429 quota_exceeded), a 429 with a long or missing Retry-After, and every non-GET request (webhook endpoint create / delete / rotate) raise FightAPIError at once.

Notes

• Odds are the UFCalendar consensus line only (no book identities). Information only, not betting advice.
• Fighter images are Wikimedia Commons / Creative Commons files: display the license and artist fields as a credit.
• Not affiliated with UFC, Zuffa, TKO or any promotion. Terms: https://www.ufcalendar.com/developers/terms

MIT licensed.