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

# Get Leaderboard

> Retrieves leaderboard data for a specific campaign. Supports both v1 and v2 leaderboard formats based on campaign type.



## OpenAPI

````yaml /openapi.yaml get /leaderboard
openapi: 3.0.0
info:
  title: claimr API
  version: 1.0.0
  description: >-
    Advanced features of claimr for business partners. This API provides a
    seamless integration with claimr services
  termsOfService: https://claimr.io/terms-of-service/
  contact:
    name: claimr support team
    email: support@claimr.io
servers:
  - url: https://prod.claimr.io/api/v1
    description: Production server
  - url: https://prod.claimr.io/api/v1
    description: Development server
security: []
tags: []
paths:
  /leaderboard:
    get:
      tags:
        - Leaderboard
      summary: Get Leaderboard
      description: >-
        Retrieves leaderboard data for a specific campaign. Supports both v1 and
        v2 leaderboard formats based on campaign type.
      parameters:
        - in: query
          name: pid
          description: Campaign ID (required)
          required: true
          schema:
            type: string
            example: campaign_123
        - in: query
          name: account
          description: User's account identifier (required for v2 campaigns)
          required: false
          schema:
            type: string
            example: user123
        - in: query
          name: platform
          description: >-
            Account's platform (required for v2 campaigns when account is
            provided)
          required: false
          schema:
            type: string
            example: twitter
            enum:
              - twitter
              - discord
              - telegram
              - email
      responses:
        '200':
          description: Successfully retrieved campaign leaderboard
          content:
            application/json:
              schema:
                oneOf:
                  - title: V2 Leaderboard Response
                    type: object
                    properties:
                      success:
                        type: boolean
                        example: true
                      data:
                        type: object
                        properties:
                          live:
                            type: boolean
                            description: Indicates if leaderboard is live/real-time
                            example: true
                          leaderboard:
                            type: array
                            description: Array of leaderboard entries (v2 format)
                            items:
                              type: object
                              properties:
                                rank:
                                  type: integer
                                  description: Current rank position
                                  example: 1
                                score:
                                  type: number
                                  description: User's score
                                  example: 1250.75
                                user:
                                  type: object
                                  description: User information
                                  properties:
                                    id:
                                      type: string
                                      example: user_123
                                    name:
                                      type: string
                                      example: John Doe
                                    avatar:
                                      type: string
                                      nullable: true
                                      example: https://example.com/avatar.jpg
                              required:
                                - rank
                                - score
                                - user
                          rank:
                            type: integer
                            description: Current user's rank (if account provided)
                            example: 5
                            nullable: true
                        required:
                          - live
                          - leaderboard
                  - title: V1 Leaderboard Response
                    type: object
                    properties:
                      success:
                        type: boolean
                        example: true
                      data:
                        type: object
                        properties:
                          leaderboard:
                            type: array
                            description: Array of leaderboard entries (v1 format)
                            items:
                              type: object
                              properties:
                                id:
                                  type: string
                                  description: User ID
                                  example: user_123
                                name:
                                  type: string
                                  description: User display name
                                  example: John Doe
                                xp:
                                  type: number
                                  description: Experience points
                                  example: 1250
                                cts:
                                  type: number
                                  description: Custom tracking score
                                  example: 150
                              required:
                                - id
                                - name
                                - xp
                                - cts
                        required:
                          - leaderboard
                required:
                  - success
                  - data
        '400':
          description: |
            Bad request - possible causes:
            - Missing required pid parameter
            - Invalid campaign ID
            - Campaign doesn't belong to requesting organization
            - Missing account/platform for v2 campaigns
            - Invalid user credentials
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  error:
                    type: object
                    properties:
                      code:
                        type: integer
                        format: int32
                        default: 400
                      message:
                        type: string
                        default: bad request
        '401':
          $ref: '#/components/responses/unauthorized'
          description: Unauthorized - invalid or missing bearer token
        '403':
          $ref: '#/components/responses/access_denied'
          description: Access denied - insufficient permissions
        '500':
          $ref: '#/components/responses/internal_error'
          description: Internal server error
      security:
        - bearer: []
components:
  responses:
    unauthorized:
      description: Unauthorized request
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
              error:
                type: object
                properties:
                  code:
                    type: integer
                    format: int32
                    default: 401
                  message:
                    type: string
                    default: unauthorized
    access_denied:
      description: Access denied
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
              error:
                type: object
                properties:
                  code:
                    type: integer
                    format: int32
                    default: 403
                  message:
                    type: string
                    default: access denied
    internal_error:
      description: Internal server error
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
              error:
                type: object
                properties:
                  code:
                    type: integer
                    format: int32
                    default: 500
                  message:
                    type: string
                    default: internal error
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT

````