openapi: 3.2.0
info:
  title: LiteLLM budget management API
  description: 'Proxy Server to call 100+ LLMs in the OpenAI format. **Customize Swagger Docs**


    👉 ```LiteLLM Admin Panel on /ui```. Create, Edit Keys with SSO. Having issues? Try ```Fallback Login```


    💸 ```LiteLLM Model Cost Map```.


    🔎 ```LiteLLM Model Hub```. See available models on the proxy. **Docs**'
  version: 1.102.1
tags:
- name: budget management
paths:
  /management/v1/budgets:
    get:
      tags:
      - budget management
      summary: List Budgets
      description: 'The budgets defined on this proxy, paged, sortable and filterable, for the

        Budgets page.


        Readable by a proxy admin or an admin viewer; anyone else is refused 403. The

        older `/budget/list` answers with the whole table as a bare array and has no

        way to page, sort or filter it.


        `sort` takes a comma-separated list of `budget_id`, `max_budget`, `tpm_limit`,

        `rpm_limit` or `created_at`, each optionally prefixed with `-` for descending,

        and defaults to `-created_at`. `budget_id` is appended to every sort as the

        tiebreaker. `q` is a case-insensitive substring match on `budget_id`.

        `page_size` defaults to 50 and is capped at 100. Filters are

        `filter[budget_duration][in|is_null]`, `filter[max_budget][gte|lte|is_null]`

        and `filter[created_at][gte|lte]`.


        Example curl:

        ```

        curl --location --globoff ''http://0.0.0.0:4000/management/v1/budgets?sort=-max_budget&filter[budget_duration][in]=7d,30d&page_size=25'' --header ''Authorization: Bearer sk-1234''

        ```'
      operationId: list_budgets_management_v1_budgets_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListResponse_BudgetListItem_'
      security:
      - APIKeyHeader: []
  /budget/new:
    post:
      tags:
      - budget management
      summary: New Budget
      description: 'Create a new budget object. Can apply this to teams, orgs, end-users, keys.


        Parameters:

        - budget_duration: Optional[str] - Budget reset period ("30d", "1h", etc.)

        - budget_id: Optional[str] - The id of the budget. If not provided, a new id will be generated.

        - max_budget: Optional[float] - The max budget for the budget.

        - soft_budget: Optional[float] - The soft budget for the budget.

        - max_parallel_requests: Optional[int] - The max number of parallel requests for the budget.

        - tpm_limit: Optional[int] - The tokens per minute limit for the budget.

        - rpm_limit: Optional[int] - The requests per minute limit for the budget.

        - model_max_budget: Optional[dict] - Specify max budget for a given model. Example: {"openai/gpt-4o-mini": {"max_budget": 100.0, "budget_duration": "1d", "tpm_limit": 100000, "rpm_limit": 100000}}

        - budget_reset_at: Optional[datetime] - Datetime when the initial budget is reset. Default is now.'
      operationId: new_budget_budget_new_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BudgetNewRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
  /budget/update:
    post:
      tags:
      - budget management
      summary: Update Budget
      description: 'Update an existing budget object.


        Parameters:

        - budget_duration: Optional[str] - Budget reset period ("30d", "1h", etc.)

        - budget_id: Optional[str] - The id of the budget. If not provided, a new id will be generated.

        - max_budget: Optional[float] - The max budget for the budget.

        - soft_budget: Optional[float] - The soft budget for the budget.

        - max_parallel_requests: Optional[int] - The max number of parallel requests for the budget.

        - tpm_limit: Optional[int] - The tokens per minute limit for the budget.

        - rpm_limit: Optional[int] - The requests per minute limit for the budget.

        - model_max_budget: Optional[dict] - Specify max budget for a given model. Example: {"openai/gpt-4o-mini": {"max_budget": 100.0, "budget_duration": "1d", "tpm_limit": 100000, "rpm_limit": 100000}}

        - budget_reset_at: Optional[datetime] - Update the Datetime when the budget was last reset.'
      operationId: update_budget_budget_update_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BudgetNewRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
  /budget/info:
    post:
      tags:
      - budget management
      summary: Info Budget
      description: 'Get the budget id specific information


        Parameters:

        - budgets: List[str] - The list of budget ids to get information for'
      operationId: info_budget_budget_info_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BudgetRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
  /budget/settings:
    get:
      tags:
      - budget management
      summary: Budget Settings
      description: 'Get list of configurable params + current value for a budget item + description of each field


        Used on Admin UI.


        Query Parameters:

        - budget_id: str - The budget id to get information for'
      operationId: budget_settings_budget_settings_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: budget_id
        in: query
        required: true
        schema:
          type: string
          title: Budget Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /budget/list:
    get:
      tags:
      - budget management
      summary: List Budget
      description: List all the created budgets in proxy db. Used on Admin UI.
      operationId: list_budget_budget_list_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
      - APIKeyHeader: []
  /budget/delete:
    post:
      tags:
      - budget management
      summary: Delete Budget
      description: 'Delete budget


        Parameters:

        - id: str - The budget id to delete'
      operationId: delete_budget_budget_delete_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BudgetDeleteRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
