---
title: "Admin Rankings"
method: GET
path: "/api/v1/quick-spaces/admin/rankings"
tags: ["quickSpaces", "quickSpaces"]
---

# Admin Rankings

`GET /api/v1/quick-spaces/admin/rankings`

Every ranking board in one response — the composite plus each single metric — each carrying
the same window's places against the previous window of equal length. It is the one route here
that builds two reports, because the comparison IS the answer.

`metric` narrows the single-metric boards to one; the composite always ships, because it is the
thing the screen is for and it costs nothing extra once the two reports exist.

## Query parameters

- `start` string, nullable — YYYY-MM-DD, inclusive, UTC
- `end` string, nullable — YYYY-MM-DD, inclusive, UTC
- `metric` string, nullable — one metric key; default every board
- `limit` integer

## Headers

- `X-Admin-Session` string, nullable

## Response `200`

Successful Response

- AdminRankingsResponseDTO
  - `range` AdminRangeDTO, required — The window every number on the response was computed over. Inclusive on both ends, UTC.
    - `start` string, date, required
    - `end` string, date, required
    - `days` integer
  - `previous` AdminRangeDTO, required — The window every number on the response was computed over. Inclusive on both ends, UTC.
    - `start` string, date, required
    - `end` string, date, required
    - `days` integer
  - `metrics` AdminRankBoardDTO[]
    - `key` string, required
    - `label` string
    - `unit` string
    - `total` number
    - `total_is_distinct` boolean
    - `rows` AdminRankRowDTO[]
      - `rank` integer
      - `user_id` string, required
      - `name` string
      - `email` string
      - `role` string
      - `source` string
      - `value` number
      - `share_pct` number
      - `percentile` number
      - `previous` number
      - `delta` number
      - `delta_pct` number, nullable
      - `trend` string
      - `zero_activity` boolean
    - `ranked` integer
    - `truncated` boolean
  - `composite` AdminCompositeDTO — The composite board, published with the recipe that produced it. `weights` is the flat axis -> weight map for a legend; `axes` is the same thing with the labels and the component names, so a UI can say "Output (35%): creatives uploaded, projects delivered" without hard-coding the model this endpoint owns.
    - `weights` object
    - `axes` AdminRankAxisDTO[]
      - `key` string, required
      - `label` string
      - `weight` number
      - `score` number
      - `points` number
      - `components` AdminRankComponentDTO[]
        - `key` string, required
        - `label` string
        - `value` number
        - `normalised` number
    - `rows` AdminCompositeRowDTO[]
      - `rank` integer
      - `user_id` string, required
      - `name` string
      - `email` string
      - `role` string
      - `source` string
      - `score` number
      - `previous_score` number
      - `delta` number
      - `delta_pct` number, nullable
      - `trend` string
      - `percentile` number
      - `zero_activity` boolean
      - `breakdown` AdminRankAxisDTO[]
        - `key` string, required
        - `label` string
        - `weight` number
        - `score` number
        - `points` number
        - `components` AdminRankComponentDTO[]
          - `key` string, required
          - `label` string
          - `value` number
          - `normalised` number
    - `ranked` integer
    - `truncated` boolean

## Other responses

- `422` — Validation Error

## Changes

- **2026-09-02** `ff7f2b621b41` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/brandbooster/apis/fastapi/changes/api/v1/quick-spaces/admin/rankings/get.md)

---

[API](https://skmtc.dev/brandbooster/apis/fastapi.md) · [All operations](https://skmtc.dev/brandbooster/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/brandbooster/fastapi/revisions/ff7f2b621b41/schema)