MMA API

Welcome to the BALLDONTLIE MMA API, the premier source for MMA (Mixed Martial Arts) data. This API covers UFC, Bellator, PFL, ONE Championship, and other major MMA organizations with comprehensive fighter, fight, event, and statistics data. An API key is required. You can obtain an API key by creating a free account on our website. Read the authentication section to learn how to use the API key.

Download language specific libraries:

Take a look at our other APIs.

Join us on discord.

AI-Powered Integration

Using the OpenAPI Specification with AI

Our complete OpenAPI specification allows AI assistants to automatically understand and interact with our API. Simply share the spec URL with your AI assistant and describe what you want to build—the AI will handle the technical implementation.

Getting Started with AI:

Copy this URL: https://www.balldontlie.io/openapi.yml
Share it with your preferred AI assistant (ChatGPT, Claude, Gemini, etc.)
Tell the AI what you want to build (e.g., "Create a dashboard showing upcoming UFC fights")
The AI will read the OpenAPI spec and write the code for you

Example prompts to try:

"Using the OpenAPI spec at https://www.balldontlie.io/openapi.yml, show me how to get Conor McGregor's fight history"
"Read the BALLDONTLIE OpenAPI spec and create a Python script that fetches upcoming MMA events"
"Help me understand the available MMA endpoints from this OpenAPI spec: https://www.balldontlie.io/openapi.yml"

This makes it incredibly easy for non-technical users, analysts, and researchers to leverage our MMA data without needing to learn programming from scratch.

Google Sheets Integration

Our Google Sheets integration lets you access all the same data available through our API using simple spreadsheet formulas. Perfect for fantasy sports tracking, betting analysis, and sports research.

Quick Start:

Get your API key from app.balldontlie.io
Copy our Google Sheets script
Paste it into your Google Sheet (Extensions > Apps Script)
Start using functions in your cells

Example functions:

=BDL_MMA_FIGHTERS("McGregor") - Search for fighters
=BDL_MMA_EVENTS() - Get upcoming events
=BDL_MMA_RANKINGS() - Get rankings by weight class
=BDL_MMA_ODDS() - Get betting odds

For full setup instructions and the complete list of 150+ functions, see our Google Sheets Integration Guide.

Account Tiers

There are three different account tiers which provide you access to different types of data. Visit our website to create an account for free.

Paid tiers do not apply across sports. The tier you purchase for MMA will not automatically be applied to other sports. You can purchase the ALL-ACCESS ($299.99/mo) tier to get access to every endpoint for every sport.

Read the table below to see the breakdown.

Endpoint	Free	ALL-STAR	GOAT
Leagues	Yes	Yes	Yes
Events	Yes	Yes	Yes
Fighters	Yes	Yes	Yes
Fights	No	Yes	Yes
Rankings	No	Yes	Yes
Fight Statistics	No	No	Yes
Betting Odds	No	No	Yes

The feature breakdown per tier is shown in the table below.

Tier	Requests / Min	$USD / mo.
GOAT	600	39.99
ALL-STAR	60	9.99
Free	5	0

Authentication

curl "api_endpoint_here" -H "Authorization: YOUR_API_KEY"

const response = await fetch('https://api.balldontlie.io/mma/v1/fighters', {
  headers: {
    'Authorization': 'YOUR_API_KEY'
  }
});
const data = await response.json();
console.log(data);

import requests

response = requests.get(
    'https://api.balldontlie.io/mma/v1/fighters',
    headers={'Authorization': 'YOUR_API_KEY'}
)

if response.status_code == 200:
    data = response.json()
    print(data)
else:
    print(f'Error: {response.status_code}')

BALLDONTLIE uses API keys to allow access to the API. You can obtain an API key by creating a free account at our website

We expect the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: YOUR_API_KEY

You must replace YOUR_API_KEY with your personal API key.

Pagination

This API uses cursor based pagination rather than limit/offset. Endpoints that support pagination will send back responses with a meta key that looks like what is displayed on the right.

{
  "meta": {
    "next_cursor": 90,
    "per_page": 25
  }
}

You can use per_page to specify the maximum number of results. It defaults to 25 and doesn't allow values larger than 100.

You can use next_cursor to get the next page of results. Specify it in the request parameters like this: ?cursor=NEXT_CURSOR.

Errors

The API uses the following error codes:

Error Code	Meaning
401	Unauthorized - You either need an API key or your account tier does not have access to the endpoint.
400	Bad Request -- The request is invalid. The request parameters are probably incorrect.
404	Not Found -- The specified resource could not be found.
406	Not Acceptable -- You requested a format that isn't json.
429	Too Many Requests -- You're rate limited.
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Leagues

Get All Leagues

curl "https://api.balldontlie.io/mma/v1/leagues" \
  -H "Authorization: YOUR_API_KEY"

const response = await fetch('https://api.balldontlie.io/mma/v1/leagues', {
  headers: {
    'Authorization': 'YOUR_API_KEY'
  }
});
const data = await response.json();
console.log(data);

import requests

response = requests.get(
    'https://api.balldontlie.io/mma/v1/leagues',
    headers={'Authorization': 'YOUR_API_KEY'}
)

if response.status_code == 200:
    leagues = response.json()['data']
    for league in leagues:
        print(f"{league['name']} ({league['abbreviation']})")