components:
  schemas:
    BudgetConfig:
      properties:
        max_budget:
          anyOf:
          - type: number
          - type: 'null'
          title: Max Budget
        budget_duration:
          anyOf:
          - type: string
          - type: 'null'
          title: Budget Duration
        tpm_limit:
          anyOf:
          - type: integer
          - type: 'null'
          title: Tpm Limit
        rpm_limit:
          anyOf:
          - type: integer
          - type: 'null'
          title: Rpm Limit
      type: object
      title: BudgetConfig
    BudgetListItem:
      properties:
        budget_id:
          type: string
          title: Budget Id
        max_budget:
          anyOf:
          - type: number
          - type: 'null'
          title: Max Budget
        soft_budget:
          anyOf:
          - type: number
          - type: 'null'
          title: Soft Budget
        tpm_limit:
          anyOf:
          - type: integer
          - type: 'null'
          title: Tpm Limit
        rpm_limit:
          anyOf:
          - type: integer
          - type: 'null'
          title: Rpm Limit
        budget_duration:
          anyOf:
          - type: string
          - type: 'null'
          title: Budget Duration
        budget_reset_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Budget Reset At
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
      - budget_id
      - created_at
      - updated_at
      title: BudgetListItem
      description: 'One budget as the Budgets page reads it, and as it comes back off the table.


        Validating the raw row through here is what makes `tpm_limit` / `rpm_limit`

        numbers: they are `BigInt?` in the schema, which the query engine hands back as

        decimal strings, and a quoted "60000" breaks arithmetic in the dashboard.'
    BudgetDeleteRequest:
      properties:
        id:
          type: string
          title: Id
      type: object
      required:
      - id
      title: BudgetDeleteRequest
    ListLinks:
      properties:
        self:
          type: string
          title: Self
        first:
          type: string
          title: First
        prev:
          anyOf:
          - type: string
          - type: 'null'
          title: Prev
        next:
          anyOf:
          - type: string
          - type: 'null'
          title: Next
        last:
          type: string
          title: Last
      type: object
      required:
      - self
      - first
      - last
      title: ListLinks
      description: Page-mode counterpart to `PageLinks`. `first`/`last` are knowable here because the total count is.
    ListMeta:
      properties:
        total_count:
          type: integer
          title: Total Count
        page:
          type: integer
          title: Page
        page_size:
          type: integer
          title: Page Size
        total_pages:
          type: integer
          title: Total Pages
      type: object
      required:
      - total_count
      - page
      - page_size
      - total_pages
      title: ListMeta
      description: 'Page-mode counterpart to `PageMeta`: an entity list pays for the COUNT(*) so the table can show a page count.'
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    BudgetNewRequest:
      properties:
        budget_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Budget Id
          description: The unique budget id.
        max_budget:
          anyOf:
          - type: number
          - type: 'null'
          title: Max Budget
          description: Requests will fail if this budget (in USD) is exceeded.
        soft_budget:
          anyOf:
          - type: number
          - type: 'null'
          title: Soft Budget
          description: Requests will NOT fail if this is exceeded. Will fire alerting though.
        max_parallel_requests:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Parallel Requests
          description: Max concurrent requests allowed for this budget id.
        tpm_limit:
          anyOf:
          - type: integer
          - type: 'null'
          title: Tpm Limit
          description: Max tokens per minute, allowed for this budget id.
        rpm_limit:
          anyOf:
          - type: integer
          - type: 'null'
          title: Rpm Limit
          description: Max requests per minute, allowed for this budget id.
        budget_duration:
          anyOf:
          - type: string
          - type: 'null'
          title: Budget Duration
          description: Max duration budget should be set for (e.g. '1hr', '1d', '28d')
        model_max_budget:
          anyOf:
          - additionalProperties:
              $ref: '#/components/schemas/BudgetConfig'
            type: object
          - type: 'null'
          title: Model Max Budget
          description: 'Max budget for each model (e.g. {''gpt-4o'': {''max_budget'': ''0.0000001'', ''budget_duration'': ''1d'', ''tpm_limit'': 1000, ''rpm_limit'': 1000}})'
        budget_reset_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Budget Reset At
          description: Datetime when the budget is reset
      type: object
      title: BudgetNewRequest
    ListResponse_BudgetListItem_:
      properties:
        data:
          items:
            $ref: '#/components/schemas/BudgetListItem'
          type: array
          title: Data
        meta:
          $ref: '#/components/schemas/ListMeta'
        links:
          $ref: '#/components/schemas/ListLinks'
      type: object
      required:
      - data
      - meta
      - links
      title: ListResponse[BudgetListItem]
    BudgetRequest:
      properties:
        budgets:
          items:
            type: string
          type: array
          title: Budgets
      type: object
      required:
      - budgets
      title: BudgetRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      description: Bearer token
      in: header
      name: x-litellm-api-key