{"openapi":"3.0.3","info":{"title":"Perfectscale API - OpenAPI 3.0","version":"v1"},"servers":[{"url":"https://api.app.perfectscale.io/public/v1"}],"security":[{"auth":[]}],"components":{"securitySchemes":{"auth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"TimeWindow":{"type":"string","description":"The time period for which the data is calculated (from 1h to 30d).","enum":["1h","4h","12h","1d","3d","7d","14d","30d"]},"Workload":{"type":"object","properties":{"id":{"type":"string","description":"A unique identifier for the workload, usually following a namespace-type-name convention."},"name":{"type":"string","description":"A human-readable name for the workload."},"type":{"type":"string","description":"The type of Kubernetes workload. Common types include Deployment, StatefulSet, and DaemonSet, but other string values can also be used to represent custom or extended workload types."},"namespace":{"type":"string","description":"The Kubernetes namespace in which the workload resides."},"firstSeen":{"type":"string","format":"date-time","description":"The timestamp when the workload was first observed."},"lastSeen":{"type":"string","format":"date-time","description":"The timestamp when the workload was last observed."},"runningMinutes":{"type":"integer","description":"The total number of minutes the workload has been running."},"replicasCounts":{"$ref":"#/components/schemas/ReplicasCounts"},"resilienceLevel":{"type":"string","description":"**Deprecated**: Use `optimizationPolicy` instead. The resilience level of the workload (configured on Perfectscale side).\n\nMapping to optimizationPolicy values:\n- `low` → `maxSavings`\n- `medium` → `balanced`\n- `high` → `extraHeadroom`\n- `highest` → `maxHeadroom`\n","deprecated":true,"enum":["low","medium","high","highest"]},"optimizationPolicy":{"allOf":[{"$ref":"#/components/schemas/OptimizationPolicy"}],"description":"The optimization policy applied to the workload."},"optimizationPolicyTimeWindow":{"allOf":[{"$ref":"#/components/schemas/OptimizationPolicyTimeWindow"}],"description":"The time window for optimization policy."},"cpuOptimizationPolicy":{"allOf":[{"$ref":"#/components/schemas/OptimizationPolicy"}],"description":"The CPU-specific optimization policy."},"memoryOptimizationPolicy":{"allOf":[{"$ref":"#/components/schemas/OptimizationPolicy"}],"description":"The memory-specific optimization policy."},"memoryRequestEqualsLimit":{"type":"boolean","description":"Whether memory request equals limit is enabled."},"muteStatus":{"$ref":"#/components/schemas/MuteStatus"},"costAnalysis":{"$ref":"#/components/schemas/CostAnalysis"},"workloadLabels":{"type":"object","description":"Key-value pairs representing kubernets labels associated with the workload.","additionalProperties":{"type":"string","description":"A label value associated with a particular key."}},"indicators":{"type":"array","description":"A list of indicators providing insights into the performance and health of the workload.","items":{"$ref":"#/components/schemas/Indicator"}},"containers":{"type":"array","description":"An object holding detailed information about each container within the workload.","items":{"$ref":"#/components/schemas/Container"}}},"required":["id","name","type","namespace","firstSeen","lastSeen","runningMinutes","replicasCounts","resilienceLevel","optimizationPolicy","optimizationPolicyTimeWindow","cpuOptimizationPolicy","memoryOptimizationPolicy","memoryRequestEqualsLimit","muteStatus","costAnalysis","workloadLabels","indicators","containers"]},"ReplicasCounts":{"type":"object","description":"An object representing the count statistics of replicas for a workload over a month period.","properties":{"maxCount":{"type":"integer","description":"The maximum count of replicas observed for the workload during the month period."},"avgCount":{"type":"integer","description":"The average count of replicas observed for the workload during the month period."}},"required":["maxCount","avgCount"]},"OptimizationPolicy":{"type":"string","description":"The optimization policy determining resource allocation strategy.","enum":["balanced","extraHeadroom","maxHeadroom","maxSavings"]},"OptimizationPolicyTimeWindow":{"type":"string","description":"The time window for optimization policy.","enum":["14d","21d","30d","45d","policyDefault"]},"MuteStatus":{"type":"object","properties":{"isMuted":{"type":"boolean","description":"Indicates whether the workload is currently muted."},"expires":{"type":"string","format":"date-time","nullable":true,"description":"The date and time when the workload will automatically become unmuted. If null, the mute status does not expire automatically."}},"required":["isMuted","expires"]},"CostAnalysis":{"type":"object","description":"Analysis of the costs associated with the workload's resource consumption for the requested period.","properties":{"past30Days":{"allOf":[{"$ref":"#/components/schemas/PastPeriodCostAnalysis"}],"description":"Cost analysis data for a 30-day window when an explicit period is requested (including period=30d). When no period is specified the default 28-day window is used for backward compatibility.\n"},"pastPeriod":{"$ref":"#/components/schemas/PastPeriodCostAnalysis"},"next30Days":{"allOf":[{"$ref":"#/components/schemas/NextPeriodCostAnalysis"}],"description":"Projected cost data for a 30-day window when an explicit period is requested (including period=30d). When no period is specified the default 28-day window is used for backward compatibility.\n"},"nextPeriod":{"$ref":"#/components/schemas/NextPeriodCostAnalysis"}},"required":["past30Days","next30Days","pastPeriod","nextPeriod"]},"PastPeriodCostAnalysis":{"type":"object","description":"Metrics detailing the total and wasted costs associated with the workload's resource consumption over the analysed period.","properties":{"totalCost":{"type":"number","format":"double","description":"The total cost incurred by the workload's resource consumption."},"wastedCost":{"type":"number","format":"double","description":"The cost attributed to over-provisioned or inefficiently utilized resources."},"costPerHour":{"type":"number","format":"double","description":"The cost of the workload per hour."}},"required":["totalCost","wastedCost","costPerHour"]},"NextPeriodCostAnalysis":{"type":"object","description":"Metrics detailing the cost increase and potential savings associated with the workload's upcoming potential resource consumption.","properties":{"costIncrease":{"type":"number","format":"double","description":"The workload total cost increase."},"potentialSavings":{"type":"number","format":"double","description":"The potential savings for the workload."}},"required":["costIncrease","potentialSavings"]},"Indicator":{"type":"object","description":"An object representing key performance indicators that provide insights into the performance and health of the workload or container.","properties":{"name":{"type":"string","description":"The name of the indicator representing a specific aspect of performance or health.","enum":["OOM","CpuThrottling","CpuRequestNotSet","MemRequestNotSet","MemLimitNotSet","UnderProvisionedMemRequest","UnderProvisionedMemLimit","UnderProvisionedCpuRequest","UnderProvisionedCpuLimit","OverProvisionedCpuRequest","OverProvisionedMemRequest","RestartsObserved"]},"type":{"type":"string","description":"The type of indicator, categorizing it as either a risk, waste, or no issue (none).","enum":["none","risk","waste"]},"severityLevel":{"type":"integer","description":"The severity level of the indicator, ranging from 0 (no issue) to 3 (critical issue).","enum":[0,1,2,3]}},"required":["name","type","severityLevel"]},"Container":{"type":"object","description":"Detailed information about a specific container within the workload, including its performance indicators and usage statistics.","properties":{"name":{"type":"string","description":"The name of the container."},"runningMinutes":{"type":"integer","description":"The total number of minutes the container has been running."},"indicators":{"type":"array","description":"A list of indicators providing insights into the performance and health of the container.","items":{"$ref":"#/components/schemas/Indicator"}},"resources":{"type":"object","description":"The resource allocation details for the workload, including the current and recommended by PerfectScale allocation.","properties":{"current":{"$ref":"#/components/schemas/Resources"},"recommended":{"$ref":"#/components/schemas/Resources"}},"required":["current","recommended"]},"usage":{"type":"object","description":"An object representing the resource usage statistics of a container, broken down into CPU and memory consumption.","properties":{"cpuCores":{"$ref":"#/components/schemas/Percentiles"},"memoryMiB":{"$ref":"#/components/schemas/Percentiles"}},"required":["cpuCores","memoryMiB"]}},"required":["name","runningMinutes","indicators","resources","usage"]},"Resources":{"type":"object","description":"Metrics detailing the resource allocation in terms of memory and CPU.","properties":{"memoryRequestMiB":{"type":"number","format":"double","description":"The amount of memory requested for the workload in MiB."},"memoryLimitMiB":{"type":"number","format":"double","description":"The maximum amount of memory that can be allocated for the workload in MiB."},"cpuRequestCores":{"type":"number","format":"double","description":"The amount of CPU resources requested for the workload in cores."},"cpuLimitCores":{"type":"number","format":"double","description":"The maximum amount of CPU resources that can be allocated for the workload in cores."}},"required":["memoryRequestMiB","memoryLimitMiB","cpuRequestCores","cpuLimitCores"]},"Percentiles":{"type":"object","description":"An object representing percentile statistics of resource usage, providing insights into the distribution of usage values over a certain period.","properties":{"p90":{"type":"number","format":"double","description":"The 90th percentile value of resource usage, indicating that 90% of the usage values are below this value and 10% are above."},"p95":{"type":"number","format":"double","description":"The 95th percentile value of resource usage, indicating that 95% of the usage values are below this value and 5% are above."},"p100":{"type":"number","format":"double","description":"The 100th percentile value (or maximum value) of resource usage observed during the specified period."}},"required":["p90","p95","p100"]}}},"paths":{"/clusters/{cluster_uid}/workloads":{"get":{"tags":["Workloads"],"summary":"List all workloads in a specified cluster","parameters":[{"name":"cluster_uid","in":"path","required":true,"schema":{"type":"string"},"description":"The unique identifier for the cluster"},{"name":"period","in":"query","required":false,"schema":{"allOf":[{"$ref":"#/components/schemas/TimeWindow"}]},"description":"The period for which data is calculated"},{"name":"expandEphemeralWorkloads","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"By default, short-lived ephemeral workloads in large clusters are collapsed into a single aggregate row named \"Collapsed Ephemeral Pods\" (namespace \"EphemeralPods\", type \"-\") carrying their summed cost and no recommendations. The aggregate row has empty-string values for resilienceLevel, optimizationPolicy, cpuOptimizationPolicy, memoryOptimizationPolicy and optimizationPolicyTimeWindow, a single placeholder container named \"-\", and firstSeen/lastSeen spanning the collapsed workloads. Collapse eligibility is evaluated within the requested period's data window, so the same cluster may collapse for one period and not another. Set to true to return the full, uncollapsed workload list.\n"}],"responses":{"200":{"description":"A list of workloads","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"count":{"type":"integer","description":"The total number of workloads in the specified cluster."}},"required":["count"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Workload"}}},"required":["meta","data"]}}}},"404":{"description":"Cluster not found"},"500":{"description":"Internal server error"}}}}}}