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

# Leaderboard

> Returns top profiles by view count. **Permission required:** `api.leaderboard`. Data may be cached (e.g. Redis).

Returns top profiles by view count. Requires permission **`api.leaderboard`**. Data may be cached (e.g. Redis). Non-cache errors return 500 with `{ "error": "Failed to fetch leaderboard" }`.

Only badges with `name === "verified"` or `name === "team"` are included. `assets.pfp` is `null` for the default avatar.


## OpenAPI

````yaml GET /leaderboard
openapi: 3.1.0
info:
  title: frozi.lol API
  description: >-
    REST API for frozi.lol. Access profile data, leaderboard, and
    profile-related content (e.g. links). All endpoints require a valid API key.
  version: 1.0.0
servers:
  - url: https://frozi.lol/api
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Leaderboard
    description: Top profiles by view count
  - name: Lookup
    description: Profile and links lookup by username, UID, or auth ID
paths:
  /leaderboard:
    get:
      tags:
        - Leaderboard
      summary: Get leaderboard
      description: >-
        Returns top profiles by view count. **Permission required:**
        `api.leaderboard`. Data may be cached (e.g. Redis).
      operationId: getLeaderboard
      parameters:
        - name: limit
          in: query
          description: Max number of profiles to return (1–100). Default 100.
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 100
      responses:
        '200':
          description: Leaderboard response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeaderboardResponse'
        default:
          description: >-
            Error response. See [Errors](/api-reference/errors) for status codes
            and format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    LeaderboardResponse:
      type: object
      properties:
        topProfiles:
          type: array
          items:
            $ref: '#/components/schemas/LeaderboardItem'
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Human-readable error message
    LeaderboardItem:
      type: object
      properties:
        username:
          type: string
        displayName:
          type: string
        viewsCount:
          type: number
        badges:
          type: array
          items:
            $ref: '#/components/schemas/LeaderboardBadge'
        assets:
          type: object
          properties:
            pfp:
              type: string
              nullable: true
              description: Null if default avatar
    LeaderboardBadge:
      type: object
      properties:
        name:
          type: string
          description: Only 'verified' or 'team' are included
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        API key from Dashboard → Developer Platform → API Keys. Send as:
        Authorization: Bearer <API_KEY>

````