# UFC API (`lemur/ufc-api`) Actor

The most complete UFC data API  - Access events, fights, fighters, rankings and weight division information in one clean, developer friendly API. Perfect for analytics, dashboards, betting models, fantasy apps, and MMA research.

- **URL**: https://apify.com/lemur/ufc-api.md
- **Developed by:** [Lemur](https://apify.com/lemur) (community)
- **Categories:** Developer tools, Integrations, Other
- **Features:** Limited permissions
- **Stats:** 227 total users, 8 monthly users, 87.5% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $35.00 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

### 🥊 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:

```json
{
  "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:

```json
{
  "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

```js
{
  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

```js
{
  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

```js
{
  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

```js
{
  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

```js
{
  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

```js
{
  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

```js
{
  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

```js
{
  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

```js
{
  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` ✌️

***

# Actor input Schema

## `endpoint` (type: `string`):

The endpoint to fetch data from.

## `params` (type: `object`):

Search params

## Actor input object example

```json
{
  "endpoint": "/rankings?category=pound-for-pound"
}
```

# Actor output Schema

## `overview` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "endpoint": "/rankings?category=pound-for-pound"
};

// Run the Actor and wait for it to finish
const run = await client.actor("lemur/ufc-api").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "endpoint": "/rankings?category=pound-for-pound" }

# Run the Actor and wait for it to finish
run = client.actor("lemur/ufc-api").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "endpoint": "/rankings?category=pound-for-pound"
}' |
apify call lemur/ufc-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,lemur/ufc-api"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/PXKaP7ujdwAL2F443/builds/NynSg2Wldn0Jowcx6/openapi.json