> ## 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.

# Get a user's leaderboard data

> Get a user's rank, value, and daily ranking history for a specific leaderboard.



## OpenAPI

````yaml https://api.trophy.so/v1/openapi get /users/{id}/leaderboards/{key}
openapi: 3.1.0
info:
  title: Trophy
  version: 1.19.0
servers:
  - x-fern-server-name: Application API
    url: https://api.trophy.so/v1
    description: Application API
security: []
paths:
  /users/{id}/leaderboards/{key}:
    servers:
      - url: https://api.trophy.so/v1
        description: Application API
    parameters:
      - $ref: '#/components/parameters/TenantId'
    get:
      tags:
        - Users
      summary: Get a user's leaderboard data
      description: >-
        Get a user's rank, value, and daily ranking history for a specific
        leaderboard.
      operationId: users_leaderboard
      parameters:
        - name: id
          in: path
          description: The user's ID in your database.
          required: true
          schema:
            type: string
          example: user-123
        - name: key
          in: path
          description: Unique key of the leaderboard as set when created.
          required: true
          schema:
            type: string
          example: weekly-words
        - name: run
          in: query
          description: >-
            Specific run date in YYYY-MM-DD format. If not provided, returns the
            current run.
          required: false
          schema:
            type: string
            format: date
          example: '2025-01-15'
        - name: numEvents
          in: query
          description: >-
            The number of days to return in the leaderboard history for the
            user.
          required: false
          schema:
            type: integer
            default: 10
            minimum: 0
            maximum: 100
          example: 10
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserLeaderboardResponseWithHistory'
              examples:
                Successful operation:
                  value:
                    id: 5100fe51-6bce-6j44-b0hs-bddc4e123682
                    name: Weekly Word Count Challenge
                    key: weekly-words
                    rankBy: metric
                    metricKey: words-written
                    metricName: Words Written
                    description: Compete weekly to see who writes the most words
                    start: '2025-01-01'
                    end: null
                    maxParticipants: 100
                    breakdownAttribute: null
                    runUnit: day
                    runInterval: 7
                    rank: 2
                    value: 4500
                    history:
                      - date: '2025-01-13'
                        timestamp: '2025-01-13T00:00:00.000Z'
                        previousRank: null
                        rank: 5
                        previousValue: null
                        value: 1000
                      - date: '2025-01-14'
                        timestamp: '2025-01-14T00:00:00.000Z'
                        previousRank: 5
                        rank: 3
                        previousValue: 1000
                        value: 3000
                      - date: '2025-01-15'
                        timestamp: '2025-01-15T00:00:00.000Z'
                        previousRank: 3
                        rank: 2
                        previousValue: 3000
                        value: 4500
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '404':
          description: User or leaderboard not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '422':
          description: Unprocessible Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: javascript
          source: >
            import { TrophyApiClient } from '@trophyso/node';


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


            const response = await trophy.users.leaderboards("user-123",
            "weekly-words", {
              run: "2025-01-15"
            });
        - lang: python
          source: |
            from trophy import TrophyApi

            client = TrophyApi(api_key='YOUR_API_KEY')

            response = client.users.leaderboards(
              user_id="user-123",
              key="weekly-words",
              run="2025-01-15"
            )
        - 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.Users.Leaderboard(
              context.TODO(),
              "user-id",
              "leaderboard-key",
              &api.UsersLeaderboardRequest{},
            )
