UFC API

🥊 UFC API

Access comprehensive UFC data with this UFC API Actor. Designed for developers, analysts, and UFC enthusiasts, it provides structured and reliable data across the entire UFC ecosystem.

This API is designed for production use cases removing the need for scraping or stitching together unreliable data sources.

---

🚀 What You Get

Unlike generic sports APIs or fragile scrapers, UFC API is purpose-built for the UFC - delivering structured, reliable and complete fight data you can actually build on.

You get access to:

• 🧑‍🥋 Fighter profiles, records, and career data
• 🥊 Fight histories and outcomes
• 📅 UFC events (past and upcoming)
• 📊 Fighter and fight statistics
• ⚖️ Weight divisions
• 🏆 Official UFC rankings

All responses are returned in clean, predictable JSON and are suitable for long-term use.

---

💡 Use Cases — What You Can Build

With UFC API, you can build:

• 🕸️ UFC & MMA data websites (Tapology, Sherdog etc)
• 🏟️ Event and fight history explorers
• 📊 Ranking trackers and historical comparisons
• 🎮 Fantasy MMA tools
• 🧠 Betting, odds, and prediction models
• 📈 MMA analytics dashboards
• 🤖 Automation workflows and bots

---

🧭 How to Call the API

We support two input methods.

1️⃣ Using Search Parameters

Provide the endpoint with query parameters:

{
  "endpoint": "/weight-divisions?division=all&gender=male"
}

2️⃣ Endpoint + Params Object

You can also pass:

• The resource endpoint as a string
• An optional params object containing arguments.

Example:

{
  "endpoint": "/weight-divisions",
  "params": {
    "division": "all",
    "gender": "male",
    "includeRankings": false
  }
}

---

📦 Available Endpoints

Endpoint	Description
/weight-divisions	UFC weight classes with optional rankings
/rankings	Official UFC rankings by division and gender
/fighters	Basic fighter profile, record, division, and career data
/fighter/details	Full fighter profile
/fighter/previousFights	A fighter's previous fights
/fights	Fight history, results, methods, and outcomes
/fight/details	Full fight information and stats
/events	Past and upcoming UFC events and fight cards
/event/details	Full event details and stats

All endpoints return structured JSON and support flexible filtering via query parameters or params objects.

---

📘 Endpoint Reference

Optional params are marked by "?" next to their type.

If you pass wrong params e.g. typos or non acceptable values, we'll default to "all" or not apply any filters for that param.

1️⃣ /weight-divisions

Returns UFC weight divisions with optional rankings.

Params

Name	Type	Description - Allowed args
division	string	Filter by a specific weight division - all, flyweight, bantamweight, featherweight, lightweight, welterweight, middleweight, light-heavyweight, heavyweight, strawweight, w-flyweight, w-bantamweight
gender	string?	Filter by gender - all, male, female
includeRankings	boolean?	Include official rankings for the division

Notes:

• The "w-" delimited values refer to women specific weight divisions.

Example Response

{
  status: 'success',
  data: [
    { name: 'lightweight', lbs: 155, kgs: 70.307, gender: 'male', totalFighters: 389 }
  ]
}

2️⃣ /rankings

Returns official UFC rankings across all categories, i.e. pound-for-pound and weight-division.

Params

Name	Type	Description - Allowed args
category	string	Ranking category to return - any, pound-for-pound, weight-divisions
gender	string?	Filter by gender - all, male, female
division	string?	Filter by a specific weight division - all, flyweight, bantamweight, featherweight, lightweight, welterweight, middleweight, light-heavyweight, heavyweight, strawweight, w-flyweight, w-bantamweight

Note:

• A rank value of 0 means that this athlete is the champion of the division.

Example Response

{
  status: 'success',
  data: [
    { category: 'pound-for-pound', gender: 'female', list: [
        { athlete: 'Valentina Shevchenko', rank: 1 },
        { athlete: 'Kayla Harrison', rank: 2 }
        ...
      ]
    }
  ]
}

3️⃣ /fighters

Search UFC fighters by name, weight division, status, country, gender, or any combination of filters.

Returns basic fighter information, including the fighter's id, which you can use to fetch their full profile.

Params

