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

# Simulate gateway budgets

> Returns the budgets that would apply to a hypothetical user/team/model/metadata selection, with current usage.



## OpenAPI

````yaml /openapi.json post /api/svc/v1/llm-gateway/budgets/simulate
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/simulate:
    post:
      tags:
        - LLM Gateway Budgets
      summary: Simulate gateway budgets
      description: >-
        Returns the budgets that would apply to a hypothetical
        user/team/model/metadata selection, with current usage.
      operationId: GatewayBudget.simulate
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimulateBudgetRequest'
      responses:
        '200':
          description: The budgets matching the selection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BudgetUsageResponse'
      security:
        - jwt: []
components:
  schemas:
    SimulateBudgetRequest:
      type: object
      properties:
        user:
          type: string
          description: User email to simulate as.
          example: alice@team-1.com
        virtual_account:
          type: string
          description: >-
            Virtual account slug to simulate as. Use this instead of `user` for
            virtual-account budgets.
          example: my-virtual-account
        team:
          type: string
          description: >-
            Single team to simulate membership of. Use `teams` to pass multiple
            teams.
          example: engineering
        teams:
          description: >-
            All teams the simulated user belongs to. Merged with `team` when
            both are provided.
          example:
            - engineering
            - platform
          type: array
          items:
            type: string
        model:
          type: string
          description: Model to simulate.
          example: openai/gpt-4o
        metadata:
          type: object
          description: Request metadata key/value pairs to simulate.
          additionalProperties:
            type: string
          example:
            environment: production
            cost_centre: cc-engineering
      title: SimulateBudgetRequest
      x-fern-type-name: SimulateBudgetRequest
    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

````