> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trophy.so/llms.txt
> Use this file to discover all available pages before exploring further.

# List leaderboards

> List leaderboards.



## OpenAPI

````yaml https://admin.trophy.so/v1/openapi get /leaderboards
openapi: 3.1.0
info:
  title: Trophy
  version: 1.19.0
servers:
  - x-fern-server-name: Admin API
    url: https://admin.trophy.so/v1
    description: Admin API
security: []
paths:
  /leaderboards:
    servers:
      - url: https://admin.trophy.so/v1
        description: Admin API
    parameters:
      - $ref: '#/components/parameters/TenantId'
    get:
      tags:
        - Admin
      summary: List leaderboards
      description: List leaderboards.
      operationId: admin_leaderboards_list
      parameters:
        - name: limit
          in: query
          description: Number of records to return.
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
          example: 10
        - name: skip
          in: query
          description: Number of records to skip from the start of the list.
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
          example: 0
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListLeaderboardsResponse'
              examples:
                Leaderboards list:
                  value:
                    - id: 550e8400-e29b-41d4-a716-446655440100
                      name: Revenue Champions
                      key: revenue-champions
                      description: Ranked by monthly revenue
                      status: active
                      rankBy: metric
                      metricId: 550e8400-e29b-41d4-a716-446655440000
                      maxParticipants: 100
                      start: '2026-04-20'
                      end: '2026-05-20'
                      breakdownAttributes:
                        - 550e8400-e29b-41d4-a716-446655440010
                      runUnit: month
                      runInterval: 1
                    - id: 550e8400-e29b-41d4-a716-446655440101
                      name: Streak Legends
                      key: streak-legends
                      status: scheduled
                      rankBy: streak
                      maxParticipants: 1000
                      start: '2026-04-27'
                      breakdownAttributes: []
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminErrorBody'
        '422':
          description: Unprocessible Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminErrorBody'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: javascript
          source: |
            import { TrophyApiClient } from '@trophyso/node';

            const trophy = new TrophyApiClient({
              apiKey: 'YOUR_API_KEY'
            });

            const leaderboards = await trophy.admin.leaderboards.list({
              limit: 10,
              skip: 0
            });
        - lang: python
          source: |
            from trophy import TrophyApi

            client = TrophyApi(api_key='YOUR_API_KEY')

            leaderboards = client.admin.leaderboards.list(
              limit=10,
              skip=0
            )
        - lang: go
          source: |
            import (
              "context"

              api "github.com/trophyso/trophy-go"
              trophyclient "github.com/trophyso/trophy-go/client"
              "github.com/trophyso/trophy-go/option"
            )

            client := trophyclient.NewClient(
              option.WithApiKey("YOUR_API_KEY"),
            )

            response, err := client.Admin.Leaderboards.List(context.TODO(), nil)
components:
  parameters:
    TenantId:
      name: Tenant-ID
      in: header
      description: >-
        The tenant identifier for multi-tenant organisations. Required when the
        organisation has multi-tenancy enabled. Pass your own internal customer
        ID for the tenant. Ignored for single-tenant organisations.
      required: false
      schema:
        type: string
      example: customer_12345
  schemas:
    ListLeaderboardsResponse:
      title: ListLeaderboardsResponse
      type: array
      description: A paginated list of leaderboards.
      items:
        $ref: '#/components/schemas/AdminLeaderboard'
    AdminErrorBody:
      title: AdminErrorBody
      type: object
      properties:
        error:
          type: string
      required:
        - error
    AdminLeaderboard:
      title: AdminLeaderboard
      type: object
      description: A leaderboard returned from the admin leaderboards endpoints.
      properties:
        id:
          type: string
          format: uuid
          description: The UUID of the leaderboard.
        name:
          type: string
          description: The leaderboard name.
        key:
          type: string
          description: The leaderboard key.
        description:
          type: string
          description: The leaderboard description.
        status:
          type: string
          enum:
            - inactive
            - active
            - scheduled
            - finished
          description: The current user-facing status of the leaderboard.
        rankBy:
          type: string
          enum:
            - metric
            - streak
            - points
          description: What the leaderboard ranks by.
        metricId:
          type: string
          format: uuid
          description: The metric ID used when `rankBy` is `metric`.
        pointsSystemId:
          type: string
          format: uuid
          description: The points system ID used when `rankBy` is `points`.
        maxParticipants:
          type:
            - integer
            - 'null'
          description: The maximum number of participants.
        start:
          type: string
          format: date
          description: The leaderboard start date in YYYY-MM-DD format.
        end:
          type: string
          format: date
          description: The optional leaderboard end date in YYYY-MM-DD format.
        startTime:
          type: string
          pattern: ^([01][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$
          description: >-
            When set, ranking only counts activity at or after this time of day
            in the user's timezone (HH:mm format).
          example: '09:00'
        endTime:
          type: string
          pattern: ^([01][0-9]|2[0-3]):[0-5][0-9](:[0-5][0-9])?$
          description: >-
            When set, ranking only counts activity before this time of day in
            the user's timezone (HH:mm format).
          example: '17:00'
        breakdownAttributes:
          type: array
          description: The UUIDs of the user attributes used for ranking breakdowns.
          items:
            type: string
            format: uuid
        runUnit:
          type: string
          enum:
            - day
            - month
            - year
          description: The recurrence unit when the leaderboard repeats.
        runInterval:
          type: integer
          description: The number of recurrence units between leaderboard runs.
      required:
        - id
        - name
        - key
        - status
        - rankBy
        - maxParticipants
        - start
        - breakdownAttributes
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

````