Name	Type	Description - Allowed args
search	string?	Search fighters by name or return all fighters - all, fighter-name. For a fighter like Conor McGregor, you can pass "conor", "mcgregor", "conor-mcgregor", even their nickname "notorious".
status	string?	Filter by status - active, retired, inactive
division	string?	Filter by weight division - all, flyweight, bantamweight, featherweight, lightweight, welterweight, middleweight, light-heavyweight, heavyweight, strawweight, w-flyweight, w-bantamweight
gender	string?	Filter by gender - all, male, female
country	string?	Filter by country - string name of the country e.g. "ireland", "russia", "spain", "brazil" etc
cursor	string?	Requests with more than 10 items will be paginated. Use this to fetch the next page of results.

Note:

• If you pass other filters alongside search, search will take precedence and the other fitlers will be ignored.
• If you pass no filters, we'll default to /fighters?search=all and return all fighters, 10 at a time.
• You are charged per result. A query that returns 100 fighters counts as 100 requests.

Example Response

{
  status: 'success',
  cursor: '',
  data: [
    { id: 'fighterId', name: 'Conor McGregor', nickname: 'The Notorious', thumbnail: 'url', image: 'url', gender: 'male', status: 'active', division: 'lightweight', city: 'dublin', country: 'ireland', wins: 25, losses: 6, draws: 0, divisionRanking?: 'unranked', pfpRanking?: null }
  ]
}

4️⃣ /fighter/details

Get full fighter profile and stats.

Params

Name	Type	Description - Allowed args
id	string	Represents the id of the fighter. You can get this from searching using the /fighters endpoint.
includeStats	boolean?	Whether to include fighter stats.

Note:

• Returns all details from the /fighters endpoint and more - age, reach, legReach, fightingStyle, city, country, gym, octagonDebut, totalFights etc
• The returned stats include - significantStrikes, takedowns, submissions, knockdownAvg, averageFightTime, winsByKnockout, winsBySubmission, winsByDecision and more.

Example Response

{
  status: 'success',
  data: { ..., stats: { ... } }
}

5️⃣ /fighter/previousFights

Returns a fighter's previous fights.

Params

Name	Type	Description - Allowed args
id	string	Represents the id of the fighter. You can get this from searching using the /fighters endpoint.
count	number?	How many fights to return.

Note:

• You can get the total number of fights from the previous endpoint as well.

Example Response

{
  status: 'success',
  data: [
    {
      id: 'ckq9f4x8c0001l2z6h3a9m7v2',
      matchup: "merab vs yan 2",
      isTitleFight: true,
      isInterimTitleFight: false,
      event: "ufc 323",
      eventSlug: "ufc-323",
      winner: "Petr Yan",
      winMethod: "Decision",
      round: 5,
      endTime: "25:00",
      awards: ["Fight of the night"],
      redCorner: {
        id: '9f4x8c0001l2z6h3acdqertpko',
        name: "Merab Dvalishvili",
        nickname: "The Machine",
        thumbnail: "image-url",
        wins: 21,
        losses: 5,
        draws: 0,
        weightDivision: "bantamweight",
        pfpRanking: 7,
        divisionRanking: 1,
        country: "georgia",
      },
      blueCorner: { name: "Petr Yan", ... }
      date: new Date('2025-12-07'),
    },
    ...
  ]
}

6️⃣ /fights

Search for fights by fighter or matchup names.

In order to match a fight e.g. "Merab vs Yan" you could pass "merab yan", "merab vs yan", "dvalishvili petr" etc.

Params

Name	Type	Description - Allowed args
search	string	Search term - e.g. makhackev vs jack, makhachev, jack etc.

Note:

• Returns a list of fights. If we have an exact match, we'll return a list with one item, otherwise we'll return a max of 5 fights.
• Try and use the matchup format "fighterA fighterB" to get exact matches as you'll be billed per returned result.

Example Response

{
  status: 'success',
  data: [
    {
      id: 'ckq9f4x8c0001l2z6h3a9m7v2',
      isTitleFight: true,
      isInterimTitleFight: true,
      matchup: "merab vs yan 2",
      event: "ufc 323",
      eventSlug: "ufc-323",
      winner: "Petr Yan",
      winMethod: "Decision",
      round: 5,
      endTime: "25:00",
      date: new Date('2025-12-07'),
    },
    ...
  ]
}

7️⃣ /fight/details

Get fight details and stats.

Params

Name	Type	Description - Allowed args
fightId	string	Id of the fight. You can get this from searching on the /fights endpoint.
includeStats	boolean?	Whether to include fight stats.

Note:

• Returns fight details.
• For each fighter we'll return - id, name, nickname, thumbnail, image, wins, losses, draws, pfpRanking, divisionRanking, age, height, reach, legReach, fightingStyle, city, country.

