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

# Get the leaderboard

> Employees ranked by XP for a period, company-wide or within one department.

<Tip>
  See the [leaderboards guide](/guides/leaderboards) for period windows, what `rank` means under a department filter, and refresh cadence.
</Tip>


## OpenAPI

````yaml api-reference/openapi.json GET /v1/leaderboard
openapi: 3.0.0
info:
  title: TeamBuilder API
  description: >-
    The TeamBuilder API gives your own systems access to your company's
    gamification data (employees, leaderboards, departments and the rewards
    shop) and lets you push your employee roster from your HR system. Send every
    request to `https://api.teambuilder.ge/v1` with your API key as
    `Authorization: Bearer <key>`: live keys (`tb_live_…`) work on your real
    data, test keys (`tb_test_…`) on a sandbox company with sample data.
    Responses are JSON with snake_case fields, cursor-based pagination and
    `X-RateLimit-*` headers. For keys, scopes or help, contact
    [contact@teambuilder.ge](mailto:contact@teambuilder.ge).
  version: '1.0'
  contact:
    name: TeamBuilder support
    url: https://teambuilder.ge
    email: contact@teambuilder.ge
servers:
  - url: https://api.teambuilder.ge
    description: Production
security: []
tags:
  - name: Status
    description: Check that your API key works and see what it can access.
  - name: Employees
    description: >-
      Your active employees, their gamification stats and the badges they hold.
      Requires the `employees:read` scope.
  - name: Leaderboard
    description: >-
      XP rankings of your employees for a chosen period, company-wide or grouped
      by department. Requires the `leaderboard:read` scope.
  - name: Departments
    description: Your company's department tree. Requires the `departments:read` scope.
  - name: Shop
    description: >-
      The rewards your employees can redeem with their coins. Requires the
      `shop:read` scope.
  - name: Roster sync
    description: >-
      Keep TeamBuilder in step with your HR system by pushing your employee
      roster. Requires the `employees:write` scope, which is issued on request.
paths:
  /v1/leaderboard:
    get:
      tags:
        - Leaderboard
      summary: Get the leaderboard
      description: >-
        Returns your employees ranked by the XP they earned in the chosen
        `period`, highest first, 25 per page unless you set `limit`.


        Use it to show a company-wide leaderboard, or pass `department_id` to
        show one team with each member's company-wide rank.


        **Notes**


        - Rankings are refreshed at most every 30 seconds.

        - Ranks move while people earn XP, so paging is approximate: an employee
        can appear on two pages, or on none. Read the pages you need in quick
        succession.

        - Leaderboards never include coin balances.
      operationId: getLeaderboard
      parameters:
        - name: cursor
          required: false
          in: query
          description: >-
            The `pagination.next_cursor` of the previous page. Omit it, or send
            it empty, for the first page. A cursor is opaque and works only on
            the endpoint that returned it, for the same company.
          schema:
            maxLength: 512
            example: djEuQ2hhY2hhMjAuZXhhbXBsZS1jdXJzb3I
            type: string
        - name: limit
          required: false
          in: query
          description: How many items to return per page, from 1 to 100.
          schema:
            minimum: 1
            maximum: 100
            default: 25
            example: 25
            type: integer
        - name: period
          required: false
          in: query
          description: >-
            The window XP is counted over. Months are calendar months in UTC.

            - `all_time`: all XP ever earned.

            - `this_month`: XP earned since the 1st of the current month.

            - `last_3_months`: XP earned in the current month and the two before
            it.

            - `last_year`: XP earned in the current month and the eleven before
            it.
          schema:
            default: all_time
            example: this_month
            type: string
            enum:
              - all_time
              - this_month
              - last_3_months
              - last_year
        - name: department_id
          required: false
          in: query
          description: >-
            Only members of this department (not of its sub-departments). Each
            keeps their company-wide `rank`, so ranks on a filtered page can
            have gaps.
          schema:
            format: uuid
            example: b3e1f7a2-6c4d-4e8f-9a1b-2c3d4e5f6a7b
            type: string
      responses:
        '200':
          description: A page of the leaderboard.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Leaderboard'
        '400':
          description: >-
            A query parameter or the `cursor` is invalid. `message` names the
            problem.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: validation_failed
                  message: limit must not be greater than 100
                  request_id: req_7Hq2LmX9vT4kPz1RbN8sWc
        '401':
          description: The API key is missing, unknown, revoked or expired.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            WWW-Authenticate:
              $ref: '#/components/headers/WWW-Authenticate'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: unauthorized
                  message: Invalid API key
                  request_id: req_7Hq2LmX9vT4kPz1RbN8sWc
        '403':
          description: Your API key does not have the `leaderboard:read` scope.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: forbidden
                  message: 'This API key lacks the required scope: leaderboard:read'
                  request_id: req_7Hq2LmX9vT4kPz1RbN8sWc
        '404':
          description: '`department_id` is not a department of your company.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: not_found
                  message: Department not found
                  request_id: req_7Hq2LmX9vT4kPz1RbN8sWc
        '429':
          description: >-
            Your API key made more requests than its limit allows (60 per minute
            unless agreed otherwise), or too many requests came from your IP
            address. Wait `Retry-After` seconds, then retry.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: rate_limit_exceeded
                  message: Too many requests. Retry after 30 seconds.
                  request_id: req_7Hq2LmX9vT4kPz1RbN8sWc
      security:
        - api-key: []
