---
title: "The Record Book"
method: GET
path: "/v1/stats/record-book"
tags: ["Stats"]
---

# The Record Book

`GET /v1/stats/record-book`

## Request

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

Every leaderboard's top rows for ONE promotion in one call — `org` is required — grouped by category (`fights`, `time`, `striking`, `grappling`, `records`): `data` is `[{ category, boards: [{ metric, rows }] }]`, rows exactly as on `/v1/stats/leaders`. `top` rows per board (default 10, max 25). Same `division` / `country` / `population` narrowing as `/v1/stats/leaders`, plus `scope` for one kind of board (`career`, `single_fight`, `round`, `division`, `event`). A board appears only when it has at least 3 rows (or `top`, if smaller); inside one `division`, the division-ranking boards are left out. An empty slice returns `[]` with `meta.note`.

## Query parameters

- `org` 'ufc' | 'pfl' | 'oktagon' | 'bkfc' | 'rizin', 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
- `scope` 'career' | 'single_fight' | 'round' | 'division' | 'event'
- `top` integer

## Response `200`

Boards grouped by category

- RecordBookResponse: Grouped by category in registry order; `[]` with `meta.note` on an empty slice.
  - `data` RecordBookSection[], required
    - `category` 'fights' | 'time' | 'striking' | 'grappling' | 'records', required: Record Book category.
    - `boards` object[], 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`, …).
      - `rows` 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
    - `division` string, nullable, required
    - `population` 'all' | 'active', required: `active` = a bout in the last ~18 months.
    - `country` string, nullable, required
    - `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.
    - `top` integer, required: Rows per board.
    - `computed_at` string, date-time, nullable, required: Null when the slice is empty.
    - `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.
- `400`: Invalid input (`invalid_org`, `invalid_scope`, `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)