{
  "data": [
    {
      "id": 3,
      "name": "Bellator MMA",
      "abbreviation": "Bellator"
    },
    {
      "id": 7,
      "name": "Cage Warriors",
      "abbreviation": "CW"
    },
    {
      "id": 10,
      "name": "Dana White's Contender Series",
      "abbreviation": "DWCS"
    },
    {
      "id": 6,
      "name": "Invicta Fighting Championships",
      "abbreviation": "Invicta"
    },
    {
      "id": 9,
      "name": "Konfrontacja Sztuk Walki",
      "abbreviation": "KSW"
    },
    {
      "id": 5,
      "name": "Legacy Fighting Alliance",
      "abbreviation": "LFA"
    },
    {
      "id": 4,
      "name": "ONE Championship",
      "abbreviation": "ONE"
    },
    {
      "id": 2,
      "name": "PFL",
      "abbreviation": "PFL"
    },
    {
      "id": 8,
      "name": "Rizin Fighting Federation",
      "abbreviation": "RIZIN"
    },
    {
      "id": 1,
      "name": "UFC",
      "abbreviation": "UFC"
    }
  ]
}

This endpoint retrieves all MMA leagues/organizations.

HTTP Request

GET https://api.balldontlie.io/mma/v1/leagues

Query Parameters

This endpoint does not accept query parameters.

Get Specific League

curl "https://api.balldontlie.io/mma/v1/leagues/1" \
  -H "Authorization: YOUR_API_KEY"

const response = await fetch('https://api.balldontlie.io/mma/v1/leagues/1', {
  headers: {
    'Authorization': 'YOUR_API_KEY'
  }
});
const data = await response.json();
console.log(data);

import requests

league_id = 1
response = requests.get(
    f'https://api.balldontlie.io/mma/v1/leagues/{league_id}',
    headers={'Authorization': 'YOUR_API_KEY'}
)

if response.status_code == 200:
    league = response.json()['data']
    print(f"{league['name']} - {league['abbreviation']}")

{
  "data": {
    "id": 1,
    "name": "UFC",
    "abbreviation": "UFC"
  }
}

This endpoint retrieves a specific league.

HTTP Request

GET https://api.balldontlie.io/mma/v1/leagues/{id}

URL Parameters

Parameter	Description
id	The ID of the league

Events

Get All Events

curl "https://api.balldontlie.io/mma/v1/events?year=2025" \
  -H "Authorization: YOUR_API_KEY"

const response = await fetch('https://api.balldontlie.io/mma/v1/events?year=2025', {
  headers: {
    'Authorization': 'YOUR_API_KEY'
  }
});
const data = await response.json();
console.log(data);

import requests

response = requests.get(
    'https://api.balldontlie.io/mma/v1/events',
    headers={'Authorization': 'YOUR_API_KEY'},
    params={'year': 2025}
)

if response.status_code == 200:
    events = response.json()['data']
    for event in events:
        print(f"{event['name']} - {event['date']}")

{
  "data": [
    {
      "id": 38975,
      "name": "UFC Fight Night: Royval vs. Kape",
      "short_name": "UFC Fight Night: Royval vs. Kape",
      "date": "2025-12-13T19:00:00.000Z",
      "venue_name": "UFC APEX",
      "venue_city": "Las Vegas",
      "venue_state": "NV",
      "venue_country": "USA",
      "status": "completed",
      "main_card_start_time": null,
      "prelims_start_time": null,
      "early_prelims_start_time": null,
      "league": {
        "id": 1,
        "name": "UFC",
        "abbreviation": "UFC"
      }
    },
    {
      "id": 38973,
      "name": "UFC 323: Dvalishvili vs. Yan 2",
      "short_name": "UFC 323: Dvalishvili vs. Yan 2",
      "date": "2025-12-06T18:00:00.000Z",
      "venue_name": "T-Mobile Arena",
      "venue_city": "Las Vegas",
      "venue_state": "NV",
      "venue_country": "USA",
      "status": "completed",
      "main_card_start_time": null,
      "prelims_start_time": null,
      "early_prelims_start_time": null,
      "league": {
        "id": 1,
        "name": "UFC",
        "abbreviation": "UFC"
      }
    }
  ],
  "meta": {
    "next_cursor": 38971,
    "per_page": 25
  }
}

This endpoint retrieves all MMA events with optional filtering.

HTTP Request

GET https://api.balldontlie.io/mma/v1/events

Query Parameters

Parameter	Type	Description
cursor	integer	Cursor for pagination
per_page	integer	Number of results per page (max 100)
date	string	Filter by event date (YYYY-MM-DD)
year	integer	Filter by event year

Get Specific Event

curl "https://api.balldontlie.io/mma/v1/events/38973" \
  -H "Authorization: YOUR_API_KEY"

const response = await fetch('https://api.balldontlie.io/mma/v1/events/38973', {
  headers: {
    'Authorization': 'YOUR_API_KEY'
  }
});
const data = await response.json();
console.log(data);

import requests

event_id = 38973
response = requests.get(
    f'https://api.balldontlie.io/mma/v1/events/{event_id}',
    headers={'Authorization': 'YOUR_API_KEY'}
)

if response.status_code == 200:
    event = response.json()['data']
    print(f"{event['name']} at {event['venue_name']}")

{
  "data": {
    "id": 38973,
    "name": "UFC 323: Dvalishvili vs. Yan 2",
    "short_name": "UFC 323: Dvalishvili vs. Yan 2",
    "date": "2025-12-06T18:00:00.000Z",
    "venue_name": "T-Mobile Arena",
    "venue_city": "Las Vegas",
    "venue_state": "NV",
    "venue_country": "USA",
    "status": "completed",
    "main_card_start_time": null,
    "prelims_start_time": null,
    "early_prelims_start_time": null,
    "league": {
      "id": 1,
      "name": "UFC",
      "abbreviation": "UFC"
    }
  }
}

This endpoint retrieves a specific MMA event.

HTTP Request

GET https://api.balldontlie.io/mma/v1/events/{id}

URL Parameters

Parameter	Description
id	The ID of the event

Fighters

Get All Fighters

