---
title: "Retrieve the leaderboard"
method: GET
path: "/partners/leaderboard"
tags: ["Partners"]
---

# Retrieve the leaderboard

`GET /partners/leaderboard`

Ranks referrers by partner business earnings — all-time by default, or over the current day, month, year, or trailing 30 days. Authentication is optional: authenticated callers also get their own standing, anonymous callers get the rankings alone.

## Query parameters

- `period` 'day' | 'month' | 'year' | 'last_30_days' | 'all_time'

## Response `200`

caller has no referral earnings

- object
  - `leaders` object[], required — The top referrers by total earnings, best first.
    - `first_referral_started_at` string, date-time, required — When the referrer's earliest partner business became active.
    - `rank` integer, required — 1-based leaderboard position.
    - `total_earnings_usd` string, required — The referrer's pending + completed earnings across all referred businesses, in USD.
    - `total_volume_usd` string, required — Credited GMV across all the referrer's referred businesses, in USD.
    - `user` object, nullable, required — The ranked referrer. Identity fields (id, name, username, profile_picture) are returned only on the caller's own entry; other referrers expose coarse location only.
      - `city` string, nullable, required — The city where the referrer is located, derived from their IP address. Null if location sharing is disabled.
      - `country` string, nullable, required — The country where the referrer is located, derived from their IP address. Null if location sharing is disabled.
      - `id` string — User ID, prefixed `user_`. Present only on the caller's own entry.
      - `name` string, nullable — The user's display name. Present only on the caller's own entry.
      - `profile_picture` object — The user's profile picture. Present only on the caller's own entry.
        - `url` string, required — The user's profile picture URL.
      - `username` string — The user's unique username. Present only on the caller's own entry.
  - `me` object, nullable, required — The caller's own standing; null when the caller has no referral earnings.
    - `first_referral_started_at` string, date-time, required — When the referrer's earliest partner business became active.
    - `rank` integer, required — 1-based leaderboard position.
    - `total_earnings_usd` string, required — The referrer's pending + completed earnings across all referred businesses, in USD.
    - `total_volume_usd` string, required — Credited GMV across all the referrer's referred businesses, in USD.
    - `user` object, nullable, required — The ranked referrer. Identity fields (id, name, username, profile_picture) are returned only on the caller's own entry; other referrers expose coarse location only.
      - `city` string, nullable, required — The city where the referrer is located, derived from their IP address. Null if location sharing is disabled.
      - `country` string, nullable, required — The country where the referrer is located, derived from their IP address. Null if location sharing is disabled.
      - `id` string — User ID, prefixed `user_`. Present only on the caller's own entry.
      - `name` string, nullable — The user's display name. Present only on the caller's own entry.
      - `profile_picture` object — The user's profile picture. Present only on the caller's own entry.
        - `url` string, required — The user's profile picture URL.
      - `username` string — The user's unique username. Present only on the caller's own entry.

## Other responses

- `400` — Invalid Parameters

---

[API](https://skmtc.net/whop/apis/whop-api.md) · [All operations](https://skmtc.net/whop/apis/whop-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/whop/whop-api/versions/866821546d67/schema)