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

# Export fresh leaderboard rankings

> Calculates the selected period once from a fresh database snapshot and streams a complete CSV. Later writes are not included. Requires an authenticated admin user with permission to read XP logs, users and the leaderboard configuration. User identity fields retain community restrictions. Rankings exports allow up to 250000 participants and 64 MiB; exclusions templates allow 10000 rows and 5120000 bytes. Calculation has a 240-second request deadline. No partial file is returned if preparation fails.



## OpenAPI

````yaml /openapi/admin.json post /leaderboards/export
openapi: 3.1.0
info:
  title: Nudj Admin API
  version: 1.0.0
servers:
  - url: https://{subdomain}.nudj.cx/api/v2/admin
    description: Organization API Server
    variables:
      subdomain:
        description: Your organization's subdomain (required)
        default: your-org
security:
  - ApiToken: []
paths:
  /leaderboards/export:
    post:
      tags:
        - Leaderboard
      summary: Export fresh leaderboard rankings
      description: >-
        Calculates the selected period once from a fresh database snapshot and
        streams a complete CSV. Later writes are not included. Requires an
        authenticated admin user with permission to read XP logs, users and the
        leaderboard configuration. User identity fields retain community
        restrictions. Rankings exports allow up to 250000 participants and 64
        MiB; exclusions templates allow 10000 rows and 5120000 bytes.
        Calculation has a 240-second request deadline. No partial file is
        returned if preparation fails.
      operationId: exportLeaderboard
      parameters:
        - name: x-organisation-id
          in: header
          required: true
          schema:
            type: string
            pattern: ^[0-9a-fA-F]{24}$
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - configId
                - fieldKeys
                - format
              properties:
                configId:
                  type: string
                  pattern: ^[0-9a-fA-F]{24}$
                inHistoricPeriod:
                  type:
                    - string
                    - 'null'
                  format: date-time
                  description: >-
                    An ISO date in the selected historic period; omit or pass
                    null for the current period.
                fieldKeys:
                  type: array
                  minItems: 1
                  maxItems: 5
                  items:
                    type: string
                    enum:
                      - userId
                      - username
                      - email
                      - externalUserId
                      - displayName
                format:
                  type: string
                  enum:
                    - rankings
                    - exclusions
      responses:
        '200':
          description: CSV from one fixed snapshot
          content:
            text/csv:
              schema:
                type: string
          headers:
            X-Export-Bytes:
              schema:
                type: integer
              description: Expected UTF-8 file size; reject a shorter download.
            X-Export-Rows:
              schema:
                type: integer
              description: Number of participants in the CSV.
            X-Exported-At:
              schema:
                type: string
                format: date-time
              description: Server export-start time.
        '400':
          description: Invalid input or inactive period
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeaderboardExportError'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeaderboardExportError'
        '403':
          description: Insufficient permissions or inaccessible community
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeaderboardExportError'
        '404':
          description: Leaderboard not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeaderboardExportError'
        '413':
          description: Export exceeds a row, byte or input limit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeaderboardExportError'
        '500':
          description: Preparation failed or timed out; retry the export
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeaderboardExportError'
      security:
        - AdminUserAccessToken: []
components:
  schemas:
    LeaderboardExportError:
      type: object
      required:
        - error
      properties:
        error:
          type: string
  securitySchemes:
    ApiToken:
      type: apiKey
      in: header
      name: x-api-token
    AdminUserAccessToken:
      type: apiKey
      in: header
      name: x-admin-user-access-token
      description: >-
        An admin user access token. Service-only API keys cannot download user
        identities.

````