Cast AI Budgets API

openapi: 3.2.0
info:
  title: Reporting Budgets API
  version: 0.0.1
  description: Manages organization cost budgets and threshold notifications.
servers:
- url: https://api.cast.ai/
  description: US endpoint
- url: https://api.eu.cast.ai/
  description: EU endpoint
security:
- BearerAuth: []
- ApiKeyAuth: []
tags:
- name: BudgetsAPI
  description: Manages organization cost budgets and threshold notifications.
paths:
  /reporting/v1beta/organizations/{organizationId}/budgets:
    post:
      tags:
      - BudgetsAPI
      summary: Creates a new budget
      description: Creates a new budget for the organization.
      operationId: BudgetsAPI_CreateBudget
      parameters:
      - name: organizationId
        in: path
        description: Organization ID.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Budget'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Budget'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
    get:
      tags:
      - BudgetsAPI
      summary: Returns all of the organization's budgets
      description: Returns all of the organization's budgets in one call.
      operationId: BudgetsAPI_ListBudgets
      parameters:
      - name: organizationId
        in: path
        description: Organization ID.
        required: true
        schema:
          type: string
      - name: includeDisabled
        in: query
        description: Include paused (disabled) budgets in the list. Defaults to true.
        schema:
          type: boolean
      - name: includeThresholds
        in: query
        description: "Include thresholds (percent, recipients, alert fire state) in each returned budget if true.\n Defaults to false."
        schema:
          type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListBudgetsResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
  /reporting/v1beta/organizations/{organizationId}/budgets/{budgetId}:
    delete:
      tags:
      - BudgetsAPI
      summary: Permanently deletes a budget
      description: Permanently deletes a budget.
      operationId: BudgetsAPI_DeleteBudget
      parameters:
      - name: organizationId
        in: path
        description: Organization ID.
        required: true
        schema:
          type: string
      - name: budgetId
        in: path
        description: Budget ID.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content: {}
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
    get:
      tags:
      - BudgetsAPI
      summary: Returns a budget by ID
      description: Returns a single budget by ID.
      operationId: BudgetsAPI_GetBudget
      parameters:
      - name: organizationId
        in: path
        description: Organization ID.
        required: true
        schema:
          type: string
      - name: budgetId
        in: path
        description: Budget ID.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Budget'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
    patch:
      tags:
      - BudgetsAPI
      summary: Replaces a budget
      description: Full replacement.
      operationId: BudgetsAPI_UpdateBudget
      parameters:
      - name: organizationId
        in: path
        description: Organization ID.
        required: true
        schema:
          type: string
      - name: budgetId
        in: path
        description: Budget ID.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Budget'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Budget'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
  /reporting/v1beta/organizations/{organizationId}/budgets:cost-preview:
    post:
      tags:
      - BudgetsAPI
      summary: Returns a scope's actual cost over the first viable period of the given window
      description: 'Returns the actual cost of a scope over a fixed trailing 30-day window.

        Powers the budget create-form tooltip; reads the same cost pipeline the

        evaluator compares against. Window is fixed server-side (last 30 days).'
      operationId: BudgetsAPI_PreviewBudgetCost
      parameters:
      - name: organizationId
        in: path
        description: Organization ID.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PreviewBudgetCostRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreviewBudgetCostResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