components:
  parameters:
    TenantId:
      name: Tenant-ID
      in: header
      description: >-
        The tenant identifier for multi-tenant organisations. Required when the
        organisation has multi-tenancy enabled. The value should be your
        internal ID for the tenant. Ignored for single-tenant organisations.
      required: false
      schema:
        type: string
      example: customer_12345
  schemas:
    UserLeaderboardResponseWithHistory:
      title: UserLeaderboardResponseWithHistory
      type: object
      description: >-
        A user's data for a specific leaderboard including rank, value, and
        history.
      allOf:
        - $ref: '#/components/schemas/UserLeaderboardResponse'
        - type: object
          properties:
            history:
              type: array
              items:
                $ref: '#/components/schemas/LeaderboardEvent'
              description: >-
                An array of daily change events showing the user's rank and
                value over time.
          required:
            - history
    ErrorBody:
      title: ErrorBody
      type: object
      properties:
        error:
          type: string
      required:
        - error
    UserLeaderboardResponse:
      title: UserLeaderboardResponse
      type: object
      description: >-
        A user's data for a specific leaderboard including rank, value, and
        history.
      allOf:
        - $ref: '#/components/schemas/LeaderboardResponse'
        - type: object
          properties:
            rank:
              type:
                - integer
                - 'null'
              description: >-
                The user's current rank in this leaderboard. Null if the user is
                not on the leaderboard.
              example: 2
            value:
              type:
                - integer
                - 'null'
              description: >-
                The user's current value in this leaderboard. Null if the user
                is not on the leaderboard.
              example: 4500
          required:
            - rank
            - value
    LeaderboardEvent:
      title: LeaderboardEvent
      type: object
      description: >-
        A daily leaderboard snapshot entry representing the user's rank/value
        state and the previous persisted state.
      properties:
        date:
          type: string
          format: date
          description: The leaderboard snapshot date in YYYY-MM-DD format.
          example: '2025-01-15'
        timestamp:
          type: string
          format: date-time
          description: >-
            Deprecated ISO timestamp for the snapshot day boundary. Use `date`
            instead.
          example: '2025-01-15T00:00:00.000Z'
          deprecated: true
        previousRank:
          type:
            - integer
            - 'null'
          description: >-
            The user's rank before this event, or null if they were not on the
            leaderboard.
          example: 5
        rank:
          type:
            - integer
            - 'null'
          description: >-
            The user's rank after this event, or null if they are no longer on
            the leaderboard.
          example: 3
        previousValue:
          type:
            - integer
            - 'null'
          description: >-
            The user's value before this event, or null if they were not on the
            leaderboard.
          example: 1000
        value:
          type:
            - integer
            - 'null'
          description: >-
            The user's value after this event, or null if they are no longer on
            the leaderboard.
          example: 3000
      required:
        - date
        - timestamp
        - previousRank
        - rank
        - previousValue
        - value
    LeaderboardResponse:
      title: LeaderboardResponse
      type: object
      description: A leaderboard with its configuration details.
      properties:
        id:
          type: string
          description: The unique ID of the leaderboard.
          example: 5100fe51-6bce-6j44-b0hs-bddc4e123682
        name:
          type: string
          description: The user-facing name of the leaderboard.
          example: Weekly Word Count Challenge
        key:
          type: string
          description: The unique key used to reference the leaderboard in APIs.
          example: weekly-words
        rankBy:
          type: string
          enum:
            - points
            - streak
            - metric
          description: What the leaderboard ranks by.
          example: metric
        breakdownAttribute:
          type:
            - string
            - 'null'
          description: >-
            Deprecated. The key of the attribute to break down this leaderboard
            by.
          deprecated: true
          example: country
        breakdownAttributes:
          type: array
          description: The user attribute keys that this leaderboard is broken down by.
          items:
            type: string
            description: The key of a user attribute in this leaderboard breakdown.
            example: country
        metricKey:
          type: string
          description: The key of the metric to rank by, if rankBy is 'metric'.
          example: words-written
        metricName:
          type: string
          description: The name of the metric to rank by, if rankBy is 'metric'.
          example: Words Written
        pointsSystemKey:
          type: string
          description: The key of the points system to rank by, if rankBy is 'points'.
          example: xp-system
        pointsSystemName:
          type: string
          description: The name of the points system to rank by, if rankBy is 'points'.
          example: Experience Points
        description:
          type:
            - string
            - 'null'
          description: The user-facing description of the leaderboard.
          example: Compete weekly to see who writes the most words
        start:
          type: string
          format: date
          description: The start date of the leaderboard in YYYY-MM-DD format.
          example: '2025-01-01'
        end:
          type:
            - string
            - 'null'
          format: date
          description: >-
            The end date of the leaderboard in YYYY-MM-DD format, or null if it
            runs forever.
          example: '2025-12-31'
        startTime:
          type:
            - string
            - 'null'
          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
            - 'null'
          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'
        maxParticipants:
          type:
            - integer
            - 'null'
          description: The maximum number of participants in the leaderboard.
          example: 100
        runUnit:
          type:
            - string
            - 'null'
          enum:
            - day
            - month
            - year
            - null
          description: >-
            The repetition type for recurring leaderboards, or null for one-time
            leaderboards.
          example: day
        runInterval:
          type:
            - integer
            - 'null'
          description: >-
            The interval between repetitions, relative to the start date and
            repetition type. Null for one-time leaderboards.
          example: 7
      required:
        - id
        - name
        - key
        - status
        - description
        - rankBy
        - breakdownAttribute
        - breakdownAttributes
        - start
        - end
        - startTime
        - endTime
        - maxParticipants
        - runUnit
        - runInterval
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

````