curl "https://api.balldontlie.io/mma/v1/fighters?search=McGregor" \
  -H "Authorization: YOUR_API_KEY"

const response = await fetch('https://api.balldontlie.io/mma/v1/fighters?search=McGregor', {
  headers: {
    'Authorization': 'YOUR_API_KEY'
  }
});
const data = await response.json();
console.log(data);

import requests

response = requests.get(
    'https://api.balldontlie.io/mma/v1/fighters',
    headers={'Authorization': 'YOUR_API_KEY'},
    params={'search': 'McGregor'}
)

if response.status_code == 200:
    fighters = response.json()['data']
    for fighter in fighters:
        record = f"{fighter['record_wins']}-{fighter['record_losses']}"
        if fighter['record_draws']:
            record += f"-{fighter['record_draws']}"
        print(f"{fighter['name']} ({record})")

{
  "data": [
    {
      "id": 6592,
      "name": "Conor McGregor",
      "first_name": "Conor",
      "last_name": "McGregor",
      "nickname": "The Notorious",
      "date_of_birth": null,
      "birth_place": null,
      "nationality": "Ireland",
      "height_inches": null,
      "reach_inches": 74,
      "weight_lbs": null,
      "stance": "Southpaw",
      "record_wins": 22,
      "record_losses": 6,
      "record_draws": 0,
      "record_no_contests": 0,
      "active": true,
      "weight_class": {
        "id": 5,
        "name": "Lightweight",
        "abbreviation": "LW",
        "weight_limit_lbs": 155,
        "gender": "Male"
      }
    }
  ],
  "meta": {
    "per_page": 25
  }
}

This endpoint retrieves all MMA fighters with optional search and filtering.

HTTP Request

GET https://api.balldontlie.io/mma/v1/fighters

Query Parameters

Parameter	Type	Description
cursor	integer	Cursor for pagination
per_page	integer	Number of results per page (max 100)
search	string	Search fighters by name
fighter_ids	array	Filter by specific fighter IDs

Get Specific Fighter

curl "https://api.balldontlie.io/mma/v1/fighters/6592" \
  -H "Authorization: YOUR_API_KEY"

const response = await fetch('https://api.balldontlie.io/mma/v1/fighters/6592', {
  headers: {
    'Authorization': 'YOUR_API_KEY'
  }
});
const data = await response.json();
console.log(data);

import requests

fighter_id = 6592
response = requests.get(
    f'https://api.balldontlie.io/mma/v1/fighters/{fighter_id}',
    headers={'Authorization': 'YOUR_API_KEY'}
)

if response.status_code == 200:
    fighter = response.json()['data']
    print(f"{fighter['name']} - {fighter['weight_class']['name']}")
    print(f"Record: {fighter['record_wins']}-{fighter['record_losses']}")

{
  "data": {
    "id": 6592,
    "name": "Conor McGregor",
    "first_name": "Conor",
    "last_name": "McGregor",
    "nickname": "The Notorious",
    "date_of_birth": null,
    "birth_place": null,
    "nationality": "Ireland",
    "height_inches": null,
    "reach_inches": 74,
    "weight_lbs": null,
    "stance": "Southpaw",
    "record_wins": 22,
    "record_losses": 6,
    "record_draws": 0,
    "record_no_contests": 0,
    "active": true,
    "weight_class": {
      "id": 5,
      "name": "Lightweight",
      "abbreviation": "LW",
      "weight_limit_lbs": 155,
      "gender": "Male"
    }
  }
}

This endpoint retrieves a specific fighter.

HTTP Request

GET https://api.balldontlie.io/mma/v1/fighters/{id}

URL Parameters

Parameter	Description
id	The ID of the fighter

Fights

Get All Fights

curl "https://api.balldontlie.io/mma/v1/fights?event_ids[]=38983" \
  -H "Authorization: YOUR_API_KEY"

const params = new URLSearchParams();
params.append('event_ids[]', 38983);

const response = await fetch(`https://api.balldontlie.io/mma/v1/fights?${params}`, {
  headers: {
    'Authorization': 'YOUR_API_KEY'
  }
});
const data = await response.json();
console.log(data);

import requests

response = requests.get(
    'https://api.balldontlie.io/mma/v1/fights',
    headers={'Authorization': 'YOUR_API_KEY'},
    params={'event_ids[]': 38983}
)

if response.status_code == 200:
    fights = response.json()['data']
    for fight in fights:
        print(f"{fight['fighter1']['name']} vs {fight['fighter2']['name']}")
        if fight['winner']:
            print(f"Winner: {fight['winner']['name']} by {fight['result_method']}")