components:
  schemas:
    Status:
      type: object
      properties:
        code:
          type: integer
          description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
          format: int32
        message:
          type: string
          description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
        details:
          type: array
          items:
            $ref: '#/components/schemas/GoogleProtobufAny'
          description: A list of messages that carry the error details.  There is a common set of message types for APIs to use.
      description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).'
    BudgetWindow_Trailing:
      required:
      - value
      - unit
      type: object
      properties:
        value:
          type: integer
          description: Window size in the given unit.
          format: int32
        unit:
          enum:
          - UNIT_UNSPECIFIED
          - UNIT_DAYS
          - UNIT_HOURS
          type: string
          description: Unit of the window size.
          format: enum
      description: Rolling window looking back from now.
    ListBudgetsResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Budget'
          description: List of budgets, ordered by name.
      description: Response for listing budgets.
    BudgetStatus:
      type: object
      properties:
        currentCost:
          type: string
          description: Cost accumulated in the current window, decimal encoded as string (e.g. "1450.32").
        consumedPercent:
          type: number
          description: current_cost as a percentage of budget_cost.
          format: double
      description: "Live, computed status of a budget in its current window. Not stored — derived on every read\n from the same window math and ClickHouse spend query the evaluator uses."
    BudgetScope_OrganizationScope:
      type: object
      properties:
        clusterIds:
          type: array
          items:
            type: string
          description: Optional cluster filter; organization-wide when empty.
      description: Organization scope filters spend to the given clusters; empty means the whole organization.
    BudgetScope_AllocationGroupScope:
      required:
      - allocationGroupId
      type: object
      properties:
        allocationGroupId:
          type: string
          description: Allocation group ID.
      description: Allocation group scope.
    BudgetWindow:
      type: object
      properties:
        monthlyReset:
          allOf:
          - $ref: '#/components/schemas/BudgetWindow_MonthlyReset'
          description: Resets monthly on the given day.
        trailing:
          allOf:
          - $ref: '#/components/schemas/BudgetWindow_Trailing'
          description: Trailing window of the given size.
      description: Measurement window over which budget spend is accumulated.
    BudgetScope_ClusterScope:
      required:
      - clusterId
      type: object
      properties:
        clusterId:
          type: string
          description: Cluster ID.
      description: Single cluster scope.
    BudgetScope_NamespaceScope:
      required:
      - clusterId
      - namespace
      type: object
      properties:
        clusterId:
          type: string
          description: Cluster ID.
        namespace:
          type: string
          description: Namespace name.
      description: Namespace within a cluster.
    BudgetScope_WorkloadScope:
      required:
      - clusterId
      - namespace
      - workloadName
      - workloadKind
      type: object
      properties:
        clusterId:
          type: string
          description: Cluster ID.
        namespace:
          type: string
          description: Namespace of the workload.
        workloadName:
          type: string
          description: Workload name (top-level owner).
        workloadKind:
          type: string
          description: Workload kind (top-level owner kind, e.g. Deployment, StatefulSet).
      description: Single workload within a cluster.
    BudgetWindow_MonthlyReset:
      required:
      - resetDay
      type: object
      properties:
        resetDay:
          type: integer
          description: Day of month the window resets (clamped to the last day of shorter months).
          format: int32
      description: Window anchored on a day of month, resetting monthly.
    Budget:
      required:
      - name
      - scope
      - budgetCost
      - window
      - enabled
      - timeZone
      type: object
      properties:
        id:
          readOnly: true
          type: string
          description: Budget ID.
        name:
          type: string
          description: Human-readable budget name.
        scope:
          allOf:
          - $ref: '#/components/schemas/BudgetScope'
          description: Entity whose spend this budget tracks.
        budgetCost:
          type: string
          description: Budget cost, decimal encoded as string (e.g. "1234.56").
        window:
          allOf:
          - $ref: '#/components/schemas/BudgetWindow'
          description: Measurement window over which spend is accumulated.
        thresholds:
          type: array
          items:
            $ref: '#/components/schemas/BudgetThreshold'
          description: "Alert thresholds. Each threshold fires an email to its own recipients when spend reaches its percent of budget_cost.\n Omitted from List responses when include_thresholds is false."
        enabled:
          type: boolean
          description: Whether the budget is evaluated. Paused budgets keep their configuration but do not fire.
        createdBy:
          readOnly: true
          type: string
          description: Identity of the budget creator.
        createTime:
          readOnly: true
          type: string
          description: When the budget was created.
          format: date-time
        updateTime:
          readOnly: true
          type: string
          description: When the budget was last modified.
          format: date-time
        status:
          readOnly: true
          allOf:
          - $ref: '#/components/schemas/BudgetStatus'
          description: Computed current-window status. Populated on Get and List responses; ignored on writes.
        timeZone:
          type: string
          description: IANA timezone (e.g. "America/New_York") used to derive window boundaries.
        useListingPrices:
          type: boolean
          description: "When true, spend is computed using listing (retail) prices; when false,\n real prices are used. Defaults to false."
        includeIdleCosts:
          type: boolean
          description: "When true, idle cluster resource cost attributed to the scope is included\n in spend. Supported only for workload, namespace and allocation-group\n scopes; Defaults to false."
      description: A single budget with its scope, window and notification configuration.
    PreviewBudgetCostRequest:
      required:
      - organizationId
      - scope
      - window
      - timeZone
      type: object
      properties:
        organizationId:
          type: string
          description: Organization ID.
        scope:
          allOf:
          - $ref: '#/components/schemas/BudgetScope'
          description: Scope to price.
        window:
          allOf:
          - $ref: '#/components/schemas/BudgetWindow'
          description: "Window over which the scope cost is evaluated. The cost is computed over\n the first viable period of the window: the current period since the last\n reset for monthly-reset windows, or a full trailing window looking back\n from evaluation time."
        timeZone:
          type: string
          description: IANA timezone used to derive window boundaries for the preview.
        useListingPrices:
          type: boolean
          description: "When true, spend is computed using listing (retail) prices; when false,\n real prices are used. Defaults to false."
        includeIdleCosts:
          type: boolean
          description: "When true, idle cluster resource cost attributed to the scope is included.\n Supported only for workload, namespace and allocation-group scopes."
      description: Request for a scope cost preview.
    BudgetThreshold:
      required:
      - percent
      - recipientUserIds
      type: object
      properties:
        percent:
          type: integer
          description: Percentage (1..100) of budget_cost at which this threshold fires.
          format: int32
        recipientUserIds:
          type: array
          items:
            type: string
          description: User IDs notified when this threshold is crossed.
        lastFiredTime:
          readOnly: true
          type: string
          description: When this threshold last fired in the current window; unset while spend is below it.
          format: date-time
      description: A single alert threshold with its own recipients and fire state.
    BudgetScope:
      type: object
      properties:
        organization:
          allOf:
          - $ref: '#/components/schemas/BudgetScope_OrganizationScope'
          description: Whole organization, optionally filtered to a set of clusters.
        cluster:
          allOf:
          - $ref: '#/components/schemas/BudgetScope_ClusterScope'
          description: A single cluster.
        namespace:
          allOf:
          - $ref: '#/components/schemas/BudgetScope_NamespaceScope'
          description: A namespace within a cluster.
        workload:
          allOf:
          - $ref: '#/components/schemas/BudgetScope_WorkloadScope'
          description: A single workload within a cluster.
        allocationGroup:
          allOf:
          - $ref: '#/components/schemas/BudgetScope_AllocationGroupScope'
          description: An allocation group.
      description: Entity whose spend a budget tracks.
    PreviewBudgetCostResponse:
      type: object
      properties:
        fromTime:
          type: string
          description: Inclusive window start of the evaluated period.
          format: date-time
        toTime:
          type: string
          description: Exclusive window end (evaluation time).
          format: date-time
        spend:
          type: string
          description: Actual USD spend of the scope across the window, decimal string.
      description: Scope cost preview over the first viable period of the requested window.
    GoogleProtobufAny:
      type: object
      properties:
        '@type':
          type: string
          description: The type of the serialized message.
      additionalProperties: true
      description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
