# Fight Matrix MMA Rankings Scraper (`artsiom_k/fightmatrix-scraper`) Actor

Fight Matrix MMA rankings: every ranked fighter in every division, quarterly historical rankings since 1990, and fighter profiles with ratings, stats and fight history.

- **URL**: https://apify.com/artsiom_k/fightmatrix-scraper.md
- **Developed by:** [Artsiom Kunitsyn](https://apify.com/artsiom_k) (community)
- **Categories:** Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.05 / 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

## Fight Matrix MMA Rankings Scraper

Scrapes MMA rankings from [Fight Matrix](https://www.fightmatrix.com), the computer-rating site that ranks
every active fighter, not just the top 15: **current rankings for every division as deep as the site goes**
(about 1,500 fighters in a big division), **quarterly historical rankings back to 1990**, and **fighter
profiles** with rating stats, every fight with the opponent's rank at the time, and the fighter's Sherdog id.
No login required.

### Contents

- [Key features](#key-features)
- [Output](#output)
- [Input](#input)
- [Input examples](#input-examples)
- [Incremental mode](#incremental-mode)
- [FAQ](#faq)

### 🔑 Key features

- **Every ranked fighter.** All men's and women's divisions, pound-for-pound and the division dominance
  lists, from #1 to the last ranked fighter, with rating points, movement, age, country and record.
- **Rating stats per fighter.** Gym, pro debut, "big league" record, last three years, finish rate,
  quality-performance %, the 540 metric, combat age and over/underrated notes.
- **Last fight on every row.** Date, promotion, opponent with their rank, and the result.
- **Filter like the site does.** Only fighters whose last fight was in a promotion (UFC, PFL, ONE, Rizin,
  Oktagon, Cage Warriors, LFA, KSW...), or from one country or region.
- **Five rating systems.** Fight Matrix's own, or the same fights rated by Elo, modified Elo, Glicko-1 or WHR.
- **History since 1990.** Generated rankings for every quarter (Jan 1, Apr 1, Jul 1, Oct 1), every division.
- **Profiles that join other data.** Each profile carries the Sherdog and Tapology links and the Sherdog
  fighter id, plus every fight (opponent's rank at the time, event, date, method, round) and the
  quarterly ranking history.
- **Incremental runs.** Schedule `rankings` and get only fighters whose rank, points or record changed,
  plus the ones who dropped out.
- **`maxItems` defaults to 50**: a fast, cheap preview. Clear it (`null`) for everything in your selection.

### 📋 Output

The **Output** tab lists every field.

**`rankings`**: one row per ranked fighter:

```json
{
  "division": "lightweight",
  "rank": 1,
  "movement": 0,
  "fighter": "Justin Gaethje",
  "fighter_id": 46751,
  "country": "US",
  "age": 37,
  "record": "28-5-0",
  "points": 2677,
  "last_fight_date": "2026-06-14",
  "last_fight_promotion": "UFC",
  "last_opponent": "Ilia Topuria",
  "last_opponent_rank": "2 LW",
  "last_result": "win",
  "association": "Genesis Training Center",
  "big_league_record": "21-5-0",
  "win_finish_pct": 78.6,
  "quality_performance_pct": 66.7,
  "metric_540": 0.727,
  "combat_age": 45,
  "last_5": ["W", "L", "W", "W", "W"],
  "change_type": "new"
}
```

**`historicalRankings`**: one row per fighter per quarterly issue: `issue_date`, division, `rank`,
`movement` (`NR` = newly ranked), fighter, record and points.

**`fighters`**: one row per fighter: birth date, gym, record, current and all-time rankings, highest
quarterly rank, the rating stats above, `sherdog_id`, `tapology_url`, `fights` and `ranking_history`.

### 🔧 Input

| Field | Type | Default | Description |
|---|---|---|---|
| `entityType` | string | `rankings` | `rankings`, `historicalRankings` or `fighters`. |
| `divisions` | array | all | Divisions to scrape. **Empty = all of them.** |
| `maxRank` | integer | — | Only the top N of each division. Empty = the whole list. |
| `promotion` | string | — | `rankings`: only fighters whose last fight was in this promotion, as Fight Matrix names it. |
| `country` | string | — | `rankings`: a country code (`US`, `BR`...) or region (`REU`, `RNA`...). |
| `ratingSystem` | string | `FM` | `rankings`: `FM`, `R_ELOK170`, `R_ELOMOD1`, `R_GLICKO1` or `R_WHR`. |
| `dateFrom` / `dateTo` | string | — | `historicalRankings`: only issues in this window (`YYYY-MM-DD`). |
| `startUrls` | array | — | `fighters`: specific profile URLs. Replaces the division selection. |
| `maxItems` | integer | `50` | Stop after this many rows. `null` = everything selected. |
| `mode` | string | `auto` | `auto` / `full` / `incremental`, `rankings` only. |
| `concurrency` | integer | `6` | Requests in flight (max 12). |
| `proxyConfiguration` | object | no proxy | Apify Proxy settings. Not needed in testing. |

### 📥 Input examples

**Default preview (top of pound-for-pound and the dominance lists):**

```json
{}
```

**The whole lightweight list:**

```json
{ "divisions": ["lightweight"], "maxItems": null }
```

**Top 25 of every division among UFC fighters:**

```json
{ "promotion": "UFC", "maxRank": 25, "maxItems": null }
```

**Top 10 heavyweights every quarter since 2000:**

```json
{ "entityType": "historicalRankings", "divisions": ["heavyweight"], "dateFrom": "2000-01-01", "maxRank": 10, "maxItems": null }
```

**Profiles of the top 50 women's strawweights:**

```json
{ "entityType": "fighters", "divisions": ["womens-strawweight"], "maxRank": 50, "maxItems": null }
```

### 🔁 Incremental mode

`rankings` only, and only for a run with `maxItems` cleared (`null`): a capped run is a preview and always
returns rows. After the first complete run, a scheduled run of the same selection (divisions, filters,
rating system, depth) returns only fighters who are new to the list or whose rank, points or record changed,
and the fighters who dropped out with `change_type: "delisted"`. Each selection keeps its own state.

### ❓ FAQ

**How deep do the rankings go?** As deep as Fight Matrix ranks: about 1,500 fighters in lightweight, fewer
in the smaller divisions. Pound-for-pound has 15, the dominance lists 10.

**What are the "historical rankings"?** Fight Matrix's generated rankings for each quarter since 1990, as the
site publishes them. They are as deep as the current lists for recent years and thinner for the 1990s.

**Why is `country` empty on pound-for-pound rows?** That list doesn't show flags; the division lists do.

**How do I join with Sherdog data?** Profiles carry `sherdog_id`, the id in our
[Sherdog MMA Scraper](https://apify.com/artsiom_k/sherdog-scraper)'s `fighter_id`.

**Is the promotion filter the fighter's current promotion?** It's the promotion of the fighter's last fight,
which is how Fight Matrix filters.

**Can I filter pound-for-pound by promotion?** No: the site's pound-for-pound and dominance lists have no
filters, so a run with `promotion` or `country` skips them and covers the weight divisions.

### Related sports data scrapers

- [Sherdog MMA Scraper](https://apify.com/artsiom_k/sherdog-scraper) — MMA fighter profiles, full fight histories, event cards and bout results for every promotion.
- [BestFightOdds MMA Odds Scraper](https://apify.com/artsiom_k/bestfightodds-scraper) — every sportsbook's MMA moneyline and props, consensus opening and closing lines back to 2008, and line movement.
- [Action Network Scraper](https://apify.com/artsiom_k/actionnetwork-scraper) — US sportsbook odds, public betting splits, line movement, props, injuries and futures.
- [Kalshi & Polymarket Scraper](https://apify.com/artsiom_k/prediction-markets-scraper) — prediction market odds, settled results and price history for sports, politics, economics and crypto.
- [FantasyPros Scraper](https://apify.com/artsiom_k/fantasypros-scraper) — NFL, NBA, MLB and NHL expert consensus rankings, ADP and projections.

# Actor input Schema

## `entityType` (type: `string`):

"rankings": the current Fight Matrix rankings, every ranked fighter (about 1,500 in a big division). "historicalRankings": the quarterly rankings since 1990. "fighters": full fighter profiles with stats, every fight with the opponent's rank at the time and the ranking history.

## `divisions` (type: `array`):

Divisions to scrape. Empty = all of them (men's and women's divisions, pound-for-pound and the dominance lists). For fighters: the fighters ranked in these divisions.

## `maxRank` (type: `integer`):

Only the top N of each division (e.g. 25 or 100). Empty = the whole list.

## `promotion` (type: `string`):

Current rankings: only fighters whose last fight was in this promotion, exactly as Fight Matrix names it (UFC, PFL, ONE Championship, Rizin Fighting Federation, Oktagon MMA, Cage Warriors, LFA, KSW...). Ranks are then within the filter, with the overall rank alongside.

## `country` (type: `string`):

Current rankings: a two-letter country code (US, BR, RU...) or a Fight Matrix region code (REU Europe, REE Eastern Europe, RAS Asia, RWE Western Europe, RNA North America).

## `ratingSystem` (type: `string`):

Current rankings: Fight Matrix's own ratings, or the same fights rated by Elo, modified Elo, Glicko-1 or WHR.

## `dateFrom` (type: `string`):

Historical rankings: only quarterly issues on or after this date (issues are dated Jan 1, Apr 1, Jul 1 and Oct 1, from 1990).

## `dateTo` (type: `string`):

Historical rankings: only issues on or before this date.

## `startUrls` (type: `array`):

Fighters only: specific Fight Matrix profiles (https://www.fightmatrix.com/fighter-profile/Ilia%20Topuria/149195/). When set, they replace the division selection.

## `maxItems` (type: `integer`):

Stop after pushing this many rows. Defaults to 50 - a fast, cheap preview. Set to null for everything in your selection.

## `mode` (type: `string`):

Current rankings only. "incremental" returns only fighters who are new to the list or whose rank, points or record changed since the last complete run of the same selection, plus those who dropped out (delisted). "auto" is incremental when Max results is cleared and an earlier run exists.

## `concurrency` (type: `integer`):

Requests in flight at once.

## `impersonate` (type: `string`):

Browser TLS fingerprint. Change only if requests are blocked.

## `proxyConfiguration` (type: `object`):

Apify Proxy settings. Not needed in testing.

## Actor input object example

```json
{
  "entityType": "rankings",
  "divisions": [],
  "ratingSystem": "FM",
  "maxItems": 50,
  "mode": "auto",
  "concurrency": 6,
  "impersonate": "chrome",
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `results` (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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("artsiom_k/fightmatrix-scraper").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("artsiom_k/fightmatrix-scraper").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 '{}' |
apify call artsiom_k/fightmatrix-scraper --silent --output-dataset

```

## MCP server setup

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

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/VI1wZZ2oCbM76uGk9/builds/VUopCGdKRJ3pfqD8g/openapi.json