---
title: "Retrieve leaderboard results"
method: GET
path: "/leaderboard"
tags: ["Leaderboard"]
---

# Retrieve leaderboard results

`GET /leaderboard`

Retrieves leaderboard results.

## Query parameters

- `score_set` string, required
- `category` string
- `chapter` string
- `entry` string
- `tag` string
- `archived` 'only' | 'all' | 'none'
- `page` string
- `per_page` string
- `order` 'category' | 'chapter' | 'division' | 'link' | 'slug' | 'status' | 'submitted' | 'auto_score' | 'title' | 'tags'
- `dir` 'asc' | 'desc'

## Headers

- `Accept` 'application/vnd.Creative Force.v2.3+json' | 'application/vnd.Creative Force.v2.3+xml', required
- `x-api-language` string[]

## Response `200`

Leaderboard results retrieved.

- LeaderboardList — Pagination envelope returned by every list endpoint. Wraps the result set with positional fields (`current_page`, `from`, `to`, `total`) and navigation URLs (`first_page_url`, `last_page_url`, `next_page_url`, `prev_page_url`) for traversing the full list. The records themselves are returned in a sibling `data` array supplied by the wrapping schema.
  - `current_page` integer — Number of the page returned by this response. The first page is `1`.
  - `first_page_url` string, uri — URL of the first page in the result set.
  - `from` integer — Position of the first record on this page within the full result set. The first record is at position `1`.
  - `last_page` integer — Number of the last page. Equals the total number of pages.
  - `last_page_url` string, uri — URL of the last page in the result set.
  - `next_page_url` string — URL of the next page in the result set. Empty string when the current page is the last page.
  - `path` string, uri — Canonical URL of the endpoint, without query parameters.
  - `per_page` integer — Maximum number of records returned per page.
  - `prev_page_url` string — URL of the previous page in the result set. Empty string when the current page is the first page.
  - `to` integer — Position of the last record on this page within the full result set.
  - `total` integer — Total number of records across all pages.
  - `data` Leaderboard[] — Leaderboard rows for the current page.
    - `slug` string — Short URL-safe identifier for the entry.
    - `title` string — Title of the entry as submitted by the entrant.
    - `tags` string — Comma-separated tags applied to the entry. Empty string when no tags are applied.
    - `category` object, nullable — Category the entry was submitted to. `null` when the entry is not assigned to a category.
      - `slug` string — Short URL-safe identifier for the category.
      - `link` string, uri — Canonical URL for the category resource.
      - `name` object — Map keyed by locale code (for example, `en_GB` or `fr_FR`). Keys are drawn from the languages enabled on the account. Values are the translated string.
    - `chapter` object, nullable — Chapter the entry belongs to. `null` when the entry is not assigned to a chapter.
      - `slug` string — Short URL-safe identifier for the chapter.
      - `link` string, uri — Canonical URL for the chapter resource.
      - `name` object — Map keyed by locale code (for example, `en_GB` or `fr_FR`). Keys are drawn from the languages enabled on the account. Values are the translated string.
    - `division` string, nullable — Division the entry is assigned to. `null` when the entry is not assigned to a division.
    - `submitted` string, date-time — Date and time the entry was submitted, in ISO 8601 format.
    - `auto_score` number, nullable — Automated score calculated from the auto-scored fields of the entry. `null` when the entry has no auto-scored fields.
    - `status` string — Submission status of the entry.
    - `grant_status` string, nullable — Grant status of the entry. `null` unless grants are enabled on the account.
    - `link` string, uri — Canonical URL for the entry resource.
    - `scores` union — Scores for the entry under the selected score set. The shape depends on the mode of the score set: `voting`, `qualifying`, `vip_judging`, or `top_pick`.
      - object — Scores returned for a `voting` score set.
        - `total_votes` integer — Total number of votes the entry received.
      - object — Scores returned for a `qualifying` score set.
        - `final_decision` 'pass' | 'fail' | 'unsure', nullable — Qualifying decision recorded for the entry. `null` when no decision has been recorded.
      - object — Scores returned for a `vip_judging` score set.
        - `total_score` object — Aggregated score across all criteria.
          - `value` number — Total score awarded across all criteria.
          - `max_score` union — Maximum achievable total score. Empty string when no maximum is configured.
            - integer
            - string
          - `final_score` string — Formatted total score, such as `8/10`. Returns `-` when no maximum is configured.
        - `criteria` object[] — Per-criterion scores making up the total.
          - `name` object — Map keyed by locale code (for example, `en_GB` or `fr_FR`). Keys are drawn from the languages enabled on the account. Values are the translated string.
          - `value` number — Score awarded for the criterion.
          - `max_score` integer — Maximum achievable score for the criterion.
          - `final_score` string — Formatted criterion score, such as `4/5`.
          - `weight` number — Relative weight of the criterion in the total.
      - object — Scores returned for a `top_pick` score set. Keyed by preference position (for example, `preference_1`), with the number of judges who ranked the entry at that position.
  - `score_set` object — Score set the leaderboard is calculated for.
    - `slug` string — Short URL-safe identifier for the score set.
    - `name` object — Map keyed by locale code (for example, `en_GB` or `fr_FR`). Keys are drawn from the languages enabled on the account. Values are the translated string.
    - `mode` 'voting' | 'qualifying' | 'vip_judging' | 'top_pick' — Scoring mode of the score set. Determines the shape of each row's `scores` object.
    - `form` object — Form the score set scores entries from.
      - `slug` string — Short URL-safe identifier for the form.
      - `link` string, uri — Canonical URL for the form resource.
      - `name` object — Map keyed by locale code (for example, `en_GB` or `fr_FR`). Keys are drawn from the languages enabled on the account. Values are the translated string.
  - `season` object — Season the leaderboard belongs to.
    - `slug` string — Short URL-safe identifier for the season.
    - `link` string, uri — Canonical URL for the season resource.
    - `name` object — Map keyed by locale code (for example, `en_GB` or `fr_FR`). Keys are drawn from the languages enabled on the account. Values are the translated string.

## Other responses

- `400` — Request was rejected before the endpoint could process it. Common causes: invalid `Accept` header, unsupported `x-api-language` code, empty request body on `POST` / `PUT`, or invalid JSON in the request body.
- `401` — Missing `x-api-key` header.
- `403` — Authenticated request denied. Common causes: invalid or unknown API key, suspended account, or `api` feature not enabled for the account.
- `429` — Rate limit of 60 requests per minute exceeded.
- `503` — Service is temporarily unavailable due to regional maintenance.

---

[API](https://skmtc.dev/tectonic/apis/award-force-api.md) · [All operations](https://skmtc.dev/tectonic/apis/award-force-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/tectonic/award-force-api/revisions/b70a2ea056c3/schema)