{
  "data": [
    {
      "id": 28111,
      "event": {
        "id": 38983,
        "name": "UFC 326: Holloway vs. Oliveira 2",
        "short_name": "UFC 326: Holloway vs. Oliveira 2",
        "date": "2026-03-07T17:00:00.000Z",
        "venue_name": "T-Mobile Arena",
        "venue_city": "Las Vegas",
        "venue_state": "NV",
        "venue_country": "USA",
        "status": "scheduled",
        "main_card_start_time": null,
        "prelims_start_time": null,
        "early_prelims_start_time": null,
        "league": {
          "id": 1,
          "name": "UFC",
          "abbreviation": "UFC"
        }
      },
      "fighter1": {
        "id": 5106,
        "name": "Charles Oliveira",
        "first_name": "Charles",
        "last_name": "Oliveira",
        "nickname": "Do Bronxs",
        "date_of_birth": "1989-10-16T00:00:00.000Z",
        "birth_place": null,
        "nationality": "Brazil",
        "height_inches": 70,
        "reach_inches": 74,
        "weight_lbs": 156,
        "stance": "Orthodox",
        "record_wins": 36,
        "record_losses": 11,
        "record_draws": 0,
        "record_no_contests": 0,
        "active": true,
        "weight_class": {
          "id": 5,
          "name": "Lightweight",
          "abbreviation": "LW",
          "weight_limit_lbs": 155,
          "gender": "Male"
        }
      },
      "fighter2": {
        "id": 6515,
        "name": "Max Holloway",
        "first_name": "Max",
        "last_name": "Holloway",
        "nickname": "Blessed",
        "date_of_birth": "1991-12-03T00:00:00.000Z",
        "birth_place": null,
        "nationality": "USA",
        "height_inches": 71,
        "reach_inches": 69,
        "weight_lbs": 155,
        "stance": "Orthodox",
        "record_wins": 27,
        "record_losses": 8,
        "record_draws": 0,
        "record_no_contests": 0,
        "active": true,
        "weight_class": {
          "id": 5,
          "name": "Lightweight",
          "abbreviation": "LW",
          "weight_limit_lbs": 155,
          "gender": "Male"
        }
      },
      "winner": null,
      "weight_class": {
        "id": 5,
        "name": "Lightweight",
        "abbreviation": "LW",
        "weight_limit_lbs": 155,
        "gender": "Male"
      },
      "is_main_event": true,
      "is_title_fight": false,
      "card_segment": "main_card",
      "fight_order": 1,
      "scheduled_rounds": 3,
      "result_method": null,
      "result_method_detail": null,
      "result_round": null,
      "result_time": null,
      "status": "scheduled"
    }
  ],
  "meta": {
    "per_page": 25
  }
}

This endpoint retrieves all fights with optional filtering.

HTTP Request

GET https://api.balldontlie.io/mma/v1/fights

Query Parameters

Parameter	Type	Description
cursor	integer	Cursor for pagination
per_page	integer	Number of results per page (max 100)
fight_ids	array	Filter by specific fight IDs
fighter_ids	array	Filter fights involving specific fighters
event_ids	array	Filter fights by event IDs

Get Specific Fight

curl "https://api.balldontlie.io/mma/v1/fights/28002" \
  -H "Authorization: YOUR_API_KEY"

const response = await fetch('https://api.balldontlie.io/mma/v1/fights/28002', {
  headers: {
    'Authorization': 'YOUR_API_KEY'
  }
});
const data = await response.json();
console.log(data);

import requests

fight_id = 28002
response = requests.get(
    f'https://api.balldontlie.io/mma/v1/fights/{fight_id}',
    headers={'Authorization': 'YOUR_API_KEY'}
)

if response.status_code == 200:
    fight = response.json()['data']
    print(f"{fight['fighter1']['name']} vs {fight['fighter2']['name']}")
    print(f"Method: {fight['result_method']} in Round {fight['result_round']}")

{
  "data": {
    "id": 28002,
    "event": {
      "id": 38973,
      "name": "UFC 323: Dvalishvili vs. Yan 2",
      "short_name": "UFC 323: Dvalishvili vs. Yan 2",
      "date": "2025-12-06T18:00:00.000Z",
      "venue_name": "T-Mobile Arena",
      "venue_city": "Las Vegas",
      "venue_state": "NV",
      "venue_country": "USA",
      "status": "completed",
      "main_card_start_time": null,
      "prelims_start_time": null,
      "early_prelims_start_time": null,
      "league": {
        "id": 1,
        "name": "UFC",
        "abbreviation": "UFC"
      }
    },
    "fighter1": {
      "id": 25,
      "name": "Antonio Trocoli",
      "first_name": "Antonio",
      "last_name": "Trocoli",
      "nickname": "Malvado",
      "date_of_birth": "1990-12-05T00:00:00.000Z",
      "birth_place": null,
      "nationality": "Brazil",
      "height_inches": 77,
      "reach_inches": 80,
      "weight_lbs": 186,
      "stance": "Orthodox",
      "record_wins": 12,
      "record_losses": 6,
      "record_draws": 0,
      "record_no_contests": 0,
      "active": true,
      "weight_class": {
        "id": 3,
        "name": "Middleweight",
        "abbreviation": "MW",
        "weight_limit_lbs": 185,
        "gender": "Male"
      }
    },
    "fighter2": {
      "id": 26,
      "name": "Mansur Abdul-Malik",
      "first_name": "Mansur",
      "last_name": "Abdul-Malik",
      "nickname": null,
      "date_of_birth": "1997-10-06T00:00:00.000Z",
      "birth_place": null,
      "nationality": "USA",
      "height_inches": 74,
      "reach_inches": 79,
      "weight_lbs": 185,
      "stance": "Orthodox",
      "record_wins": 9,
      "record_losses": 0,
      "record_draws": 1,
      "record_no_contests": 0,
      "active": true,
      "weight_class": {
        "id": 3,
        "name": "Middleweight",
        "abbreviation": "MW",
        "weight_limit_lbs": 185,
        "gender": "Male"
      }
    },
    "winner": {
      "id": 26,
      "name": "Mansur Abdul-Malik",
      "first_name": "Mansur",
      "last_name": "Abdul-Malik",
      "nickname": null,
      "date_of_birth": "1997-10-06T00:00:00.000Z",
      "birth_place": null,
      "nationality": "USA",
      "height_inches": 74,
      "reach_inches": 79,
      "weight_lbs": 185,
      "stance": "Orthodox",
      "record_wins": 9,
      "record_losses": 0,
      "record_draws": 1,
      "record_no_contests": 0,
      "active": true,
      "weight_class": {
        "id": 3,
        "name": "Middleweight",
        "abbreviation": "MW",
        "weight_limit_lbs": 185,
        "gender": "Male"
      }
    },
    "weight_class": {
      "id": 3,
      "name": "Middleweight",
      "abbreviation": "MW",
      "weight_limit_lbs": 185,
      "gender": "Male"
    },
    "is_main_event": false,
    "is_title_fight": false,
    "card_segment": "prelims",
    "fight_order": 4,
    "scheduled_rounds": 3,
    "result_method": "Submission",
    "result_method_detail": "Victory by Guillotine Choke",
    "result_round": 1,
    "result_time": "1:09",
    "status": "completed"
  }
}