x-provenance:
  method: searched
  source: https://docs.cast.ai/reference
  harvested: '2026-10-20'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://docs.cast.ai/reference/budgetsapi_createbudget.md
  - https://docs.cast.ai/reference/budgetsapi_deletebudget.md
  - https://docs.cast.ai/reference/budgetsapi_getbudget.md
  - https://docs.cast.ai/reference/budgetsapi_listbudgets.md
  - https://docs.cast.ai/reference/budgetsapi_previewbudgetcost.md
  - https://docs.cast.ai/reference/budgetsapi_updatebudget.md
  - https://docs.cast.ai/reference/clusterscoreapi_getclusterrestrictiondetails.md
  - https://docs.cast.ai/reference/clusterscoreapi_listclusterrestrictions.md
  - https://docs.cast.ai/reference/containerlivemigrationapi_getcontainerlivemigrationdetail.md
  - https://docs.cast.ai/reference/containerlivemigrationapi_getcontainerlivemigrationsummary.md
  - https://docs.cast.ai/reference/containerlivemigrationapi_listcontainerlivemigrationevents.md
  - https://docs.cast.ai/reference/containerlivemigrationapi_listcontainerlivemigrationfiltervalues.md
  - https://docs.cast.ai/reference/containerlivemigrationapi_listcontainerlivemigrationincompatibleworkloads.md
  - https://docs.cast.ai/reference/containerlivemigrationapi_listcontainerlivemigrations.md
  - https://docs.cast.ai/reference/containerlivemigrationapi_listcontainerlivemigrationworkloads.md
  - https://docs.cast.ai/reference/instanceapi_getinstancessummary.md
  - https://docs.cast.ai/reference/instanceapi_listinstances.md
  - https://docs.cast.ai/reference/nodeconditioneventsapi_listnodeconditionevents.md
  - https://docs.cast.ai/reference/nodetemplateapi_getspotinterruptionpredictionperformancesummary.md
  - https://docs.cast.ai/reference/nodetemplateapi_listnodetemplatesmetrics.md
  - https://docs.cast.ai/reference/nodetemplateapi_listnodetemplatesmetricsfiltered.md
  - https://docs.cast.ai/reference/nodetemplateapi_listspotinterruptionpredictionperformancemetrics.md
  - https://docs.cast.ai/reference/optimizationapi_runclusteroptimizationsreport.md
  - https://docs.cast.ai/reference/reliabilitymetricsapi_getclusterreliabilitymetrics.md
  - https://docs.cast.ai/reference/reliabilitymetricsapi_getorganizationclustersreliabilitymetrics.md
  - https://docs.cast.ai/reference/valuerealizationapi_getbaselineparams.md
  - https://docs.cast.ai/reference/valuerealizationapi_recalculatebaselineparams.md
  - https://docs.cast.ai/reference/valuerealizationapi_runclustersvaluerealizationreport.md
  - https://docs.cast.ai/reference/valuerealizationapi_runvaluerealizationtimelinereport.md
  - https://docs.cast.ai/reference/valuerealizationapi_runworkloadsvaluerealizationreport.md
  - https://docs.cast.ai/reference/valuerealizationapi_updatebaselineparams.md
  merge:
    pages: 31
    deduped: 179
    conflicts_kept_first: 0