---
title: "List Leaderboards for a Brand"
method: GET
path: "/leaderboards/brand/{brandId}"
tags: ["Leaderboards"]
---

# List Leaderboards for a Brand

`GET /leaderboards/brand/{brandId}`

All leaderboards and tournaments configured for the brand, including prize tiers, period dates, and reset cadence.

For repeatable leaderboards, when a period ends the current instance moves to `rewarding`, then `archived`, and a new `active` instance appears in the list automatically.

## Path parameters

- `brandId` string, uuid, required

## Response `200`

Array of leaderboards.

- Leaderboard[]
  - `id` string — UUID. Use as `leaderboardId` in statistics and enrollment calls.
  - `brandId` string, uuid
  - `name` string — Display name shown in the widget.
  - `description` string, nullable — Optional longer description.
  - `type` 'leaderboard' | 'tournament' — `leaderboard` (auto-enrolled, rank by score) or `tournament` (opt-in, may have entry cost).
  - `status` 'draft' | 'active' | 'rewarding' | 'archived' — `draft` not visible; `active` running; `rewarding` period ended, prizes distributing (typically resolves within 5 to 20 minutes); `archived` terminal state.
  - `objectivesActivated` boolean — `true` when the leaderboard score is driven by in-app objectives.
  - `startDate` string, date-time — When the current period started.
  - `endDate` string, date-time — When the current period ends.
  - `isRepeatable` boolean — Whether the leaderboard resets and restarts automatically.
  - `resetEveryHours` integer, nullable — Reset interval in hours (e.g. `168` = weekly). `null` if not repeatable.
  - `rewards` LeaderboardRewardTier[] — Prize tiers by rank range. Show these as the incentive to compete.
    - `id` string
    - `leaderboardId` string
    - `rankFrom` integer — Start of the rank range eligible for this prize tier (inclusive).
    - `rankTo` integer — End of the rank range (inclusive).
    - `items` LeaderboardRewardItem[]
      - `id` string
      - `leaderboardRewardId` string
      - `rewardId` string, uuid — Look up in the rewards catalog by matching against `id`.
      - `amount` integer
      - `rewardName` string
      - `rewardType` 'currency' | 'progression' | 'badge'
      - `rewardIcon` string, nullable
      - `rewardTag` 'common' | 'rare' | 'epic' | 'legendary'
    - `createdAt` string, date-time
    - `updatedAt` string, date-time
  - `objectives` string[] — Objective IDs that drive the leaderboard score. Empty array when `objectivesActivated` is `false`.
  - `participationCostCurrencyId` string, uuid, nullable — UUID of the currency required to enter (tournaments only). `null` if free.
  - `participationCostAmount` integer, nullable — Amount of that currency required to enter (tournaments only). `null` if free.
  - `createdAt` string, date-time
  - `updatedAt` string, date-time

---

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