Cast AI Rebalancing Config API

openapi: 3.2.0
info:
  title: Cluster Autoscaler Rebalancing Config API
  version: 0.0.1
  description: 'RebalancingConfigAPI provides read-only endpoints for the rebalancing configuration UI.

    These endpoints support pagination, filtering, and sorting to handle large clusters.'
servers:
- url: https://api.cast.ai/
  description: US endpoint
- url: https://api.eu.cast.ai/
  description: EU endpoint
security:
- BearerAuth: []
- ApiKeyAuth: []
tags:
- name: RebalancingConfigAPI
  description: 'RebalancingConfigAPI provides read-only endpoints for the rebalancing configuration UI.

    These endpoints support pagination, filtering, and sorting to handle large clusters.'
paths:
  ? /cluster-autoscaler/v1/organizations/{organizationId}/clusters/{clusterId}/rebalancing-configurations:searchNodeFilterValues
  : get:
      tags:
      - RebalancingConfigAPI
      summary: Search values for a node filter type
      description: 'Searches available values for a specific node filter type.

        Supports pagination and keyword search for typeahead.'
      operationId: RebalancingConfigAPI_SearchRebalancingNodeFilterValues
      parameters:
      - name: organizationId
        in: path
        description: Organization ID.
        required: true
        schema:
          type: string
      - name: clusterId
        in: path
        description: Cluster ID.
        required: true
        schema:
          type: string
      - name: field
        in: query
        description: The filter type to retrieve values for.
        schema:
          enum:
          - TYPE_UNSPECIFIED
          - NAME
          - CAST_NODE_ID
          - STATUS
          - RESOURCE_OFFERING
          - LABEL
          - NODE_TEMPLATE
          - INSTANCE_TYPE
          - AVAILABILITY_ZONE
          - ADDED_BY
          - REMOVAL_DISABLED
          - UNSCHEDULABLE
          - CONFIG
          - CONFIG_VERSION
          - OS
          type: string
          format: enum
      - name: keyword
        in: query
        description: Keyword to search/filter the values (for typeahead).
        schema:
          type: string
      - name: page.limit
        in: query
        description: Defines the number of items that should be returned
        schema:
          type: string
      - name: page.cursor
        in: query
        description: "Cursor that defines token indicating where to start the next page.\n Empty value indicates to start from beginning of the dataset."
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchRebalancingNodeFilterValuesResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
  /cluster-autoscaler/v1/organizations/{organizationId}/clusters/{clusterId}/rebalancing-configurations:searchNodeFilters:
    get:
      tags:
      - RebalancingConfigAPI
      summary: Search available node filter types
      description: Searches available node filter types for this cluster.
      operationId: RebalancingConfigAPI_SearchRebalancingNodeFilters
      parameters:
      - name: organizationId
        in: path
        description: Organization ID.
        required: true
        schema:
          type: string
      - name: clusterId
        in: path
        description: Cluster ID.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchRebalancingNodeFiltersResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
  /cluster-autoscaler/v1/organizations/{organizationId}/clusters/{clusterId}/rebalancing-configurations:searchNodes:
    post:
      tags:
      - RebalancingConfigAPI
      summary: Search cluster nodes for rebalancing configuration
      description: Searches cluster nodes for the rebalancing configuration view.
      operationId: RebalancingConfigAPI_SearchRebalancingNodes
      parameters:
      - name: organizationId
        in: path
        description: Organization ID.
        required: true
        schema:
          type: string
      - name: clusterId
        in: path
        description: Cluster ID.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRebalancingNodesRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchRebalancingNodesResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
  /cluster-autoscaler/v1/organizations/{organizationId}/clusters/{clusterId}/rebalancing-configurations:searchWorkloads:
    post:
      tags:
      - RebalancingConfigAPI
      summary: Search cluster workloads for rebalancing configuration
      description: Searches cluster workloads for the rebalancing configuration view.
      operationId: RebalancingConfigAPI_SearchRebalancingWorkloads
      parameters:
      - name: organizationId
        in: path
        description: Organization ID.
        required: true
        schema:
          type: string
      - name: clusterId
        in: path
        description: Cluster ID.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRebalancingWorkloadsRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchRebalancingWorkloadsResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