components:
  headers:
    X-Request-Id:
      description: Unique id of this request. Quote it when you contact support.
      schema:
        type: string
        example: req_7Hq2LmX9vT4kPz1RbN8sWc
    X-RateLimit-Limit:
      description: Requests your API key may make per minute.
      schema:
        type: integer
        example: 60
    X-RateLimit-Remaining:
      description: Requests left in the current one-minute window.
      schema:
        type: integer
        example: 57
    X-RateLimit-Reset:
      description: When the current window ends, as a Unix timestamp in seconds.
      schema:
        type: integer
        example: 1792483260
    WWW-Authenticate:
      description: The authentication scheme to use.
      schema:
        type: string
        example: Bearer realm="TeamBuilder API"
    Retry-After:
      description: Seconds to wait before you retry.
      schema:
        type: integer
        example: 30
  schemas:
    Leaderboard:
      type: object
      properties:
        data:
          description: Employees on this page, highest rank first.
          type: array
          items:
            $ref: '#/components/schemas/LeaderboardEntry'
        pagination:
          description: Where the next page starts.
          allOf:
            - $ref: '#/components/schemas/Pagination'
      required:
        - data
        - pagination
    Error:
      type: object
      properties:
        error:
          description: What went wrong, and the id that traces the request.
          allOf:
            - $ref: '#/components/schemas/ErrorDetail'
      description: Every error response has this shape, whatever its status code.
      required:
        - error
    LeaderboardEntry:
      type: object
      properties:
        rank:
          type: integer
          minimum: 1
          description: >-
            Position among all your employees for the period. 1 is the top. A
            department filter keeps it.
          example: 3
        employee_id:
          type: string
          format: uuid
          description: >-
            TeamBuilder id of the employee. Stable for as long as they are in
            your company.
          example: 8d2f6b1e-4c3a-4f5e-b7d9-1a2c3e4f5a6b
        external_id:
          type: string
          nullable: true
          description: The employee's key in your HR system. Null if none was set.
          example: EMP-00042
        name:
          type: string
          nullable: true
          description: >-
            Full name. Until the employee first signs in, this is the name your
            roster sync sent, or null if it sent none; afterwards, the name on
            their TeamBuilder account.
          example: Nino Beridze
        department:
          nullable: true
          description: The department the employee belongs to. Null if they have none.
          type: object
          allOf:
            - $ref: '#/components/schemas/DepartmentRef'
        level:
          type: integer
          minimum: 1
          description: Current level, earned through all-time XP whatever the period.
          example: 12
        xp:
          type: integer
          description: >-
            XP earned in the period (all-time XP for `all_time`). The ranking is
            by this value.
          example: 12450
      description: An employee and their position on the leaderboard.
      required:
        - rank
        - employee_id
        - external_id
        - name
        - department
        - level
        - xp
    Pagination:
      type: object
      properties:
        next_cursor:
          type: string
          nullable: true
          description: Pass it as `cursor` to read the next page. Null on the last page.
          example: djEuQ2hhY2hhMjAuZXhhbXBsZS1jdXJzb3I
      required:
        - next_cursor
    ErrorDetail:
      type: object
      properties:
        code:
          description: >-
            Machine-readable error type. Branch on this, not on `message`:

            - `validation_failed` (400): a parameter, cursor or body field is
            invalid.

            - `unauthorized` (401): the API key is missing, unknown, revoked or
            expired.

            - `forbidden` (403): the key does not have the scope this endpoint
            requires.

            - `not_found` (404): the resource does not exist in your company.

            - `conflict` (409): the request clashes with work in progress, such
            as another roster sync.

            - `length_required` (411): the request body was sent without a
            `Content-Length` header.

            - `payload_too_large` (413): the request body is larger than the
            endpoint accepts.

            - `rate_limit_exceeded` (429): the key made too many requests; wait
            for `Retry-After` seconds.

            - `bad_request` (other 4xx): the request could not be accepted as
            sent.

            - `internal_error` (500): something failed on our side; contact
            support with the `request_id`.
          example: validation_failed
          allOf:
            - $ref: '#/components/schemas/ErrorCode'
        message:
          type: string
          description: >-
            Human-readable explanation for developers. It may change; do not
            parse it.
          example: limit must not be greater than 100
        request_id:
          type: string
          description: >-
            Unique id of the request, also sent as the `X-Request-Id` header.
            Quote it when you contact support.
          example: req_7Hq2LmX9vT4kPz1RbN8sWc
      required:
        - code
        - message
        - request_id
    DepartmentRef:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: TeamBuilder id of the department.
          example: b3e1f7a2-6c4d-4e8f-9a1b-2c3d4e5f6a7b
        external_id:
          type: string
          nullable: true
          description: The department's key in your HR system. Null if none was set.
          example: D-ENG
        name:
          type: string
          description: Department name.
          example: Engineering
      description: The department an employee belongs to.
      required:
        - id
        - external_id
        - name
    ErrorCode:
      type: string
      enum:
        - bad_request
        - validation_failed
        - unauthorized
        - forbidden
        - not_found
        - conflict
        - length_required
        - payload_too_large
        - rate_limit_exceeded
        - internal_error
      description: >-
        Machine-readable error type. Branch on this, not on `message`:

        - `validation_failed` (400): a parameter, cursor or body field is
        invalid.

        - `unauthorized` (401): the API key is missing, unknown, revoked or
        expired.

        - `forbidden` (403): the key does not have the scope this endpoint
        requires.

        - `not_found` (404): the resource does not exist in your company.

        - `conflict` (409): the request clashes with work in progress, such as
        another roster sync.

        - `length_required` (411): the request body was sent without a
        `Content-Length` header.

        - `payload_too_large` (413): the request body is larger than the
        endpoint accepts.

        - `rate_limit_exceeded` (429): the key made too many requests; wait for
        `Retry-After` seconds.

        - `bad_request` (other 4xx): the request could not be accepted as sent.

        - `internal_error` (500): something failed on our side; contact support
        with the `request_id`.
  securitySchemes:
    api-key:
      scheme: bearer
      bearerFormat: API key
      type: http
      description: API key — `tb_live_…` for production data, `tb_test_…` for the sandbox.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.