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

# Get a gateway budget leaderboard

> Returns the top spenders for a budget in its applies_to dimension, for the configured period. Aggregate budgets return a single whole-budget entity (entity: null).



## OpenAPI

````yaml /openapi.json get /api/svc/v1/llm-gateway/budgets/{id}/leaderboard
openapi: 3.1.0
info:
  title: TrueFoundry API
  description: API for TrueFoundry
  version: 0.1.0
  contact: {}
servers:
  - url: https://{controlPlaneURL}
    variables:
      controlPlaneURL:
        default: app.truefoundry.com
        description: Control Plane URL
security: []
tags:
  - name: Agent
  - name: Agent Skills
  - name: Applications
  - name: Metrics
  - name: Apply
  - name: Artifacts
  - name: Audit Logs
  - name: Clusters
  - name: Jobs
  - name: LLM Gateway Budgets
  - name: Logs
  - name: MCP Registry
  - name: MCP Servers V2
  - name: MLRepos
  - name: Model Deployments
  - name: Models
  - name: Personal Access Tokens
  - name: Prompts
  - name: Provider Integrations
  - name: SCIM v2
  - name: Secret Groups
  - name: Secrets
  - name: Teams
  - name: Traces
  - name: Users
  - name: Virtual Accounts
  - name: Role Bindings
  - name: Workspaces
  - name: Provider Accounts
paths:
  /api/svc/v1/llm-gateway/budgets/{id}/leaderboard:
    get:
      tags:
        - LLM Gateway Budgets
      summary: Get a gateway budget leaderboard
      description: >-
        Returns the top spenders for a budget in its applies_to dimension, for
        the configured period. Aggregate budgets return a single whole-budget
        entity (entity: null).
      operationId: GatewayBudget.leaderboard
      parameters:
        - name: id
          required: true
          in: path
          description: The budget id to retrieve or delete.
          schema:
            type: string
        - name: limit
          required: false
          in: query
          description: >-
            Maximum number of entries to return. Defaults to 500 and is capped
            at 500.
          schema:
            example: 50
            type: number
      responses:
        '200':
          description: The budget leaderboard.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BudgetUsageResponse'
        '404':
          description: No budget with that id exists for the tenant.
      security:
        - jwt: []
components:
  schemas:
    BudgetUsageResponse:
      type: object
      properties:
        matched:
          description: Budgets that apply, with current usage.
          type: array
          items:
            $ref: '#/components/schemas/BudgetUsageEntry'
      required:
        - matched
      title: BudgetUsageResponse
      x-fern-type-name: BudgetUsageResponse
    BudgetUsageEntry:
      type: object
      properties:
        name:
          type: string
          description: Human-readable name of the budget.
        type:
          type: string
          enum:
            - tenant-budget-config
            - team-budget-config
          description: Budget type.
        team_name:
          type: string
          nullable: true
          description: Team that owns the budget; null for tenant-budget-config.
        applies_to:
          type: string
          description: >-
            How counters are partitioned (per-user, per-model,
            per-virtual-account, aggregate, or metadata:<key>).
        mode:
          type: string
          enum:
            - enforce
            - audit
            - soft_enforce
          description: Budget mode.
        entities:
          description: >-
            Per-entity usage for this budget. For my-usage and simulate this
            contains a single entity; leaderboard-style endpoints may return
            many.
          type: array
          items:
            $ref: '#/components/schemas/BudgetEntityUsage'
      required:
        - name
        - type
        - applies_to
        - mode
        - entities
      title: BudgetUsageEntry
      x-fern-type-name: BudgetUsageEntry
    BudgetEntityUsage:
      type: object
      properties:
        entity:
          type: string
          nullable: true
          description: Entity counter this usage maps to; null for aggregate budgets.
          example: '{user:alice@co.com}'
        periods:
          type: object
          description: >-
            Per-period usage keyed by period (cost_per_day, cost_per_month,
            ...).
          additionalProperties:
            $ref: '#/components/schemas/PeriodUsage'
      required:
        - periods
      title: BudgetEntityUsage
      x-fern-type-name: BudgetEntityUsage
    PeriodUsage:
      type: object
      properties:
        limit:
          type: number
          description: Resolved (override-aware) cost limit for the period.
        used:
          type: number
          description: Cost used in the current window of the period.
        percentage:
          type: number
          description: Usage as a percentage of the limit, capped at 100.
        start:
          type: number
          description: Current window start, Unix epoch seconds (UTC).
        end:
          type: number
          description: Current window end, Unix epoch seconds (UTC, inclusive).
      required:
        - limit
        - used
        - percentage
        - start
        - end
      title: PeriodUsage
      x-fern-type-name: PeriodUsage
  securitySchemes:
    jwt:
      type: http
      scheme: bearer
      bearerFormat: JWT

````