This endpoint retrieves a specific fight.

HTTP Request

GET https://api.balldontlie.io/mma/v1/fights/{id}

URL Parameters

Parameter	Description
id	The ID of the fight

Rankings

Get Rankings

curl "https://api.balldontlie.io/mma/v1/rankings" \
  -H "Authorization: YOUR_API_KEY"

const response = await fetch('https://api.balldontlie.io/mma/v1/rankings', {
  headers: {
    'Authorization': 'YOUR_API_KEY'
  }
});
const data = await response.json();
console.log(data);

import requests

response = requests.get(
    'https://api.balldontlie.io/mma/v1/rankings',
    headers={'Authorization': 'YOUR_API_KEY'}
)

if response.status_code == 200:
    weight_classes = response.json()['data']
    for wc in weight_classes:
        print(f"\n{wc['league']['abbreviation']} {wc['weight_class']['name']}:")
        for ranking in wc['rankings']:
            if ranking['is_champion']:
                print(f"Champion: {ranking['fighter']['name']}")
            else:
                print(f"#{ranking['rank']}: {ranking['fighter']['name']}")

{
  "data": [
    {
      "weight_class": {
        "id": 7,
        "name": "Bantamweight",
        "abbreviation": "BW",
        "weight_limit_lbs": 135,
        "gender": "Male"
      },
      "league": {
        "id": 1,
        "name": "UFC",
        "abbreviation": "UFC"
      },
      "rankings": [
        {
          "rank": 0,
          "is_champion": true,
          "is_interim_champion": false,
          "fighter": {
            "id": 1,
            "name": "Petr Yan",
            "first_name": "Petr",
            "last_name": "Yan",
            "nickname": "No Mercy",
            "date_of_birth": "1993-02-10T00:00:00.000Z",
            "birth_place": null,
            "nationality": "Russia",
            "height_inches": 67,
            "reach_inches": 67,
            "weight_lbs": 135,
            "stance": "Switch",
            "record_wins": 20,
            "record_losses": 5,
            "record_draws": 0,
            "record_no_contests": 0,
            "active": true,
            "weight_class": {
              "id": 7,
              "name": "Bantamweight",
              "abbreviation": "BW",
              "weight_limit_lbs": 135,
              "gender": "Male"
            }
          }
        },
        {
          "rank": 1,
          "is_champion": false,
          "is_interim_champion": false,
          "fighter": {
            "id": 2,
            "name": "Merab Dvalishvili",
            "first_name": "Merab",
            "last_name": "Dvalishvili",
            "nickname": "The Machine",
            "date_of_birth": "1991-01-09T00:00:00.000Z",
            "birth_place": null,
            "nationality": "Georgia",
            "height_inches": 66,
            "reach_inches": 68,
            "weight_lbs": 135,
            "stance": "Orthodox",
            "record_wins": 21,
            "record_losses": 5,
            "record_draws": 0,
            "record_no_contests": 0,
            "active": true,
            "weight_class": {
              "id": 7,
              "name": "Bantamweight",
              "abbreviation": "BW",
              "weight_limit_lbs": 135,
              "gender": "Male"
            }
          }
        },
        {
          "rank": 2,
          "is_champion": false,
          "is_interim_champion": false,
          "fighter": {
            "id": 13065,
            "name": "Umar Nurmagomedov",
            "first_name": "Umar",
            "last_name": "Nurmagomedov",
            "nickname": null,
            "date_of_birth": "1996-01-02T00:00:00.000Z",
            "birth_place": null,
            "nationality": "Russia",
            "height_inches": 68,
            "reach_inches": 69,
            "weight_lbs": 136,
            "stance": "Orthodox",
            "record_wins": 19,
            "record_losses": 1,
            "record_draws": 0,
            "record_no_contests": 0,
            "active": true,
            "weight_class": {
              "id": 7,
              "name": "Bantamweight",
              "abbreviation": "BW",
              "weight_limit_lbs": 135,
              "gender": "Male"
            }
          }
        },
        {
          "rank": 3,
          "is_champion": false,
          "is_interim_champion": false,
          "fighter": {
            "id": 12915,
            "name": "Sean O'Malley",
            "first_name": "Sean",
            "last_name": "O'Malley",
            "nickname": "Suga",
            "date_of_birth": "1994-10-23T00:00:00.000Z",
            "birth_place": null,
            "nationality": "USA",
            "height_inches": 71,
            "reach_inches": 72,
            "weight_lbs": 135,
            "stance": "Switch",
            "record_wins": 18,
            "record_losses": 3,
            "record_draws": 0,
            "record_no_contests": 0,
            "active": true,
            "weight_class": {
              "id": 7,
              "name": "Bantamweight",
              "abbreviation": "BW",
              "weight_limit_lbs": 135,
              "gender": "Male"
            }
          }
        },
        {
          "rank": 4,
          "is_champion": false,
          "is_interim_champion": false,
          "fighter": {
            "id": 12318,
            "name": "Cory Sandhagen",
            "first_name": "Cory",
            "last_name": "Sandhagen",
            "nickname": null,
            "date_of_birth": "1992-04-19T00:00:00.000Z",
            "birth_place": null,
            "nationality": "USA",
            "height_inches": 71,
            "reach_inches": 70,
            "weight_lbs": 134,
            "stance": "Switch",
            "record_wins": 18,
            "record_losses": 6,
            "record_draws": 0,
            "record_no_contests": 0,
            "active": true,
            "weight_class": {
              "id": 7,
              "name": "Bantamweight",
              "abbreviation": "BW",
              "weight_limit_lbs": 135,
              "gender": "Male"
            }
          }
        },
        {
          "rank": 5,
          "is_champion": false,
          "is_interim_champion": false,
          "fighter": {
            "id": 9283,
            "name": "Song Yadong",
            "first_name": "Song",
            "last_name": "Yadong",
            "nickname": "Kung Fu Kid",
            "date_of_birth": "1997-12-01T00:00:00.000Z",
            "birth_place": null,
            "nationality": "China",
            "height_inches": 68,
            "reach_inches": 67,
            "weight_lbs": 136,
            "stance": "Orthodox",
            "record_wins": 22,
            "record_losses": 8,
            "record_draws": 1,
            "record_no_contests": 0,
            "active": true,
            "weight_class": {
              "id": 7,
              "name": "Bantamweight",
              "abbreviation": "BW",
              "weight_limit_lbs": 135,
              "gender": "Male"
            }
          }
        }
      ]
    }
  ]
}

