---
title: "One stat leaderboard"
method: GET
path: "/v1/stats/leaders"
tags: ["Stats"]
---

# One stat leaderboard

`GET /v1/stats/leaders`

## Request

- Base URL: `https://api.ufcalendar.com`
- URL: `https://api.ufcalendar.com/v1/stats/leaders`
- Auth: HTTP bearer

One board from UFCalendar's Record Book rollup (rebuilt daily) for ONE promotion — `org` is required; there is no cross-promotion board on the API. `metric` picks the board; its `scope` decides what a row is: `career` rows are fighters, `single_fight` and `round` rows are PERFORMANCES (one fighter can hold several; `fight` names the bout and opponent, `round_number` the round), `event` rows are CARDS (`event`, no fighter), `division` rows are WEIGHT CLASSES (`division`, no fighter). `value` is in `meta.metric.unit` (`rate` is a 0–1 fraction; `seconds`, `per_minute`, `per_15_minutes` as named); `value_secondary` is the denominator or context named by `meta.metric.secondary` (e.g. attempts behind an accuracy, the round of a fastest finish); `sample_n` is the bouts (or fighters) behind the value. `direction` is the ranking order, not a verdict. `rank` is the rollup's own position; equal values are a tie — `display_rank` and `tied` say so. Narrow with `division`, `country` (ISO-2, fighters of that nationality; population `all` only — combining it with `population=active` 400s `invalid_filter`) or `population=active` (a bout in the last ~18 months). Boards need a minimum sample, so a narrow slice can 404. Errors: `invalid_org`, `invalid_metric`, `invalid_division`, `invalid_country`, `invalid_population`, `invalid_filter`.

## Query parameters

- `org` 'ufc' | 'pfl' | 'oktagon' | 'bkfc' | 'rizin', required
- `metric` 'total_fights' | 'wins' | 'decision_wins' | 'title_fight_wins' | 'bonuses' | 'finishes' | 'win_streak' | 'total_fight_seconds' | 'avg_fight_seconds_short' | 'avg_fight_seconds_long' | 'control_time_sec' | 'control_time_pct' | 'sig_strikes_landed' | 'total_strikes_landed' | 'slpm' | 'sapm' | 'striking_differential' | 'sig_strike_accuracy' | 'sig_strike_defense' | 'knockdowns' | 'knockdowns_per_15' | 'knockouts' | 'takedowns_landed' | 'td_avg' | 'takedown_accuracy' | 'takedown_defense' | 'submission_attempts' | 'sub_avg_per_15' | 'submissions' | 'fastest_finish' | 'fastest_knockout' | 'fastest_submission' | 'longest_fight_seconds' | 'most_sig_strikes_fight' | 'most_takedowns_fight' | 'most_knockdowns_fight' | 'longest_control_fight' | 'most_sig_strikes_round' | 'most_takedowns_round' | 'most_knockdowns_round' | 'most_finishes_event' | 'most_knockouts_event' | 'shortest_card_seconds' | 'finish_rate' | 'ko_rate' | 'sub_rate' | 'decision_rate' | 'avg_fight_seconds', required
- `division` 'strawweight' | 'flyweight' | 'bantamweight' | 'featherweight' | 'lightweight' | 'welterweight' | 'super-welterweight' | 'middleweight' | 'light-heavyweight' | 'heavyweight' | 'super-heavyweight' | 'womens-strawweight' | 'womens-flyweight' | 'womens-bantamweight' | 'womens-featherweight' | 'atomweight' | 'ironweight'
- `population` 'all' | 'active'
- `country` string
- `limit` integer

## Response `200`

Board rows, best first

