---
title: "GET /api/v4.0/integrations/leaderboard"
method: GET
path: "/api/v4.0/integrations/leaderboard"
---

# GET /api/v4.0/integrations/leaderboard

`GET /api/v4.0/integrations/leaderboard`

This API retrieves the leaderboard rankings of customers within your loyalty program in Gameball, either for a specific date range or for all time. Results are ordered from the highest to the lowest rank, displaying each customer's rank, progress, and tier details.

## Query parameters

- `from` string, date-time
- `to` string, date-time
- `customerId` string
- `rewardCampaignId` integer
- `customerTag` string
- `rewardCampaignTag` string

## Response `200`

Leaderboard retrieved successfully

- object
  - `leaderboard` object[] — An array of customers ranked on the leaderboard, sorted by their score. Each entry in the array includes details about each customer, providing a comprehensive overview of their standing within the entire customer base.
    - `displayName` string — The display name of the customer on the leaderboard.
    - `customerId` string — Unique identifier for the customer that you can reference across the customer's whole lifetime.
    - `progress` number — The progress made by the customer, such as points earned.
    - `rank` number — The customer's position on the leaderboard, determined by their performance, such as points accumulated. The rank is typically higher for those with more points or progress.
    - `tierName` string — The name of the customer's current tier.
    - `tierIcon` string — URL for the icon representing the customer's current tier.
  - `customerRank` number — The position of the requested customer on the leaderboard, reflecting their rank relative to all other customers in your entire customer base. A lower rank number (e.g., 1) indicates a higher standing, typically based on points or achievements.
  - `customersCount` number — The total number of customers on the leaderboard.

---

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