---
title: "Preview a hypothetical Ultimate League rank"
method: POST
path: "/api/data/hypothetical-rank"
tags: ["Data"]
---

# Preview a hypothetical Ultimate League rank

`POST /api/data/hypothetical-rank`

Calculates where a hypothetical biological age result would rank in the current Ultimate League field. Use `pheno` for an Amateur Pheno Age preview and `bortz` for a Pro Bortz Age preview.

## Request body

- HypotheticalRankRequest — Inputs for previewing where a hypothetical biological age result would rank in the current Ultimate League field.
  - `calculator` 'pheno' | 'bortz', required — Biological aging clock to preview: `pheno` for Amateur or `bortz` for Pro.
  - `chronologicalAge` number, double — Chronological age in years at the measurement date.
  - `biologicalAge` number, double — Biological age result in years from the selected clock.
  - `birthYear` integer — Birth year used for tie-breaking against the current field.
  - `birthMonth` integer — Birth month used for tie-breaking against the current field.
  - `birthDay` integer — Birth day used for tie-breaking against the current field.

## Response `200`

Hypothetical rank, field sizes, signed age difference, and nearby rows.

- HypotheticalRankResult — Result returned by a hypothetical Ultimate League rank preview.
  - `rank` integer — One-based rank the hypothetical result would receive in the selected field.
  - `fieldSize` integer — Field size including the hypothetical result.
  - `currentFieldSize` integer — Current field size excluding the hypothetical result.
  - `leagueName` string, nullable — League used for the preview. Currently Ultimate League.
  - `category` string, nullable — Track used for the preview, either Pro or Amateur.
  - `ageDifference` number, double — Signed biological age difference, calculated as biological age minus chronological age. Lower and more negative values rank higher within the same track.
  - `nearby` HypotheticalRankNeighbor[], nullable — Nearby athletes around the hypothetical result after sorting.
    - `rank` integer — One-based rank in the preview field.
    - `name` string, nullable — Athlete display name, or the hypothetical row label.
    - `category` string, nullable — Track for the row, either Pro or Amateur.
    - `ageDifference` number, double — Signed age difference used for sorting.
    - `isHypothetical` boolean — True for the submitted hypothetical result row.

## Other responses

- `400` — Invalid request body, unsupported calculator, invalid date of birth, or out-of-range age value.

---

[API](https://skmtc.dev/longevityworldcup/apis/longevity-world-cup-public-api.md) · [All operations](https://skmtc.dev/longevityworldcup/apis/longevity-world-cup-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/longevityworldcup/longevity-world-cup-public-api/revisions/06294996061a/schema)