---
title: "Ranking history"
method: GET
path: "/v1/fighters/{idOrSlug}/rankings"
tags: ["Fighters"]
---

# Ranking history

`GET /v1/fighters/{idOrSlug}/rankings`

## Request

- Base URL: `https://api.ufcalendar.com`
- URL: `https://api.ufcalendar.com/v1/fighters/{idOrSlug}/rankings`
- Auth: HTTP bearer

Official-board rows over time (`org`, `board` in the public vocabulary — `official` / `meta` — `division` slug, `snapshot_date`, `rank`, `is_champion`), newest snapshot first. Rank 0 = champion; a snapshot is valid until superseded. Cursor-paginated since 2026-09-24 (`limit` 1–500, default 100) — long careers exceed the old silent 500-row cap.

## Path parameters

- `idOrSlug` string, required

## Query parameters

- `cursor` string
- `limit` integer

## Response `200`

Ranking rows

- FighterRankingsResponse: Newest snapshot first.
  - `data` FighterRankingRow[], required
    - `org` string, required
    - `board` 'official' | 'meta', required: `official` for every org (for UFC that is the media-panel vote ufc.com publishes); UFC additionally has `meta`.
    - `division` string, required: Division slug (`lightweight`, `womens-strawweight`, `mens-pound-for-pound`).
    - `snapshot_date` string, date, required
    - `rank` integer, required: 0 = champion.
    - `is_champion` boolean, required
  - `meta` object, required
    - `pagination` Pagination, required
      - `next_cursor` string, nullable, required: Opaque; pass as `?cursor=`. Null on the last page.
      - `has_more` boolean, required
      - `limit` integer, required: The page size actually applied (out-of-range `limit` values are clamped).
    - `note` string
    - `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_cursor`).
- `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)