---
title: "A year in review"
method: GET
path: "/v1/stats/years/{year}"
tags: ["Stats"]
---

# A year in review

`GET /v1/stats/years/{year}`

## Request

- Base URL: `https://api.ufcalendar.com`
- URL: `https://api.ufcalendar.com/v1/stats/years/{year}`
- Auth: HTTP bearer

One calendar year (UTC) of one promotion — or, without `org`, of every covered promotion together (never a promotion the API does not cover) — in numbers, over completed bouts of non-cancelled events: `events_completed`, `title_fights`, `methods` (`ko`, `sub`, `dec`, `other`, `total`), `divisions` (weight classes with 10+ bouts, highest finish rate first, up to 14), `fastest_finishes` (up to 8 round-1 KO/TKO/submissions, `seconds` and `time`, winner and loser), `upsets` (up to 8 wins with the lowest pre-fight UFCalendar Power Index probability, `win_probability`), `climbers` (up to 8 fighters with the biggest Power Index gain over the year, `gain` in rating points), `busiest` (up to 8 fighters by bouts, with wins), `orgs` (events and completed bouts per promotion), `countries` (host countries by events, up to 12) and `judges` (the 5 judges on the most commission-scored bouts). `orgs_scope` names the promotions counted. `year` runs from 1993 to the current year; anything else 404s. Unknown `org` 400s `invalid_org`. Refreshed every 10 minutes.

## Path parameters

- `year` integer, required

## Query parameters

- `org` 'ufc' | 'pfl' | 'oktagon' | 'bkfc' | 'rizin'

## Response `200`

The year in numbers

- YearStatsResponse
  - `data` YearStats, required
    - `year` integer, required
    - `orgs_scope` string[], required: Promotions counted.
    - `events_completed` integer, required
    - `title_fights` integer, required
    - `methods` object, required
      - `ko` integer, required
      - `sub` integer, required
      - `dec` integer, required
      - `other` integer, required
      - `total` integer, required
    - `divisions` object[], required: Weight classes with 10+ bouts, highest finish rate first, up to 14.
      - `weight_class` string, required
      - `fights` integer, required
      - `ko` integer, required
      - `sub` integer, required
    - `fastest_finishes` object[], required: Up to 8 round-1 KO/TKO/submissions.
      - `fight_id` integer, required
      - `seconds` integer, required
      - `time` string, required
      - `method` string, nullable, required
      - `event` object, required
        - `slug` string, required
        - `title` string, required
        - `starts_at` string, date-time, nullable, required
      - `winner` object, required
        - `id` integer, required
        - `name` string, nullable, required
        - `slug` string, nullable, required
      - `loser` object, required
        - `id` integer, nullable, required
        - `name` string, nullable, required
        - `slug` string, nullable, required
    - `upsets` object[], required: Up to 8.
      - `fight_id` integer, required
      - `win_probability` number, required: The winner's pre-fight Power Index probability.
      - `winner` object, nullable, required: Fighter link on the year-in-review blocks (`name` is `""` when unknown).
        - `id` integer, required
        - `name` string, required
        - `slug` string, nullable, required
      - `opponent` object, nullable, required: Fighter link on the year-in-review blocks (`name` is `""` when unknown).
        - `id` integer, required
        - `name` string, required
        - `slug` string, nullable, required
      - `event` object, required
        - `slug` string, required
        - `title` string, required
        - `starts_at` string, date-time, nullable, required
    - `climbers` object[], required: Up to 8.
      - `fighter` object, nullable, required: Fighter link on the year-in-review blocks (`name` is `""` when unknown).
        - `id` integer, required
        - `name` string, required
        - `slug` string, nullable, required
      - `fights` integer, required
      - `gain` integer, required: Power Index points gained over the year.
    - `busiest` object[], required: Up to 8.
      - `fighter` object, nullable, required: Fighter link on the year-in-review blocks (`name` is `""` when unknown).
        - `id` integer, required
        - `name` string, required
        - `slug` string, nullable, required
      - `fights` integer, required
      - `wins` integer, required
    - `orgs` object[], required
      - `slug` string, required
      - `name` string, required
      - `events` integer, required
      - `fights` integer, required
    - `countries` object[], required: Host countries by events, up to 12.
      - `country` string, required
      - `events` integer, required
    - `judges` object[], required: The 5 judges on the most commission-scored bouts.
      - `judge_id` integer, required
      - `name` string, required
      - `fights` integer, required
  - `meta` object, required
    - `org` string, nullable, required: The `org=` filter, null for every covered promotion.
    - `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`).
- `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)