---
title: "Official board (point-in-time)"
method: GET
path: "/v1/rankings/{org}"
tags: ["Rankings"]
---

# Official board (point-in-time)

`GET /v1/rankings/{org}`

## Request

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

**The time machine**: pass `?date=YYYY-MM-DD` for the board as it stood on any date (UFC official back to 2013, 543 snapshots). A snapshot is valid until superseded. Rank 0 = champion; P4P has no rank 0.

Every entry carries `movement` against the previous snapshot of the same board (previous rank minus current rank: positive moved up, 0 held, null when not on the previous board) and `is_new` (true when there was a previous snapshot and the fighter was not ranked in that division on it), plus `nationality` and `country_code` (ISO-3166 alpha-2). Fighters are matched by division + name, so a fighter moving divisions reads as new. `meta.previous_snapshot_date` / `meta.next_snapshot_date` name the neighbouring snapshots (null at either end) — pass one as `date` to step through history.

## Path parameters

- `org` 'ufc' | 'pfl' | 'oktagon' | 'bkfc', required

## Query parameters

- `date` string, date
- `board` 'official' | 'meta': `official` for every org (for UFC that is the media-panel vote ufc.com publishes); UFC additionally has `meta`.

## Response `200`

Board grouped by division

- RankingsBoardResponse
  - `data` RankingsBoardSnapshot, 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`.
    - `snapshot_date` string, date, required: The snapshot in force on the requested date.
    - `divisions` RankingsDivision[], required
      - `division` string, required: Division slug.
      - `entries` RankingEntry[], required
        - `rank` integer, required: 0 = champion.
        - `is_champion` boolean, required
        - `fighter_id` integer, nullable, required
        - `fighter_slug` string, nullable, required
        - `name` string, required
        - `nationality` string, nullable, required: Country NAME as the source spells it.
        - `country_code` string, nullable, required: ISO 3166-1 alpha-2 derived from `nationality`.
        - `fighter` RankedFighterRef, required
          - `id` integer, required
          - `slug` string, nullable, required
          - `name` string, required
        - `movement` integer, nullable, required: Previous rank minus current rank: positive = moved up, 0 = held, null = not on the previous board (or no previous snapshot).
        - `is_new` boolean, required: true when a previous snapshot exists and this fighter was not ranked in this division on it.
  - `meta` object, required
    - `previous_snapshot_date` string, date, nullable, required: The snapshot before this one on the same board; null at the start of history.
    - `next_snapshot_date` string, date, nullable, required: The snapshot after this one; null when this is the current board.
    - `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.
- `400`: Invalid input (`invalid_date`). Dates must be real calendar days (`2026-02-30` is `invalid_date`).
- `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)