> ## 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 single leaderboard > Get a specific leaderboard by its key. ## OpenAPI ````yaml https://api.trophy.so/v1/openapi get /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: /leaderboards/{key}: servers: - url: https://api.trophy.so/v1 description: Application API parameters: - $ref: '#/components/parameters/TenantId' get: tags: - Leaderboards summary: Get a single leaderboard description: Get a specific leaderboard by its key. operationId: leaderboards_get parameters: - name: key in: path description: Unique key of the leaderboard as set when created. required: true schema: type: string example: weekly-words - name: offset in: query description: Number of rankings to skip for pagination. required: false schema: type: integer minimum: 0 default: 0 example: 20 - name: limit in: query description: >- Maximum number of rankings to return. Cannot be greater than the size of the leaderboard. required: false schema: type: integer minimum: 0 default: 10 example: 50 - 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: userId in: query description: >- When provided, offset is relative to this user's position on the leaderboard. If the user is not found in the leaderboard, returns empty rankings array. required: false schema: type: string example: user-123 - name: userAttributes in: query description: >- Attribute key and value to filter the rankings by, separated by a colon. For example, `city:London`. This parameter is required, and only valid for leaderboards with a breakdown attribute. required: false schema: type: string example: city:London responses: '200': description: Successful operation content: application/json: schema: $ref: '#/components/schemas/LeaderboardResponseWithRankings' 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 pointsSystemKey: null pointsSystemName: null description: Compete weekly to see who writes the most words status: active start: '2025-01-01' end: null maxParticipants: 100 breakdownAttribute: null runUnit: day runInterval: 7 rankings: - userId: user-123 userName: Alice Johnson rank: 1 value: 5000 - userId: user-456 userName: Bob Smith rank: 2 value: 4500 - userId: user-789 userName: Charlie Brown rank: 3 value: 4200 '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorBody' '404': description: 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 label: Get rankings source: | import { TrophyApiClient } from '@trophyso/node'; const trophy = new TrophyApiClient({ apiKey: 'YOUR_API_KEY' }); const response = await trophy.leaderboards.get("weekly-words", { offset: 0, limit: 10, run: "2025-01-15" }); - lang: javascript label: Get rankings by user attribute source: | import { TrophyApiClient } from '@trophyso/node'; const trophy = new TrophyApiClient({ apiKey: 'YOUR_API_KEY' }); const response = await trophy.leaderboards.get("weekly-words", { offset: 0, limit: 10, run: "2025-01-15", userAttributes: "city:london" }); - lang: python label: Get rankings source: | from trophy import TrophyApi client = TrophyApi(api_key='YOUR_API_KEY') response = client.leaderboards.get( key="weekly-words", offset=0, limit=10, run="2025-01-15" ) - lang: python label: Get rankings by user attribute source: | from trophy import TrophyApi client = TrophyApi(api_key='YOUR_API_KEY') response = client.leaderboards.get( key="weekly-words", offset=0, limit=10, run="2025-01-15", user_attributes="city:london" ) - 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.Leaderboards.Get( context.TODO(), "leaderboard-key", &api.LeaderboardsGetRequest{}, ) 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: LeaderboardResponseWithRankings: title: LeaderboardResponseWithRankings type: object allOf: - $ref: '#/components/schemas/LeaderboardResponse' - type: object properties: status: type: string enum: - active - scheduled - finished description: The status of the leaderboard. example: active rankings: type: array description: Array of user rankings for the leaderboard. items: $ref: '#/components/schemas/LeaderboardRanking' required: - rankings - status ErrorBody: title: ErrorBody type: object properties: error: type: string required: - error 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 LeaderboardRanking: title: LeaderboardRanking type: object description: A user's ranking in a leaderboard. properties: userId: type: string description: The ID of the user. example: user-123 userName: type: - string - 'null' description: The name of the user. May be null if no name is set. example: Alice Johnson rank: type: integer description: The user's rank in the leaderboard. example: 1 value: type: integer description: The user's value for this leaderboard (points, metric value, etc.). example: 5000 required: - userId - userName - rank - value securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-KEY ````