Cast AI Cluster Advisor API

openapi: 3.2.0
info:
  title: Cluster Autoscaler Cluster Advisor API
  version: 0.0.1
  description: ClusterAdvisorAPI provides endpoints for triggering and managing cluster advisor analyses.
servers:
- url: https://api.cast.ai/
  description: US endpoint
- url: https://api.eu.cast.ai/
  description: EU endpoint
security:
- BearerAuth: []
- ApiKeyAuth: []
tags:
- name: ClusterAdvisorAPI
  description: ClusterAdvisorAPI provides endpoints for triggering and managing cluster advisor analyses.
paths:
  /cluster-autoscaler/v1beta/organizations/{organizationId}/clusters/{clusterId}/cluster-advisor-analyses:
    post:
      tags:
      - ClusterAdvisorAPI
      description: Creates a new cluster advisor analysis.
      operationId: ClusterAdvisorAPI_CreateAnalysis
      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/Analysis'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Analysis'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
      summary: Cluster advisor API create analysis
      x-summary-source: derived
    get:
      tags:
      - ClusterAdvisorAPI
      description: Lists analyses for a cluster.
      operationId: ClusterAdvisorAPI_ListAnalyses
      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: 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/ListAnalysesResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
      summary: Cluster advisor API list analyses
      x-summary-source: derived
  ? /cluster-autoscaler/v1beta/organizations/{organizationId}/clusters/{clusterId}/cluster-advisor-analyses/{clusterAdvisorAnalysisId}/variants
  : get:
      tags:
      - ClusterAdvisorAPI
      description: Lists analysis variants for an analysis.
      operationId: ClusterAdvisorAPI_ListAnalysisVariants
      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: clusterAdvisorAnalysisId
        in: path
        description: Parent analysis ID.
        required: true
        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/ListAnalysisVariantsResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
      summary: Cluster advisor API list analysis variants
      x-summary-source: derived
  ? /cluster-autoscaler/v1beta/organizations/{organizationId}/clusters/{clusterId}/cluster-advisor-analyses/{clusterAdvisorAnalysisId}/variants/{id}
  : get:
      tags:
      - ClusterAdvisorAPI
      description: Gets a specific analysis variant.
      operationId: ClusterAdvisorAPI_GetAnalysisVariant
      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: clusterAdvisorAnalysisId
        in: path
        description: Parent analysis ID.
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: Analysis variant ID.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalysisVariant'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
      summary: Cluster advisor API get analysis variant
      x-summary-source: derived
  /cluster-autoscaler/v1beta/organizations/{organizationId}/clusters/{clusterId}/cluster-advisor-analyses/{id}:
    get:
      tags:
      - ClusterAdvisorAPI
      description: Gets analysis details.
      operationId: ClusterAdvisorAPI_GetAnalysis
      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: id
        in: path
        description: Analysis ID.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Analysis'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
      summary: Cluster advisor API get analysis
      x-summary-source: derived
  /cluster-autoscaler/v1beta/organizations/{organizationId}/clusters/{clusterId}/cluster-advisor-analyses/{id}:cancel:
    post:
      tags:
      - ClusterAdvisorAPI
      description: Cancels a running analysis.
      operationId: ClusterAdvisorAPI_CancelAnalysis
      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: id
        in: path
        description: Analysis ID.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelAnalysisRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelAnalysisResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
      summary: Cluster advisor API cancel analysis
      x-summary-source: derived
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).'
    VariantResult:
      type: object
      properties:
        savingsPct:
          type: number
          description: Savings percentage compared to current state.
          format: double
        savingsImprovement:
          type: number
          description: Savings improvement over the baseline.
          format: double
        greenNodes:
          type: integer
          description: Number of green (right-sized) nodes.
          format: int32
        greenPriceMonthly:
          type: number
          description: Monthly price of green nodes.
          format: double
        detectedMutations:
          type: array
          items:
            $ref: '#/components/schemas/Mutation'
          description: Mutations detected by this variant run (proposed for next depth).
      description: Result of a rebalancing variant.
    ComboMutationParams:
      type: object
      properties:
        mutations:
          type: array
          items:
            $ref: '#/components/schemas/Mutation'
          description: Sub-mutations in this combo.
      description: Parameters for combo mutation.
    ListAnalysesResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Analysis'
          description: List of analyses.
        nextPageCursor:
          type: string
          description: Cursor for the next page. Empty when there are no more pages.
        totalCount:
          type: integer
          description: Total number of analyses.
          format: int32
      description: Response containing the list of analyses.
    SimulationOptions:
      type: object
      properties:
        aggressiveModeConfig:
          allOf:
          - $ref: '#/components/schemas/AggressiveModeConfig'
          description: Optional aggressive mode configuration.
      description: SimulationOptions controls the behavior of the cluster advisor simulation.
    AnalysisVariant:
      type: object
      properties:
        id:
          readOnly: true
          type: string
          description: Variant ID.
        analysisId:
          readOnly: true
          type: string
          description: Analysis ID.
        parentAnalysisVariantId:
          readOnly: true
          type: string
          description: Optional parent analysis variant ID.
        rebalancingPlanId:
          readOnly: true
          type: string
          description: Optional rebalancing plan ID.
        status:
          readOnly: true
          enum:
          - ANALYSIS_VARIANT_STATUS_UNSPECIFIED
          - ANALYSIS_VARIANT_STATUS_PENDING
          - ANALYSIS_VARIANT_STATUS_RUNNING
          - ANALYSIS_VARIANT_STATUS_COMPLETED
          - ANALYSIS_VARIANT_STATUS_FAILED
          - ANALYSIS_VARIANT_STATUS_CANCELED
          - ANALYSIS_VARIANT_STATUS_ENQUEUED
          type: string
          description: Variant status.
          format: enum
        mutations:
          readOnly: true
          type: array
          items:
            $ref: '#/components/schemas/Mutation'
          description: Mutations applied to generate this variant.
        mutationDepth:
          readOnly: true
          type: integer
          description: Mutation depth.
          format: int32
        result:
          readOnly: true
          allOf:
          - $ref: '#/components/schemas/VariantResult'
          description: Optional variant result.
        error:
          readOnly: true
          type: string
          description: Optional error message.
        createTime:
          readOnly: true
          type: string
          description: Timestamp when the variant was created.
          format: date-time
        completeTime:
          readOnly: true
          type: string
          description: Optional timestamp when the variant completed.
          format: date-time
        variantType:
          readOnly: true
          type: string
          description: 'Variant type: baseline or mutation.'
        cancelTime:
          readOnly: true
          type: string
          description: Optional timestamp when the variant was canceled.
          format: date-time
      description: An analysis variant produced by the cluster advisor.
    MinCpuMutationParams:
      type: object
      properties:
        templateName:
          type: string
          description: Template name.
        newMinCpu:
          type: integer
          description: New minimum CPU value.
          format: int32
      description: Parameters for min CPU mutation.
    ListAnalysisVariantsResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/AnalysisVariant'
          description: List of analysis variants.
        nextPageCursor:
          type: string
          description: Cursor for the next page. Empty when there are no more pages.
        totalCount:
          type: integer
          description: Total number of analysis variants.
          format: int32
      description: Response containing the list of analysis variants.
    Analysis:
      required:
      - triggerType
      type: object
      properties:
        id:
          readOnly: true
          type: string
          description: Analysis ID.
        clusterId:
          type: string
          description: Cluster ID.
        organizationId:
          type: string
          description: Organization ID.
        status:
          readOnly: true
          enum:
          - ANALYSIS_STATUS_UNSPECIFIED
          - ANALYSIS_STATUS_PENDING
          - ANALYSIS_STATUS_RUNNING
          - ANALYSIS_STATUS_COMPLETED
          - ANALYSIS_STATUS_FAILED
          - ANALYSIS_STATUS_CANCELED
          type: string
          description: Analysis status.
          format: enum
        triggerType:
          enum:
          - TRIGGER_TYPE_UNSPECIFIED
          - TRIGGER_TYPE_FULL_CLUSTER
          - TRIGGER_TYPE_REBALANCING_PLAN
          - TRIGGER_TYPE_SNAPSHOT
          type: string
          description: Trigger type.
          format: enum
        sourcePlanId:
          type: string
          description: Optional source plan ID to base the analysis on.
        maxDepth:
          type: integer
          description: Maximum mutation depth.
          format: int32
        maxAnalysisVariants:
          type: integer
          description: Optional maximum number of analysis variants.
          format: int32
        minSavingsThreshold:
          type: number
          description: Optional minimum savings threshold (percentage).
          format: double
        baselineVariantId:
          readOnly: true
          type: string
          description: Optional baseline variant ID.
        baselineSavingsPct:
          readOnly: true
          type: number
          description: Optional baseline savings percentage.
          format: double
        baselineDetectedMutationsCount:
          readOnly: true
          type: integer
          description: Number of mutations detected in the baseline variant.
          format: int32
        totalAnalysisVariants:
          readOnly: true
          type: integer
          description: Total number of analysis variants.
          format: int32
        completedAnalysisVariants:
          readOnly: true
          type: integer
          description: Number of completed analysis variants.
          format: int32
        bestAnalysisVariantId:
          readOnly: true
          type: string
          description: Optional best analysis variant ID.
        bestSavingsPct:
          readOnly: true
          type: number
          description: Optional best savings percentage.
          format: double
        error:
          readOnly: true
          type: string
          description: Optional error message.
        createTime:
          readOnly: true
          type: string
          description: Timestamp when the analysis was created.
          format: date-time
        updateTime:
          readOnly: true
          type: string
          description: Timestamp when the analysis was last updated.
          format: date-time
        startTime:
          readOnly: true
          type: string
          description: Optional timestamp when the analysis started.
          format: date-time
        completeTime:
          readOnly: true
          type: string
          description: Optional timestamp when the analysis completed.
          format: date-time
        snapshotAnchorTime:
          type: string
          description: "Optional snapshot anchor time. When trigger_type is TRIGGER_TYPE_SNAPSHOT, the analysis\n runs on the snapshot whose capture time is closest to this timestamp (within ±1 minute)."
          format: date-time
        cancelTime:
          readOnly: true
          type: string
          description: Optional timestamp when the analysis was canceled.
          format: date-time
        simulationOptions:
          allOf:
          - $ref: '#/components/schemas/SimulationOptions'
          description: Optional simulation options for controlling the rebalancing simulation behavior.
      description: A cluster advisor analysis.
    AggressiveModeConfig:
      type: object
      properties:
        ignoreLocalPersistentVolumes:
          type: boolean
          description: Ignore pods that use local persistent volumes.
        ignoreRemovalDisabled:
          type: boolean
          description: Ignore pods with the removal-disabled annotation.
        ignoreJobs:
          type: boolean
          description: Ignore Job pods.
        ignorePodsWithoutController:
          type: boolean
          description: Ignore pods without a controller.
        ignorePreventedDrain:
          type: boolean
          description: Ignore pods with the prevented-drain annotation.
      description: AggressiveModeConfig controls which problematic pod types are ignored during cluster advisor simulation.
    MaxPodsMutationParams:
      type: object
      properties:
        templateName:
          type: string
          description: Template name.
        newMaxPods:
          type: integer
          description: New max pods value.
          format: int32
        removeFormula:
          type: boolean
          description: Whether to remove the formula.
      description: Parameters for max pods mutation.
    CancelAnalysisRequest:
      required:
      - organizationId
      - clusterId
      - id
      type: object
      properties:
        organizationId:
          type: string
          description: Organization ID.
        clusterId:
          type: string
          description: Cluster ID.
        id:
          type: string
          description: Analysis ID.
        force:
          type: boolean
          description: 'Force cancel: if true, immediately transition to cancelled without waiting for in-flight variants.'
      description: Request to cancel a running analysis.
    RemoveTopologyMutationParams:
      type: object
      properties:
        ownerName:
          type: string
          description: Owner name (e.g. Deployment or StatefulSet name).
        ownerKind:
          type: string
          description: Owner kind (e.g. Deployment, StatefulSet).
      description: Parameters for remove topology mutation.
    Mutation:
      type: object
      properties:
        name:
          type: string
          description: Mutation name.
        description:
          type: string
          description: Mutation description.
        category:
          type: string
          description: Mutation category.
        affectedSubjects:
          type: array
          items:
            type: string
          description: Affected subjects (e.g. node names).
        hash:
          readOnly: true
          type: string
          description: Stable fingerprint of the mutation's identity (name, category, subjects, params).
        minCpu:
          allOf:
          - $ref: '#/components/schemas/MinCpuMutationParams'
          description: Min CPU mutation parameters.
        maxPods:
          allOf:
          - $ref: '#/components/schemas/MaxPodsMutationParams'
          description: Max pods mutation parameters.
        removeTopology:
          allOf:
          - $ref: '#/components/schemas/RemoveTopologyMutationParams'
          description: Remove topology mutation parameters.
        combo:
          allOf:
          - $ref: '#/components/schemas/ComboMutationParams'
          description: Combo mutation parameters.
      description: A single mutation applied to a rebalancing plan.
    CancelAnalysisResponse:
      type: object
      properties:
        analysis:
          allOf:
          - $ref: '#/components/schemas/Analysis'
          description: The analysis after the cancel request was applied.
      description: Response for cancel analysis.
    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/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