- LeaderboardResponse: Best first (`meta.metric.direction`). `meta.note` explains non-fighter rows.
  - `data` LeaderboardRow[], required
    - `rank` integer, required: The rollup's own position.
    - `value` number, required: In `meta.metric.unit`.
    - `value_secondary` number, nullable, required: Denominator or context named by `meta.metric.secondary`.
    - `sample_n` integer, required: Bouts (or fighters) behind the value.
    - `fighter` object, nullable, required: Null on `event` and `division` boards.
      - `id` integer, required
      - `slug` string, nullable, required
      - `name` string, nullable, required
      - `nationality` string, nullable, required
    - `division` string, nullable, required: Set on `division` boards and on any board narrowed with `division=`.
    - `round_number` integer, nullable, required: `round` boards only.
    - `fight` object, nullable, required: `single_fight` / `round` boards: the performance's bout.
      - `id` integer, required
      - `event` object, nullable, required
        - `id` integer, required
        - `slug` string, nullable, required
        - `title` string, nullable, required
        - `starts_at` string, date-time, nullable, required
      - `opponent` object, nullable, required
        - `id` integer, required
        - `slug` string, nullable, required
        - `name` string, nullable, required
    - `event` object, nullable, required: `event` boards: the card.
      - `id` integer, required
      - `slug` string, nullable, required
      - `title` string, nullable, required
      - `starts_at` string, date-time, nullable, required
    - `display_rank` integer, required: First rank of the tie group.
    - `tied` boolean, required
  - `meta` object, required
    - `org` string, required
    - `metric` MetricMeta, required
      - `slug` 'total_fights' | 'wins' | 'decision_wins' | 'title_fight_wins' | 'bonuses' | 'finishes' | 'win_streak' | 'total_fight_seconds' | 'avg_fight_seconds_short' | 'avg_fight_seconds_long' | 'control_time_sec' | 'control_time_pct' | 'sig_strikes_landed' | 'total_strikes_landed' | 'slpm' | 'sapm' | 'striking_differential' | 'sig_strike_accuracy' | 'sig_strike_defense' | 'knockdowns' | 'knockdowns_per_15' | 'knockouts' | 'takedowns_landed' | 'td_avg' | 'takedown_accuracy' | 'takedown_defense' | 'submission_attempts' | 'sub_avg_per_15' | 'submissions' | 'fastest_finish' | 'fastest_knockout' | 'fastest_submission' | 'longest_fight_seconds' | 'most_sig_strikes_fight' | 'most_takedowns_fight' | 'most_knockdowns_fight' | 'longest_control_fight' | 'most_sig_strikes_round' | 'most_takedowns_round' | 'most_knockdowns_round' | 'most_finishes_event' | 'most_knockouts_event' | 'shortest_card_seconds' | 'finish_rate' | 'ko_rate' | 'sub_rate' | 'decision_rate' | 'avg_fight_seconds', required: Board metric slug.
      - `scope` 'career' | 'single_fight' | 'round' | 'division' | 'event', required: What a board row is: `career` = a fighter, `single_fight` / `round` = a performance, `event` = a card, `division` = a weight class.
      - `category` 'fights' | 'time' | 'striking' | 'grappling' | 'records', required: Record Book category.
      - `direction` 'asc' | 'desc', required: Ranking order, not a verdict.
      - `unit` 'count' | 'seconds' | 'minutes' | 'rate' | 'per_minute' | 'per_15_minutes', required: `rate` is a 0–1 fraction.
      - `has_secondary` boolean, required
      - `secondary` object, nullable, required
        - `unit` 'count' | 'seconds' | 'minutes' | 'rate' | 'per_minute' | 'per_15_minutes', required: `rate` is a 0–1 fraction.
        - `label` string, required: snake_case name of what `value_secondary` holds (`attempted`, `round`, `fights`, …).
    - `division` string, nullable, required: API division slug as passed.
    - `population` 'all' | 'active', required: `active` = a bout in the last ~18 months.
    - `country` string, nullable, required
    - `computed_at` string, date-time, nullable, required: When the rollup was built.
    - `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.
- `400`: Invalid input (`invalid_org`, `invalid_metric`, `invalid_division`, `invalid_population`, `invalid_country`, `invalid_filter`).
- `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)