This endpoint retrieves current fighter rankings organized by weight class and league.

HTTP Request

GET https://api.balldontlie.io/mma/v1/rankings

Query Parameters

This endpoint does not accept query parameters.

Fight Stats

Get Fight Statistics

curl "https://api.balldontlie.io/mma/v1/fight_stats?fight_ids[]=28002" \
  -H "Authorization: YOUR_API_KEY"

const params = new URLSearchParams();
params.append('fight_ids[]', 28002);

const response = await fetch(`https://api.balldontlie.io/mma/v1/fight_stats?${params}`, {
  headers: {
    'Authorization': 'YOUR_API_KEY'
  }
});
const data = await response.json();
console.log(data);

import requests

response = requests.get(
    'https://api.balldontlie.io/mma/v1/fight_stats',
    headers={'Authorization': 'YOUR_API_KEY'},
    params={'fight_ids[]': 28002}
)

if response.status_code == 200:
    stats = response.json()['data']
    for stat in stats:
        fighter = stat['fighter']['name']
        sig_strikes = f"{stat['significant_strikes_landed']}/{stat['significant_strikes_attempted']}"
        takedowns = f"{stat['takedowns_landed']}/{stat['takedowns_attempted']}"
        print(f"{fighter}: Sig Strikes {sig_strikes}, Takedowns {takedowns}")

{
  "data": [
    {
      "id": 55637,
      "fight_id": 28002,
      "fighter": {
        "id": 26,
        "name": "Mansur Abdul-Malik",
        "first_name": "Mansur",
        "last_name": "Abdul-Malik",
        "nickname": null,
        "date_of_birth": "1997-10-06T00:00:00.000Z",
        "birth_place": null,
        "nationality": "USA",
        "height_inches": 74,
        "reach_inches": 79,
        "weight_lbs": 185,
        "stance": "Orthodox",
        "record_wins": 9,
        "record_losses": 0,
        "record_draws": 1,
        "record_no_contests": 0,
          "active": true,
        "weight_class": {
          "id": 3,
          "name": "Middleweight",
          "abbreviation": "MW",
          "weight_limit_lbs": 185,
          "gender": "Male"
        }
      },
      "is_winner": true,
      "knockdowns": 0,
      "significant_strikes_landed": 2,
      "significant_strikes_attempted": 4,
      "significant_strike_pct": 50,
      "total_strikes_landed": 2,
      "total_strikes_attempted": 4,
      "head_strikes_landed": 2,
      "head_strikes_attempted": 4,
      "body_strikes_landed": 0,
      "body_strikes_attempted": 0,
      "leg_strikes_landed": 0,
      "leg_strikes_attempted": 0,
      "sig_distance_head_landed": 1,
      "sig_distance_head_attempted": 3,
      "sig_distance_body_landed": 0,
      "sig_distance_body_attempted": 0,
      "sig_distance_leg_landed": 0,
      "sig_distance_leg_attempted": 0,
      "sig_clinch_head_landed": 0,
      "sig_clinch_head_attempted": 0,
      "sig_clinch_body_landed": 0,
      "sig_clinch_body_attempted": 0,
      "sig_clinch_leg_landed": 0,
      "sig_clinch_leg_attempted": 0,
      "sig_ground_head_landed": 1,
      "sig_ground_head_attempted": 1,
      "sig_ground_body_landed": 0,
      "sig_ground_body_attempted": 0,
      "sig_ground_leg_landed": 0,
      "sig_ground_leg_attempted": 0,
      "target_head_pct": 50,
      "target_body_pct": 0,
      "target_leg_pct": 0,
      "takedowns_landed": 1,
      "takedowns_attempted": 1,
      "takedown_pct": 100,
      "takedown_slams": 0,
      "slam_rate": 0,
      "reversals": 0,
      "submissions_attempted": 1,
      "control_time_seconds": 42,
      "advances": 0,
      "advance_to_back": 0,
      "advance_to_half_guard": 0,
      "advance_to_mount": 0,
      "advance_to_side": 0
    },
    {
      "id": 55636,
      "fight_id": 28002,
      "fighter": {
        "id": 25,
        "name": "Antonio Trocoli",
        "first_name": "Antonio",
        "last_name": "Trocoli",
        "nickname": "Malvado",
        "date_of_birth": "1990-12-05T00:00:00.000Z",
        "birth_place": null,
        "nationality": "Brazil",
        "height_inches": 77,
        "reach_inches": 80,
        "weight_lbs": 186,
        "stance": "Orthodox",
        "record_wins": 12,
        "record_losses": 6,
        "record_draws": 0,
        "record_no_contests": 0,
          "active": true,
        "weight_class": {
          "id": 3,
          "name": "Middleweight",
          "abbreviation": "MW",
          "weight_limit_lbs": 185,
          "gender": "Male"
        }
      },
      "is_winner": false,
      "knockdowns": 0,
      "significant_strikes_landed": 3,
      "significant_strikes_attempted": 6,
      "significant_strike_pct": 50,
      "total_strikes_landed": 3,
      "total_strikes_attempted": 6,
      "head_strikes_landed": 2,
      "head_strikes_attempted": 4,
      "body_strikes_landed": 0,
      "body_strikes_attempted": 1,
      "leg_strikes_landed": 1,
      "leg_strikes_attempted": 1,
      "sig_distance_head_landed": 2,
      "sig_distance_head_attempted": 4,
      "sig_distance_body_landed": 0,
      "sig_distance_body_attempted": 1,
      "sig_distance_leg_landed": 1,
      "sig_distance_leg_attempted": 1,
      "sig_clinch_head_landed": 0,
      "sig_clinch_head_attempted": 0,
      "sig_clinch_body_landed": 0,
      "sig_clinch_body_attempted": 0,
      "sig_clinch_leg_landed": 0,
      "sig_clinch_leg_attempted": 0,
      "sig_ground_head_landed": 0,
      "sig_ground_head_attempted": 0,
      "sig_ground_body_landed": 0,
      "sig_ground_body_attempted": 0,
      "sig_ground_leg_landed": 0,
      "sig_ground_leg_attempted": 0,
      "target_head_pct": 50,
      "target_body_pct": 0,
      "target_leg_pct": 100,
      "takedowns_landed": 0,
      "takedowns_attempted": 1,
      "takedown_pct": 0,
      "takedown_slams": 0,
      "slam_rate": 0,
      "reversals": 0,
      "submissions_attempted": 0,
      "control_time_seconds": 0,
      "advances": 0,
      "advance_to_back": 0,
      "advance_to_half_guard": 0,
      "advance_to_mount": 0,
      "advance_to_side": 0
    }
  ],
  "meta": {
    "per_page": 25
  }
}

