---
title: "Who should this fighter fight next"
method: GET
path: "/v1/matchmaker/next/{fighter}"
tags: ["Matchmaker"]
---

# Who should this fighter fight next

`GET /v1/matchmaker/next/{fighter}`

## Request

- Base URL: `https://api.ufcalendar.com`
- URL: `https://api.ufcalendar.com/v1/matchmaker/next/{fighter}`
- Auth: HTTP bearer

One fighter's most sensible next opponents by UFCalendar's matchmaker: the same engine and candidate pool as the board (their division's ladder plus the promotion's active Power Index fighters), every pairing scored, best first. The promotion and division come from the fighter's most recent bouts in a covered MMA promotion (404 `not_found` when there is none, or the division has no pool); a renamed slug 308-redirects. The fighter is scored as free even when booked — the question is who comes after that — and `booked_next` names the bout already booked (opponent + event), or null. Opponents already booked against them are left out.

`subject` carries the corner fields plus `days_since_last`; each suggestion has `opponent`, `win_probability_subject` (from the two Power Index ratings), `score` (0–100) and `tags` (same vocabulary as the board). Computed WITHOUT the website's style-clash (Fight DNA) factor, so scores can differ slightly from ufcalendar.com; probabilities are model output for information only.

## Path parameters

- `fighter` string, required

## Query parameters

- `limit` integer

## Response `200`

Suggested next opponents

- WhosNextResponse
  - `data` WhosNext, required
    - `subject` object, required
      - `id` integer, required
      - `slug` string, required
      - `name` string, required
      - `nationality` string, nullable, required
      - `rank` integer, nullable, required
      - `power_index` integer, nullable, required
      - `streak` integer, required
      - `booked` boolean, required
      - `days_since_last` integer, nullable, required: Days since their last rated bout; null when unrated.
    - `org` string, required
    - `division` string, required
    - `suggestions` object[], required: Best first.
      - `opponent` MatchmakerCorner, required
        - `id` integer, required
        - `slug` string, required
        - `name` string, required
        - `nationality` string, nullable, required
        - `rank` integer, nullable, required: Official rank: 0 = champion, null = unranked.
        - `power_index` integer, nullable, required: Rounded Power Index rating; null when unrated.
        - `streak` integer, required: Signed: +3 = three straight wins, -2 = two straight losses.
        - `booked` boolean, required: Already booked against someone else on an upcoming card.
      - `win_probability_subject` number, required
      - `score` number, required: 0–100.
      - `tags` MatchmakerTag[], required
        - `kind` 'title' | 'eliminator' | 'coinFlip' | 'bothStreaking' | 'finishers' | 'trilogyDecider' | 'unfinishedBusiness' | 'rematch' | 'booked' | 'unrankedGem' | 'bounceBack' | 'steppingUp' | 'bothDue' | 'styleClash', required: Tag vocabulary; `styleClash` never fires on the API (no Fight DNA).
        - `a` integer: `bothStreaking`: corner a's streak.
        - `b` integer: `bothStreaking`: corner b's streak.
        - `pct` integer: `finishers`: average recent finish rate, whole percent.
        - `wins` integer: `trilogyDecider`: wins each.
        - `aWins` integer: `rematch`: a's wins in the series.
        - `bWins` integer: `rematch`: b's wins in the series.
    - `booked_next` object, nullable, required: The bout already booked for the subject, or null.
      - `opponent` object, nullable, required
        - `id` integer, required
        - `slug` string, required
        - `name` string, required
      - `event` object, required
        - `id` integer, required
        - `slug` string, required
        - `title` string, required
        - `org` string, required
        - `starts_at` string, date-time, nullable, required
    - `rankings_date` string, date, nullable, required: The ladder snapshot used; null when the promotion has no current ladder.
  - `meta` object, required
    - `note` string, required
    - `ignored_params` string[]: Present only when the request carried query parameters this endpoint does not take — they were ignored. Same list as the `X-UFCalendar-Ignored-Params` header. Sorted, unique.

## Other responses

- `304`: Not Modified — `If-None-Match` matched the current weak `ETag`. Empty body.
- `308`: The slug is a retired alias (the event or fighter was renamed). Follow `Location` to the canonical URL; the numeric-id form never redirects.
- `400`: Invalid input (`invalid_query`).
- `401`: Missing/invalid API key (`unauthorized`).
- `403`: No active plan on the key's account (`subscription_required`) — choose a plan or start the free 1-day trial at https://www.ufcalendar.com/account/api.
- `404`: Not found (`not_found`; staged-org data 404s until the org is promoted).
- `429`: Rate limited (`rate_limited`) or monthly quota reached (`quota_exceeded`). Honor `Retry-After`.
- `500`: Something broke on our side (`internal_error`). It has been logged under the `request_id`.

---

[API](https://skmtc.dev/ufcalendar/apis/ufcalendar-fight-api.md) · [All operations](https://skmtc.dev/ufcalendar/apis/ufcalendar-fight-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ufcalendar/apis/ufcalendar-fight-api/revisions/9623cc8fb70b?raw)