# UFC Weight-Class Rankings & Fight Card Results (`vexaloom-labs/ufc-weight-class-rankings-and-fight-card-results`) Actor

Browse UFC weight-class rankings, look up a fighter by name, or fetch a season's events with fight-by-fight results, round, time, and method of finish for each completed bout.

- **URL**: https://apify.com/vexaloom-labs/ufc-weight-class-rankings-and-fight-card-results.md
- **Developed by:** [vexaloom-labs](https://apify.com/vexaloom-labs) (community)
- **Categories:** Automation, News, Developer tools
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
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 Weight-Class Rankings & Fight Card Results

Pull UFC data three ways: current weight-class rankings, a fighter looked up by name, or a season's worth of events with each fight's result. No login or API key needed.

### What this actor does

- **Weight-class rankings** — champion plus top-15 ranked fighters for any of the 13 official UFC rankings (11 weight classes plus men's/women's pound-for-pound)
- **Fighter search** — look up a fighter by name and get their bio: height, weight, reach, stance, age, and record
- **Events by season** — every UFC event scheduled or completed in a given year, each with its fight card; completed bouts include the round, time, and method of finish
- **Empty fields are omitted** — a field not available for a given fighter or fight (e.g. no nickname) is left out rather than returned as null

### Output per fighter (`mode: "topRanked"`)

- `recordType` — always `fighter`
- `athleteId`, `name`, `nickname`
- `weightClass`, `rank` — the division and current rank position
- `record`, `wins`, `losses`, `draws`
- `height`, `weight`, `reach`, `stance`, `fightingStyle`, `age`, `dateOfBirth` — included whenever the fighter's own profile data loads successfully (the normal case)
- `rankTrend` — change since the last ranking update; only appears on the rare fighter whose profile data couldn't be loaded, since the rank list itself (rather than the profile) is the source for this field
- `isChampion`, `titleDefenses` — set for the division's current champion
- `country`
- `headshotUrl`, `espnProfileUrl`
- `active`
- `sourceUrl`, `scrapedAt`

### Output per fighter (`mode: "searchFighters"`)

- `recordType` — always `fighter`
- `athleteId`, `name`, `nickname`
- `weightClass`, `height`, `weight`, `reach`, `stance`, `fightingStyle`, `age`, `dateOfBirth`
- `country`, `record`, `wins`, `losses`, `draws`
- `headshotUrl`, `espnProfileUrl`
- `active`
- `sourceUrl`, `scrapedAt`
- `rank`, `rankTrend`, `isChampion`, `titleDefenses` — only when a name doesn't match ESPN's search index and the actor falls back to scanning the current rankings for a substring match instead

### Output per event (`mode: "byEvent"`)

- `recordType` — always `event`
- `eventId`, `eventName`, `shortName`
- `date`, `venue`, `location`
- `fightCount`, `fights` — array of fight objects for the card:
  - `weightClass` — division abbreviation for that bout
  - `fighter1`, `fighter1Record`, `fighter2`, `fighter2Record`
  - `winner`, `round`, `time`, `method` — only present once the bout has actually concluded; a not-yet-fought bout on a future or in-progress event only has `fighter1`/`fighter2`
- `espnEventUrl`
- `sourceUrl`, `scrapedAt`

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | string (select) | `topRanked` | `topRanked`, `byEvent`, or `searchFighters` |
| `weightClass` | string (select) | `Lightweight` | Division to rank (mode=`topRanked`) |
| `searchQuery` | string | – | Fighter name to search for, e.g. `Jon Jones` (mode=`searchFighters`) |
| `season` | integer | – | Year to fetch events for, e.g. `2024`; uses the current year if left blank (mode=`byEvent`) |
| `maxItems` | integer | `50` | Maximum number of records to return (1–500) |

#### Example: top-15 lightweight rankings

```json
{
  "mode": "topRanked",
  "weightClass": "Lightweight"
}
```

#### Example: look up a fighter by name

```json
{
  "mode": "searchFighters",
  "searchQuery": "Conor McGregor"
}
```

#### Example: completed events for a season

```json
{
  "mode": "byEvent",
  "season": 2024,
  "maxItems": 50
}
```

### Use cases

- **Fantasy MMA and betting models** — pull current rankings and recent fight outcomes as model inputs
- **Fighter research** — look up a specific fighter's bio stats and record before a matchup
- **Historical analysis** — fetch a full season's events to study methods of finish and title defenses over time
- **Content and media** — build rankings widgets or fight-result recaps from live data

### FAQ

**Does this need an API key or login?**
No — rankings, fighter search, and event results are all read without authentication.

**How many fighters are in each weight-class ranking?**
Typically 16 — the current champion plus the top 15 contenders, matching the official UFC rankings.

**Can I get historical event results?**
Yes — set `mode` to `byEvent` and `season` to the year you want, e.g. `2019` through the current year. The current (or a future) season year may also include events that haven't happened yet; those come back with fighter names but no winner, round, or method until the bout concludes.

**Does this include per-fight strike or takedown statistics?**
No — fight records cover the result (winner, round, time, method), not round-by-round strike or grappling statistics.

**Why do fighter records differ between `topRanked` and `searchFighters`?**
Both normally pull the fighter's own profile, so most fields (height, weight, reach, stance, age, record) match. `topRanked` additionally adds `rank`, `isChampion`, and `titleDefenses` from the rankings list, and falls back to rank-list-only data (losing the physical stats but gaining `rankTrend`) on the rare fighter whose profile fails to load.

**How current is the data?**
Rankings and event results reflect whatever is currently published; results for an event typically update shortly after each fight concludes.

**Is this affiliated with the UFC or ESPN?**
No. This is an independent actor that reads publicly available MMA data; it is not operated by or affiliated with UFC or ESPN.

# Actor input Schema

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

What to fetch from the ESPN UFC API.

## `weightClass` (type: `string`):

Filter rankings by weight class.

## `searchQuery` (type: `string`):

Fighter name to search for (e.g. 'Jon Jones', 'Conor McGregor').

## `season` (type: `integer`):

Year to fetch completed UFC events for (e.g. 2024, 2025). Defaults to current year.

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

Maximum number of records to return.

## Actor input object example

```json
{
  "mode": "topRanked",
  "weightClass": "Lightweight",
  "maxItems": 50
}
```

# Actor output Schema

## `records` (type: `string`):

Dataset containing all scraped UFC fighter and event records.

# 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 = {
    "mode": "topRanked",
    "weightClass": "Lightweight",
    "maxItems": 50
};

// Run the Actor and wait for it to finish
const run = await client.actor("vexaloom-labs/ufc-weight-class-rankings-and-fight-card-results").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 = {
    "mode": "topRanked",
    "weightClass": "Lightweight",
    "maxItems": 50,
}

# Run the Actor and wait for it to finish
run = client.actor("vexaloom-labs/ufc-weight-class-rankings-and-fight-card-results").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 '{
  "mode": "topRanked",
  "weightClass": "Lightweight",
  "maxItems": 50
}' |
apify call vexaloom-labs/ufc-weight-class-rankings-and-fight-card-results --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,vexaloom-labs/ufc-weight-class-rankings-and-fight-card-results"
        }
    }
}
```

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/jAMbb3LF9jvgsZOdo/builds/sBjm6jLYzEqZWvTIB/openapi.json