This endpoint retrieves detailed fight statistics for fighters.

HTTP Request

GET https://api.balldontlie.io/mma/v1/fight_stats

Query Parameters

Parameter	Type	Description
cursor	integer	Cursor for pagination
per_page	integer	Number of results per page (max 100)
fight_ids	array	Filter by specific fight IDs
fighter_ids	array	Filter statistics for specific fighters
event_ids	array	Filter statistics by event IDs

Get Specific Fight Stat

curl "https://api.balldontlie.io/mma/v1/fight_stats/55637" \
  -H "Authorization: YOUR_API_KEY"

const response = await fetch('https://api.balldontlie.io/mma/v1/fight_stats/55637', {
  headers: {
    'Authorization': 'YOUR_API_KEY'
  }
});
const data = await response.json();
console.log(data);

import requests

stat_id = 55637
response = requests.get(
    f'https://api.balldontlie.io/mma/v1/fight_stats/{stat_id}',
    headers={'Authorization': 'YOUR_API_KEY'}
)

if response.status_code == 200:
    stat = response.json()['data']
    print(f"{stat['fighter']['name']} Statistics:")
    print(f"Significant Strikes: {stat['significant_strikes_landed']}/{stat['significant_strikes_attempted']}")
    print(f"Takedowns: {stat['takedowns_landed']}/{stat['takedowns_attempted']}")

{
  "data": {
    "id": 55637,
    "fight_id": 28002,
    "fighter": {
      "id": 26,
      "name": "Mansur Abdul-Malik",
      "first_name": "Mansur",
      "last_name": "Abdul-Malik",
      "nickname": null,
      "date_of_birth": "1997-10-06T00:00:00.000Z",
      "birth_place": null,
      "nationality": "USA",
      "height_inches": 74,
      "reach_inches": 79,
      "weight_lbs": 185,
      "stance": "Orthodox",
      "record_wins": 9,
      "record_losses": 0,
      "record_draws": 1,
      "record_no_contests": 0,
      "active": true,
      "weight_class": {
        "id": 3,
        "name": "Middleweight",
        "abbreviation": "MW",
        "weight_limit_lbs": 185,
        "gender": "Male"
      }
    },
    "is_winner": true,
    "knockdowns": 0,
    "significant_strikes_landed": 2,
    "significant_strikes_attempted": 4,
    "significant_strike_pct": 50,
    "total_strikes_landed": 2,
    "total_strikes_attempted": 4,
    "head_strikes_landed": 2,
    "head_strikes_attempted": 4,
    "body_strikes_landed": 0,
    "body_strikes_attempted": 0,
    "leg_strikes_landed": 0,
    "leg_strikes_attempted": 0,
    "sig_distance_head_landed": 1,
    "sig_distance_head_attempted": 3,
    "sig_distance_body_landed": 0,
    "sig_distance_body_attempted": 0,
    "sig_distance_leg_landed": 0,
    "sig_distance_leg_attempted": 0,
    "sig_clinch_head_landed": 0,
    "sig_clinch_head_attempted": 0,
    "sig_clinch_body_landed": 0,
    "sig_clinch_body_attempted": 0,
    "sig_clinch_leg_landed": 0,
    "sig_clinch_leg_attempted": 0,
    "sig_ground_head_landed": 1,
    "sig_ground_head_attempted": 1,
    "sig_ground_body_landed": 0,
    "sig_ground_body_attempted": 0,
    "sig_ground_leg_landed": 0,
    "sig_ground_leg_attempted": 0,
    "target_head_pct": 50,
    "target_body_pct": 0,
    "target_leg_pct": 0,
    "takedowns_landed": 1,
    "takedowns_attempted": 1,
    "takedown_pct": 100,
    "takedown_slams": 0,
    "slam_rate": 0,
    "reversals": 0,
    "submissions_attempted": 1,
    "control_time_seconds": 42,
    "advances": 0,
    "advance_to_back": 0,
    "advance_to_half_guard": 0,
    "advance_to_mount": 0,
    "advance_to_side": 0
  }
}