Example Response

{
  status: 'success',
  data: {
    id: '',
    isTitleFight: true,
    isInterimTitle: false,
    matchup: 'Makhachev vs Jack',
    division: 'welterweight',
    event: {
      title: 'ufc 322',
      slug: 'ufc-322',
      venue: 'Madison Square Garden',
      location: 'New York, NY',
      country: 'United States'
    },
    card: 'main',
    winner: 'Makhachev',
    winMethod: 'Unanimous decision',
    round: 5,
    endTime: '25:00',
    awards: ['Fight of the night'],
    redCorner: {id: '', name: 'Islam Makhachev', nickname: '', thumbnail: 'thumbnail-url', image: 'image-url', wins: 28, losses: 1 ...},
    blueCorner: { ... }
    stats: { totalStrikes: {}, significantStrikes: {}, strikePositions: {}, takedowns: {}, submissionAttempts: {}, reversals: {}, knockdowns: {} controlTime: {} }
  }
}

8️⃣ /events

Search UFC events.

Params

Name	Type	Description - Allowed args
search	string?	Event search term - all, past, upcoming, "event-slug" e.g. for "UFC 323" pass ufc-323 as the search term.
limit	number?	The default number of results to return. Only applies if you set search to all, past or upcoming. This param accepts a max value of 35. We return 10 results by default.
cursor	string?	Requests with more than 10 items will be paginated. Use this to fetch next page of results.

Note:

• To search for a specific event, you have to know the event slug. For example, the slug for "UFC 323" is ufc-323. This is easy enough for numbered UFC events but for Fight Nights, you'd have to get the slug by searching for a fight you know was on the card. Use the /fights endpoint for this.
• A value of all for the search term will return all events ordered in descending order - next upcoming first.

Example Response

{
  status: 'success',
  data: [
    {
      id: 'm8c0001l2z6h3a9mpju8v3',
      title: 'ufc 322',
      slug: 'ufc-322',
      poster: 'poster-url',
      venue: 'Madison Square Garden',
      location: 'New York, NY',
      country: 'United States',
      redCorner: { name: 'Islam Makhachev', image: 'image-url' },
      blueCorner: { name: 'Jack Della Madallena', image: 'image-url' },
      timestamps: { mainCard: 1763262000, prelims: 1763254800, earlyPrelims: 1763247600 },
      date: new Date('2025-11-16'),
    }
  ]
}

9️⃣ /event/details

Get event details.

Params

Name	Type	Description - Allowed args
eventId	string	Id of the event. You can get this from searching on the /events endpoint or making an educated guess, for example, a numbered UFC event e.g. "UFC 323" would have an id of ufc-323.
card	string?	Fight cards - main, prelims, early-prelims, all. We return only the main card fights by default. To return all cards pass all.
includeStats	boolean?	Whether to return stats for each fight.

Example Response

{
  status: 'success',
  data: [
    {
      title: 'ufc 322',
      slug: 'ufc-322',
      poster: 'poster-url',
      venue: 'Madison Square Garden',
      location: 'New York, NY',
      country: 'United States',
      timestamps: { mainCard: 1763262000, prelims: 1763254800, earlyPrelims: 1763247600 },
      fights: [
        {
          id: '',
          isTitleFight: true,
          isInterimTitleFight: false,
          matchup: 'Makhachev vs Jack Della',
          winner: 'Islam Makhachev',
          winMethod: 'Unanimous decision',
          round: 5,
          endTime: '25:00',
          awards: ['Fight of the Night'],
          redCorner: { name: 'Islam Makhachev', nickname: '', thumbnail: 'url', odds: -250, ...  },
          blueCorner: { name: 'Jack Della Madallena', ... },
          stats: { ... }
        },
        { ... }
      ],
      date: new Date('2025-11-16'),
    }
  ]
}

---

📖 Percentage values

When you fetch fighter statistics, please note that the following values are all percentages:

• significantStrikes.strikingAccuracy
• significantStrikes.defense
• takedowns.accuracy

---

⚠️ Terms of Service

• You MAY ✅ use this API to build applications, products, or services (commercial or otherwise), that leverage its functionality. Access is granted soley for this purpose.
• You may NOT ❌ use this API to create a competing version, copy, replica or mirror, whether for private or commercial use.

---

📩 Contact

For any inquiries, requests for more data or consultation, send an email to lemurxn@gmail.com ✌️

---