components:
  schemas:
    RebalancingNode:
      type: object
      properties:
        id:
          allOf:
          - $ref: '#/components/schemas/NodeId'
          description: Composite node identifier.
        instanceType:
          type: string
          description: Instance type (e.g. m5.xlarge).
        resourceOffering:
          enum:
          - RESOURCE_OFFERING_UNSPECIFIED
          - SPOT
          - ON_DEMAND
          - FALLBACK
          type: string
          description: Resource offering type.
          format: enum
        pricing:
          allOf:
          - $ref: '#/components/schemas/NodePricing'
          description: Pricing information including discounts.
        components:
          type: array
          items:
            $ref: '#/components/schemas/NodeComponent'
          description: Node components with resource utilization and per-component pricing.
        workloads:
          allOf:
          - $ref: '#/components/schemas/NodeWorkloadSummary'
          description: Workload summary for this node.
        status:
          enum:
          - STATUS_UNSPECIFIED
          - READY
          - AGGRESSIVE_ONLY
          - NOT_READY
          type: string
          description: Rebalancing status of this node.
          format: enum
        issues:
          allOf:
          - $ref: '#/components/schemas/NodeIssues'
          description: Issues affecting this node, separated by source.
      description: A cluster node in the rebalancing context.
    Sort:
      type: object
      properties:
        field:
          type: string
          description: The field name to order by. Nested fields can be specified by using a dot (e.g. user.name).
        order:
          enum:
          - ASC
          - asc
          - DESC
          - desc
          type: string
          description: The order of returned items. Default is ASC.
          format: enum
      description: Specifies the sorting of a list of items.
    SearchRebalancingWorkloadsRequest:
      required:
      - organizationId
      - clusterId
      type: object
      properties:
        organizationId:
          type: string
          description: Organization ID.
        clusterId:
          type: string
          description: Cluster ID.
        page:
          allOf:
          - $ref: '#/components/schemas/Page'
          description: Pagination parameters.
        sort:
          type: array
          items:
            $ref: '#/components/schemas/Sort'
          description: "Sort order. Supports multiple fields for tie-breaking.\n Supported fields are: 'name', 'kind', 'pod_count', 'requests.cpu_millicores', 'requests.memory_mib', 'recommendations.cpu_recommended_millicores', 'recommendations.cpu_diff_millicores', 'recommendations.memory_recommended_mib', 'recommendations.memory_diff_mib', 'status'.\n Default: status asc, name asc. Status order: READY, AGGRESSIVE_ONLY, NOT_READY."
        filter:
          allOf:
          - $ref: '#/components/schemas/SearchRebalancingWorkloadsFilter'
          description: Filters.
      description: Request to search rebalancing workloads.
    NodeIssue:
      type: object
      properties:
        kind:
          type: string
          description: Issue kind identifier.
        reason:
          type: string
          description: Human-readable issue description.
        category:
          enum:
          - CATEGORY_UNSPECIFIED
          - REMOVAL_DISABLED
          - CONTROL_PLANE
          - SYSTEM_NODE
          - UNKNOWN_INSTANCE
          - REQUIRED_LABELS
          - REBALANCING_DRAIN_FAILED
          - OTHER
          type: string
          description: Issue category mapping to aggressive mode toggles.
          format: enum
      description: A node-level issue that may prevent rebalancing.
    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.
    NodePricing:
      type: object
      properties:
        basePrice:
          type: string
          description: "Base node price is instance's public price without any discounts and extra attached components.\n Integral components like attached GPUs are already included in the base price."
        totalRegularPrice:
          type: string
          description: Total price of the node without any discounts but including extra attached components.
        discounts:
          type: array
          items:
            $ref: '#/components/schemas/NodeDiscount'
          description: Discounts applied to the node.
        totalPrice:
          type: string
          description: Total price of the node after all discounts and including all extra attached components.
      description: Pricing information for a node.
    RebalancingWorkload:
      type: object
      properties:
        name:
          type: string
          description: Workload name.
        namespace:
          type: string
          description: Kubernetes namespace.
        kind:
          type: string
          description: Workload kind (e.g. Deployment, StatefulSet, DaemonSet).
        podCount:
          type: integer
          description: Total pod count across the cluster.
          format: int32
        requests:
          allOf:
          - $ref: '#/components/schemas/WorkloadRequests'
          description: Current resource requests for this workload.
        status:
          enum:
          - STATUS_UNSPECIFIED
          - READY
          - AGGRESSIVE_ONLY
          - NOT_READY
          type: string
          description: Rebalancing status of this workload.
          format: enum
        issues:
          type: array
          items:
            $ref: '#/components/schemas/WorkloadIssue'
          description: Issues that may prevent rebalancing.
        recommendations:
          allOf:
          - $ref: '#/components/schemas/WorkloadRecommendations'
          description: WOOP resource optimization recommendations. May not be available for all workloads.
        affectedNodes:
          type: array
          items:
            $ref: '#/components/schemas/NodeId'
          description: Nodes this workload runs on.
      description: A cluster workload in the rebalancing context.
    WorkloadIssue:
      type: object
      properties:
        kind:
          type: string
          description: Issue kind identifier.
        description:
          type: string
          description: Human-readable issue description.
        category:
          enum:
          - CATEGORY_UNSPECIFIED
          - LOCAL_PERSISTENT_VOLUME
          - REMOVAL_DISABLED
          - NO_CONTROLLER
          - JOB_POD
          - OTHER
          - PREVENTED_DRAIN
          type: string
          description: Issue category mapping to aggressive mode toggles.
          format: enum
      description: A workload issue that may prevent rebalancing.
    NodeComponent:
      type: object
      properties:
        type:
          enum:
          - TYPE_UNSPECIFIED
          - CPU
          - MEMORY
          - GPU
          type: string
          description: The component type.
          format: enum
        unit:
          enum:
          - UNIT_UNSPECIFIED
          - COUNT
          - MIB
          - GIB
          - MILLI_COUNT
          type: string
          description: Unit of the component amount.
          format: enum
        amount:
          type: integer
          description: Total amount of this component on the node.
          format: int32
        requested:
          type: string
          description: Resource amount requested by workloads (same unit).
        recommended:
          type: string
          description: Resource amount that would be requested if WOOP recommendations were applied (same unit).
        price:
          allOf:
          - $ref: '#/components/schemas/NodeComponent_Price'
          description: Per-unit pricing. May be absent if pricing data is unavailable.
      description: Integral node component combining resource utilization and pricing.
    NodeDiscount_DiscountDetails:
      type: object
      properties:
        id:
          type: string
          description: The discount ID.
      description: Discount engine discount details.
    SearchRebalancingWorkloadsResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/RebalancingWorkload'
          description: List of workloads.
        nextPageCursor:
          type: string
          description: Cursor for the next page. Empty when there are no more pages.
        totalCount:
          type: integer
          description: Total number of workloads matching the filters.
          format: int32
      description: Response with a paginated list of rebalancing workloads.
    NodeComponent_Price:
      type: object
      properties:
        unit:
          enum:
          - UNIT_UNSPECIFIED
          - COUNT
          - MIB
          - GIB
          - MILLI_COUNT
          type: string
          description: The unit of measurement for the price.
          format: enum
        basePricePerUnit:
          type: string
          description: Public price for one unit.
        totalPricePerUnit:
          type: string
          description: Price for one unit after discounts, if any.
      description: Per-unit pricing information.
    SearchRebalancingWorkloadsFilter:
      type: object
      properties:
        fields:
          type: array
          items:
            $ref: '#/components/schemas/WorkloadFilterField'
          description: Filter fields. Multiple fields are ANDed. Values within a field are ORed.
      description: Filter for searching rebalancing workloads.
    FilterField:
      type: object
      properties:
        type:
          enum:
          - TYPE_UNSPECIFIED
          - NAME
          - CAST_NODE_ID
          - STATUS
          - RESOURCE_OFFERING
          - LABEL
          - NODE_TEMPLATE
          - INSTANCE_TYPE
          - AVAILABILITY_ZONE
          - ADDED_BY
          - REMOVAL_DISABLED
          - UNSCHEDULABLE
          - CONFIG
          - CONFIG_VERSION
          - OS
          type: string
          description: The filter type. Must match a type returned by the filters endpoint.
          format: enum
        values:
          type: array
          items:
            type: string
          description: "Values to filter by. For boolean filters use \"true\" or \"false\".\n For labels use \"key=value\" format."
      description: "A generic filter field with a type and a list of values.\n Values within a single field are ORed. Multiple fields are ANDed."
    Page:
      type: object
      properties:
        limit:
          type: string
          description: Defines the number of items that should be returned
        cursor:
          type: string
          description: "Cursor that defines token indicating where to start the next page.\n Empty value indicates to start from beginning of the dataset."
      description: Page defines how many and which fields should be returned.
    FilterValueEntry:
      type: object
      properties:
        value:
          type: string
          description: The filter value.
      description: A filter value entry returned by the filter values endpoint.
    WorkloadFilterField:
      type: object
      properties:
        type:
          enum:
          - TYPE_UNSPECIFIED
          - STATUS
          - NODE_NAME
          type: string
          description: The filter type. Must match a type returned by the workload filters endpoint.
          format: enum
        values:
          type: array
          items:
            type: string
          description: Values to filter by.
      description: "A generic workload filter field with a type and a list of values.\n Values within a single field are ORed. Multiple fields are ANDed."
    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).'
    NodeId:
      type: object
      properties:
        name:
          type: string
          description: Kubernetes node name. Always present.
        castNodeId:
          type: string
          description: CAST AI internal node ID. Only present for CAST AI managed nodes.
      description: Composite node identifier that works across CAST AI and Karpenter clusters.
    SearchRebalancingNodesFilter:
      type: object
      properties:
        fields:
          type: array
          items:
            $ref: '#/components/schemas/FilterField'
          description: Filter fields. Multiple fields are ANDed. Values within a field are ORed.
      description: Filter for searching rebalancing nodes.
    WorkloadRequests:
      type: object
      properties:
        cpuMillicores:
          type: number
          description: Total CPU requests in millicores.
          format: double
        memoryMib:
          type: number
          description: Total memory requests in MiB.
          format: double
      description: Current resource requests for a workload.
    SearchRebalancingNodeFilterValuesResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/FilterValueEntry'
          description: Filter values for the requested type.
        nextPageCursor:
          type: string
          description: Cursor for the next page. Empty when there are no more pages.
        totalCount:
          type: integer
          description: Total number of values matching the keyword.
          format: int32
      description: Response with paginated filter values.
    SearchRebalancingNodeFiltersResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/NodeFilterEntry'
          description: Available filter types.
      description: Response with available node filter types.
    NodeDiscount:
      type: object
      properties:
        type:
          type: string
          description: 'The type of discount. Possible values are: "commitment", "discount".'
        amount:
          type: string
          description: The discount amount.
        commitment:
          allOf:
          - $ref: '#/components/schemas/NodeDiscount_CommitmentDetails'
          description: Commitment type discount details.
        discount:
          allOf:
          - $ref: '#/components/schemas/NodeDiscount_DiscountDetails'
          description: Discount engine type discount details.
      description: Discount applied to a node.
    WorkloadRecommendations:
      type: object
      properties:
        cpuRecommendedMillicores:
          type: number
          description: Recommended CPU in millicores.
          format: double
        cpuDiffMillicores:
          type: number
          description: CPU difference (recommended - current) in millicores.
          format: double
        memoryRecommendedMib:
          type: number
          description: Recommended memory in MiB.
          format: double
        memoryDiffMib:
          type: number
          description: Memory difference (recommended - current) in MiB.
          format: double
      description: WOOP resource optimization recommendations for a workload.
    NodeFilterEntry:
      type: object
      properties:
        type:
          enum:
          - TYPE_UNSPECIFIED
          - NAME
          - CAST_NODE_ID
          - STATUS
          - RESOURCE_OFFERING
          - LABEL
          - NODE_TEMPLATE
          - INSTANCE_TYPE
          - AVAILABILITY_ZONE
          - ADDED_BY
          - REMOVAL_DISABLED
          - UNSCHEDULABLE
          - CONFIG
          - CONFIG_VERSION
          - OS
          type: string
          description: The filter type.
          format: enum
      description: A filter type entry returned by the filters endpoint.
    NodeWorkloadSummary:
      type: object
      properties:
        count:
          type: integer
          description: Total number of workloads on this node.
          format: int32
        problematicCount:
          type: integer
          description: Number of problematic workloads on this node.
          format: int32
      description: Workload summary for a node.
    NodeDiscount_CommitmentDetails:
      type: object
      properties:
        id:
          type: string
          description: The commitment ID.
      description: Commitment discount details.
    SearchRebalancingNodesRequest:
      required:
      - organizationId
      - clusterId
      type: object
      properties:
        organizationId:
          type: string
          description: Organization ID.
        clusterId:
          type: string
          description: Cluster ID.
        page:
          allOf:
          - $ref: '#/components/schemas/Page'
          description: Pagination parameters.
        sort:
          type: array
          items:
            $ref: '#/components/schemas/Sort'
          description: "Sort order. Supports multiple fields for tie-breaking.\n Supported fields are: 'name', 'instance_type', 'resource_offering', 'total_price', 'cpu', 'memory', 'gpu_count', 'workload_count', 'status'.\n Default: status asc, name asc. Status order: READY, AGGRESSIVE_ONLY, NOT_READY."
        filter:
          allOf:
          - $ref: '#/components/schemas/SearchRebalancingNodesFilter'
          description: Filters.
      description: Request to search rebalancing nodes.
    SearchRebalancingNodesResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/RebalancingNode'
          description: List of nodes.
        nextPageCursor:
          type: string
          description: Cursor for the next page. Empty when there are no more pages.
        totalCount:
          type: integer
          description: Total number of nodes matching the filters.
          format: int32
      description: Response with a paginated list of rebalancing nodes.
    NodeIssues:
      type: object
      properties:
        node:
          type: array
          items:
            $ref: '#/components/schemas/NodeIssue'
          description: Issues from node-level checks (control plane, system node, etc.)
        workload:
          type: array
          items:
            enum:
            - CATEGORY_UNSPECIFIED
            - LOCAL_PERSISTENT_VOLUME
            - REMOVAL_DISABLED
            - NO_CONTROLLER
            - JOB_POD
            - OTHER
            - PREVENTED_DRAIN
            type: string
            format: enum
          description: Issues from workloads running on this node (no controller, local PV, etc.)
      description: Issues affecting a node, separated by source.
  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/autoscalinghealthindicatorsapi_listhealthindicators.md
  - https://docs.cast.ai/reference/autoscalingwatchdogapi_reportwatchdogevents.md
  - https://docs.cast.ai/reference/clusteradvisorapi_cancelanalysis.md
  - https://docs.cast.ai/reference/clusteradvisorapi_createanalysis.md
  - https://docs.cast.ai/reference/clusteradvisorapi_getanalysis.md
  - https://docs.cast.ai/reference/clusteradvisorapi_getanalysisvariant.md
  - https://docs.cast.ai/reference/clusteradvisorapi_listanalyses.md
  - https://docs.cast.ai/reference/clusteradvisorapi_listanalysisvariants.md
  - https://docs.cast.ai/reference/hibernationjobsapi_createhibernationjob.md
  - https://docs.cast.ai/reference/hibernationjobsapi_gethibernationjob.md
  - https://docs.cast.ai/reference/hibernationjobsapi_pausecluster.md
  - https://docs.cast.ai/reference/hibernationjobsapi_resumecluster.md
  - https://docs.cast.ai/reference/hibernationschedulesapi_createhibernationschedule.md
  - https://docs.cast.ai/reference/hibernationschedulesapi_deletehibernationschedule.md
  - https://docs.cast.ai/reference/hibernationschedulesapi_gethibernationschedule.md
  - https://docs.cast.ai/reference/hibernationschedulesapi_listhibernationschedules.md
  - https://docs.cast.ai/reference/hibernationschedulesapi_updatehibernationschedule.md
  - https://docs.cast.ai/reference/nodetemplatesapi_updatecapacityreservationconstraints.md
  - https://docs.cast.ai/reference/policiesv2api_getclusterpolicies.md
  - https://docs.cast.ai/reference/policiesv2api_updateclusterpolicies.md
  - https://docs.cast.ai/reference/rebalancingconfigapi_searchrebalancingnodefilters.md
  - https://docs.cast.ai/reference/rebalancingconfigapi_searchrebalancingnodefiltervalues.md
  - https://docs.cast.ai/reference/rebalancingconfigapi_searchrebalancingnodes.md
  - https://docs.cast.ai/reference/rebalancingconfigapi_searchrebalancingworkloads.md
  merge:
    pages: 24
    deduped: 200
    conflicts_kept_first: 0