This endpoint retrieves statistics for a specific fight performance.

HTTP Request

GET https://api.balldontlie.io/mma/v1/fight_stats/{id}

URL Parameters

Parameter	Description
id	The ID of the fight stat

Betting Odds

Get Betting Odds

curl "https://api.balldontlie.io/mma/v1/odds?event_id=38983" \
  -H "Authorization: YOUR_API_KEY"

const response = await fetch('https://api.balldontlie.io/mma/v1/odds?event_id=38983', {
  headers: {
    'Authorization': 'YOUR_API_KEY'
  }
});
const data = await response.json();
console.log(data);

import requests

response = requests.get(
    'https://api.balldontlie.io/mma/v1/odds',
    headers={'Authorization': 'YOUR_API_KEY'},
    params={'event_id': 38983}
)

if response.status_code == 200:
    odds = response.json()['data']
    for odd in odds:
        print(f"{odd['vendor']}: {odd['fighter1']['name']} ({odd['fighter1_odds']}) vs {odd['fighter2']['name']} ({odd['fighter2_odds']})")

{
  "data": [
    {
      "id": 36187452,
      "fight_id": 28111,
      "vendor": "draftkings",
      "fighter1": {
        "id": 5106,
        "name": "Charles Oliveira",
        "first_name": "Charles",
        "last_name": "Oliveira",
        "nickname": "Do Bronxs",
        "date_of_birth": "1989-10-16T00:00:00.000Z",
        "birth_place": null,
        "nationality": "Brazil",
        "height_inches": 70,
        "reach_inches": 74,
        "weight_lbs": 156,
        "stance": "Orthodox",
        "record_wins": 36,
        "record_losses": 11,
        "record_draws": 0,
        "record_no_contests": 0,
        "active": true,
        "weight_class": {
          "id": 5,
          "name": "Lightweight",
          "abbreviation": "LW",
          "weight_limit_lbs": 155,
          "gender": "Male"
        }
      },
      "fighter2": {
        "id": 6515,
        "name": "Max Holloway",
        "first_name": "Max",
        "last_name": "Holloway",
        "nickname": "Blessed",
        "date_of_birth": "1991-12-03T00:00:00.000Z",
        "birth_place": null,
        "nationality": "USA",
        "height_inches": 71,
        "reach_inches": 69,
        "weight_lbs": 155,
        "stance": "Orthodox",
        "record_wins": 27,
        "record_losses": 8,
        "record_draws": 0,
        "record_no_contests": 0,
        "active": true,
        "weight_class": {
          "id": 5,
          "name": "Lightweight",
          "abbreviation": "LW",
          "weight_limit_lbs": 155,
          "gender": "Male"
        }
      },
      "fighter1_odds": -200,
      "fighter2_odds": 154,
      "updated_at": "2025-12-15T21:55:30.630Z"
    },
    {
      "id": 36187442,
      "fight_id": 28111,
      "vendor": "fanduel",
      "fighter1": {
        "id": 5106,
        "name": "Charles Oliveira",
        "first_name": "Charles",
        "last_name": "Oliveira",
        "nickname": "Do Bronxs",
        "date_of_birth": "1989-10-16T00:00:00.000Z",
        "birth_place": null,
        "nationality": "Brazil",
        "height_inches": 70,
        "reach_inches": 74,
        "weight_lbs": 156,
        "stance": "Orthodox",
        "record_wins": 36,
        "record_losses": 11,
        "record_draws": 0,
        "record_no_contests": 0,
        "active": true,
        "weight_class": {
          "id": 5,
          "name": "Lightweight",
          "abbreviation": "LW",
          "weight_limit_lbs": 155,
          "gender": "Male"
        }
      },
      "fighter2": {
        "id": 6515,
        "name": "Max Holloway",
        "first_name": "Max",
        "last_name": "Holloway",
        "nickname": "Blessed",
        "date_of_birth": "1991-12-03T00:00:00.000Z",
        "birth_place": null,
        "nationality": "USA",
        "height_inches": 71,
        "reach_inches": 69,
        "weight_lbs": 155,
        "stance": "Orthodox",
        "record_wins": 27,
        "record_losses": 8,
        "record_draws": 0,
        "record_no_contests": 0,
        "active": true,
        "weight_class": {
          "id": 5,
          "name": "Lightweight",
          "abbreviation": "LW",
          "weight_limit_lbs": 155,
          "gender": "Male"
        }
      },
      "fighter1_odds": 146,
      "fighter2_odds": -188,
      "updated_at": "2025-12-15T21:55:00.541Z"
    }
  ]
}

This endpoint retrieves betting odds for MMA fights from various sportsbooks.

Important: Either event_id or fight_id must be provided.

HTTP Request

GET https://api.balldontlie.io/mma/v1/odds

Query Parameters

Parameter	Type	Description	Required
event_id	integer	Filter odds by event ID	No*
fight_id	integer	Filter odds by fight ID	No*

*At least one of event_id or fight_id is required.

Available Vendors

Vendor	Description
caesars	Caesars Sportsbook
draftkings	DraftKings
fanduel	FanDuel
kalshi	Kalshi (prediction market)

Odds Format

Odds are returned in American format: - Negative odds (e.g., -200) indicate the favorite and show how much you need to bet to win $100 - Positive odds (e.g., +154) indicate the underdog and show how much you win on a $100 bet