# UFC Stats Scraper (`fetchfinch/ufc-stats-scraper`) Actor

Extract structured UFC fighter profiles, career records, event fight cards, fight results, and division and pound-for-pound rankings for sports media, analytics, fantasy applications, and research.

- **URL**: https://apify.com/fetchfinch/ufc-stats-scraper.md
- **Developed by:** [Fetch Finch](https://apify.com/fetchfinch) (community)
- **Categories:** News, Developer tools
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $10.00 / 1,000 ufc results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## UFC Stats Scraper

Extract structured UFC fighter profiles, career records, event cards, fight results, and division rankings from a single Apify Actor.

Use it to power MMA websites, sports journalism, analytics dashboards, fantasy applications, research workflows, and automated fight-week reports.

### What you can collect

#### Fighter profiles and records

- Complete UFC fighter roster
- Search by one or more fighter names
- Nicknames, physical measurements, stance, and weight information
- Win-loss-draw records
- Career striking, takedown, and submission statistics when available
- Complete fight histories with opponents, events, results, methods, rounds, and times

#### Events and fight cards

- Upcoming UFC events
- Completed UFC events
- Event metadata and dates
- Full fight cards
- Fighter matchups and bout details
- Winners, methods, rounds, and finish times for completed fights
- Detailed fight statistics when supplied by the provider

#### Rankings

- UFC weight-division rankings
- Men’s and women’s rankings
- Pound-for-pound rankings
- Champions and ranked fighters
- Rank movement where supplied by the rankings provider

### Why use this Actor?

The Actor provides one consistent interface for the three datasets most UFC applications need: fighters, events, and rankings. You can run a lightweight listing, search for specific names, or request detailed profiles and fight cards only when required.

The data is returned as structured JSON in the Apify dataset, making it easy to export to JSON, CSV, Excel, or connect to downstream automations through the Apify API, webhooks, Make, n8n, or Zapier.

### Common use cases

#### Sports media and journalism

- Build fight-week previews with fighter records and career statistics
- Track newly announced cards and matchup changes
- Generate post-event reports with winners and finish methods
- Create division and pound-for-pound ranking articles

#### Analytics and research

- Compare striking, takedown, and submission profiles
- Analyze finish methods by fighter, division, or event
- Build historical datasets for MMA research
- Track roster changes and ranking movement over time

#### Fantasy and fan applications

- Populate fighter comparison pages
- Build head-to-head fighter profiles
- Display upcoming cards and completed fight results
- Keep fighter and event data updated through scheduled runs

### Getting started

#### Search for one fighter

```json
{
  "mode": "query",
  "dataType": "fighters",
  "searchTerms": ["Conor McGregor"],
  "maxResults": 10
}
```

#### Retrieve the full fighter roster

```json
{
  "mode": "query",
  "dataType": "fighters",
  "maxResults": 1000
}
```

The full roster is normally populated by a scheduled refresh. Query runs read the latest available Actor dataset and do not contact RapidAPI.

#### Retrieve fighter statistics by name

```json
{
  "mode": "query",
  "dataType": "fighters",
  "searchTerms": ["Israel Adesanya"],
  "maxResults": 10
}
```

To populate or update a detailed profile during a scheduled update:

```json
{
  "mode": "refresh",
  "dataType": "fighters",
  "refreshSearchTerms": ["Israel Adesanya"],
  "includeDetails": true,
  "maxResults": 1
}
```

#### Retrieve upcoming events and fight cards

```json
{
  "mode": "query",
  "dataType": "events",
  "eventType": "upcoming",
  "maxResults": 10
}
```

During a scheduled update, use `includeDetails: true` to collect complete fight cards:

```json
{
  "mode": "refresh",
  "dataType": "events",
  "eventType": "upcoming",
  "includeDetails": true,
  "maxResults": 10
}
```

#### Retrieve completed event results

```json
{
  "mode": "query",
  "dataType": "events",
  "eventType": "past",
  "maxResults": 10
}
```

#### Retrieve UFC rankings

```json
{
  "mode": "query",
  "dataType": "rankings",
  "division": "pound-for-pound",
  "maxResults": 100
}
```

Rankings are supplied through MMAAPI. The RapidAPI account used by the Actor must be subscribed to MMAAPI’s plan. Fighters, events, and fight details use UFC Stats API.

### Input reference

#### Main options

| Input | Type | Default | Description |
| --- | --- | --- | --- |
| `mode` | string | `query` | `query` reads the latest available dataset; `refresh` updates it from RapidAPI; `discover` checks MMAAPI categories and tournaments. |
| `dataType` | string | `events` | Dataset to return or update: `fighters`, `events`, `rankings`, or `all`. |
| `provider` | string | `ufc-stats` | UFC Stats handles fighters and events. Use `mmaapi` for MMAAPI event/ranking workflows. |
| `maxResults` | integer | `100` | Maximum number of records returned or processed. |

#### Search and filters

| Input | Type | Description |
| --- | --- | --- |
| `searchTerms` | array | Fighter or event names to match when reading the available dataset. |
| `refreshSearchTerms` | array | Fighter names to fetch during a detailed fighter refresh. |
| `fighterLetters` | array | Letters used for a full UFC Stats roster refresh. Empty uses A–Z. |
| `division` | string | Filter by a weight division or `pound-for-pound`. |
| `gender` | string | Filter rankings or fighters by `male` or `female` where supported. |
| `fighterStatus` | string | Filter fighters by `active`, `not-fighting`, or `retired`. |
| `country` | string | Filter fighters by country or hometown. |
| `eventType` | string | For events, choose `upcoming`, `past`, or `all`. |

#### Detail and refresh controls

| Input | Type | Default | Description |
| --- | --- | --- | --- |
| `includeDetails` | boolean | `true` | Fetch detailed fighter profiles or event fight cards during a refresh. It does not affect rankings. |
| `refreshRequestBudget` | integer | `45` | Maximum RapidAPI requests allowed in one refresh run. |
| `monthlyRequestLimit` | integer | `150` | Monthly RapidAPI request guard shared by refresh runs. |
| `detailRefreshHours` | integer | `168` | Minimum interval before an already detailed fighter or event is requested again. |

### Output

Every query item contains a `recordType` field so downstream workflows can distinguish the result category.

```json
{
  "recordType": "fighter",
  "id": "f4c49976c75c5ab2",
  "name": "Conor McGregor",
  "nickname": "The Notorious",
  "record": {
    "wins": 22,
    "losses": 7,
    "draws": 0
  },
  "physical": {
    "height": "5' 9\"",
    "weightLbs": 155,
    "reachIn": 74,
    "stance": "Southpaw"
  },
  "career": {
    "slpm": "5.27",
    "strAcc": "49%",
    "tdAvg": "0.66",
    "subAvg": "0.1"
  },
  "fights": []
}
```

Fighter records may include `record`, `physical`, `career`, and `fights` fields. The exact availability of individual statistics depends on the fighter profile returned by the source.

Event records contain the event identifier, name, date, location, and—when details are enabled—the event’s fight card and bout results.

Ranking records contain the ranking division and the provider’s champion, ranked fighters, and ranking metadata. The source response is preserved so useful provider-specific fields are not discarded.

### Recommended operating model

1. Store `RAPIDAPI_KEY` as an Apify Actor secret.
2. Create scheduled refresh tasks for fighters, events, and rankings.
3. Run public or application-facing tasks in `query` mode.
4. Use `includeDetails: true` selectively for important fighters and event cards.
5. Keep the monthly request limit below the actual RapidAPI subscription quota.

Refresh runs are rate-limited and maintain a persistent Actor dataset. Repeated detail refreshes are skipped while the configured detail interval is still valid, helping the free RapidAPI plans remain usable.

### Data providers

- **UFC Stats API** — UFC fighter listings, fighter profiles, career statistics, fight histories, event listings, event details, and fight cards.
- **MMAAPI** — UFC rankings and optional MMA calendar/tournament workflows.

The Actor does not expose the RapidAPI key to task users. Keep the key in Apify’s encrypted Actor secret configuration.

### Responsible use

Use the data for legitimate sports, editorial, analytical, and research purposes. You are responsible for complying with applicable laws, provider terms, and any restrictions related to redistribution or commercial use.

# Actor input Schema

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

Internal execution mode.

## `provider` (type: `string`):

Internal provider selection.

## `dataType` (type: `string`):

Dataset to return or update.

## `searchTerms` (type: `array`):

Fighter or event names. Empty returns the available collection.

## `refreshSearchTerms` (type: `array`):

Internal refresh setting.

## `fighterLetters` (type: `array`):

Internal refresh setting.

## `eventType` (type: `string`):

Limit events by whether they are upcoming or completed.

## `eventSource` (type: `string`):

Internal event source.

## `mmaTournamentId` (type: `string`):

Internal provider setting.

## `mmaSeasonId` (type: `string`):

Internal provider setting.

## `mmaCategoryId` (type: `string`):

Internal provider setting.

## `eventPage` (type: `integer`):

Internal provider setting.

## `division` (type: `string`):

Filter fighters or rankings by division.

## `gender` (type: `string`):

Filter rankings or fighters by gender where the provider supplies it.

## `fighterStatus` (type: `string`):

Filter fighters by current status.

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

Filter fighters by country of origin.

## `includeDetails` (type: `boolean`):

Internal refresh setting.

## `maxResults` (type: `integer`):

Maximum records to process or return.

## `refreshRequestBudget` (type: `integer`):

Internal quota setting.

## `monthlyRequestLimit` (type: `integer`):

Internal quota setting.

## `detailRefreshHours` (type: `integer`):

Internal refresh setting.

## `rapidApiHost` (type: `string`):

Internal provider setting.

## `ufcStatsHost` (type: `string`):

Internal provider setting.

## `endpointMap` (type: `object`):

Internal provider setting.

## Actor input object example

```json
{
  "mode": "query",
  "provider": "ufc-stats",
  "dataType": "events",
  "searchTerms": [],
  "refreshSearchTerms": [],
  "fighterLetters": [],
  "eventType": "all",
  "eventSource": "full-cards",
  "mmaTournamentId": "19906",
  "mmaSeasonId": "95578",
  "mmaCategoryId": "1708",
  "eventPage": 0,
  "division": "",
  "gender": "",
  "fighterStatus": "",
  "country": "",
  "includeDetails": true,
  "maxResults": 100,
  "refreshRequestBudget": 45,
  "monthlyRequestLimit": 150,
  "detailRefreshHours": 168,
  "rapidApiHost": "mmaapi.p.rapidapi.com",
  "ufcStatsHost": "ufc-stats3.p.rapidapi.com",
  "endpointMap": {}
}
```

# Actor output Schema

## `results` (type: `string`):

Structured fighter profiles, event cards, fight results, rankings, or refresh metadata produced by this run.

# 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("fetchfinch/ufc-stats-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("fetchfinch/ufc-stats-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 fetchfinch/ufc-stats-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,fetchfinch/ufc-stats-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/aaMvghT94SlPy0Mcq/builds/iA5GcXkTdRtJDUXyK/openapi.json