---
title: "Fetch right-sizing recommendations"
method: GET
path: "/simulations/{simulationId}/right-sizing-hint"
tags: ["Simulations"]
---

# Fetch right-sizing recommendations

`GET /simulations/{simulationId}/right-sizing-hint`

## Request

- Base URL: `https://www.cloudworldmodel.ai/api`
- URL: `https://www.cloudworldmodel.ai/api/simulations/{simulationId}/right-sizing-hint`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-PAYMENT`
  - API key in header `PAYMENT-SIGNATURE`

Analyses the simulation's recent metrics and resource configuration to
identify over-provisioned resources. Returns actionable hints with the
recommended smaller size slug, estimated hourly rate, estimated savings
percentage, and a trade-off note explaining the operational impact.

Returns `{ hasHint: false }` when the simulation is appropriately sized
and no generic downsizing is recommended. The
`rdsSqlServerComparisons` array is still returned for every resource
using the bounded SQL Server Express billing contract. Those entries
hold absolute vCPU demand and the caller-defined interval constant,
reset alternative credit balances to zero, and deliberately set
`recommendation` to null.

Requires `read` scope and ownership.

## Path parameters

- `simulationId` string, required

## Response `200`

Right-sizing hints (or empty result if no hints)

- union
  - object
    - `hasHint` boolean
    - `rdsSqlServerComparisons` RdsSqlServerComparison[]: Bounded RDS SQL Server Express cost comparisons, returned independently of whether generic right-sizing hints exist.
      - `resourceId` string, required
      - `current` RdsSqlServerBillingResult, required: Deterministic interval estimate for one bounded RDS SQL Server Express configuration. This is not an AWS invoice reconstruction. It excludes free tier, discounts, taxes, backup overage, transfer, additional gp3 IOPS/throughput, and account-specific adjustments; actual CloudWatch sampling and AWS hourly settlement can also differ.
        - `input` RdsSqlServerBillingConfig, required: Bounded caller-provided billing assumptions for AWS RDS SQL Server Express. Attach this object only to an `aws` `database` resource whose `serviceFamily` is `rds-sqlserver-express`. CPU is a constant interval assumption, not inferred from traffic, database load, generic simulated CPU, or a managed-service process. The initial earned-credit and surplus-credit ledgers are separate and cannot both be positive.
          - `engine` 'sqlserver-ex': SQL Server Express, license included. Other engines and editions are outside this bounded model.
          - `region` 'us-east-1': Pricing region supported by this model. It must agree with `resource.location.regionKey` when that field is supplied.
          - `deployment` 'single-az': Single-AZ deployment. Multi-AZ pricing is not included.
          - `instanceClass` 'db.t3.micro' | 'db.t3.small' | 'db.t3.medium' | 'db.t3.large' | 'db.t3.xlarge', required: Supported SQL Server Express T3 instance class. If `characteristics.size` or `instanceType` is also present, it must equal this value. Non-burstable classes are intentionally unsupported because this bounded regional Express catalog has no verified non-burstable SKU/rate; they fail validation rather than receiving a fabricated or generic fallback price.
          - `storageType` 'gp2' | 'gp3', required: General Purpose SSD storage price to apply. Additional gp3 IOPS and throughput are not modeled.
          - `allocatedStorageGiB` integer, required: Caller-declared allocated database storage in GiB.
          - `durationHours` number, required: Billing interval in hours. Storage is prorated over a documented 730-hour reference month.
          - `sustainedCpuPercent` number, required: Caller-provided constant average CPU utilization over the interval. This is neither an application-load attribution nor evidence that RdsAdminService, SQL Server, the OS, or any other process caused it.
          - `creditMode` 'unlimited': T3 Unlimited credit accounting. Disabling Unlimited is not modeled and would not remove the underlying CPU demand.
          - `initialCreditBalance` number: Earned CPU credits available at interval start, in vCPU-minutes. Bounded by the selected class's 24-hour earning limit.
          - `initialSurplusCreditBalance` number: Uncharged Unlimited surplus-credit debt at interval start, in vCPU-minutes. It is repaid before new credits are banked and is bounded by the selected class's 24-hour earning limit.
          - `settleSurplusAtEnd` boolean: Whether to charge and clear otherwise uncharged surplus debt at interval end, representing an explicit stop/delete settlement assumption. False keeps debt up to the 24-hour cap in the ending surplus ledger.
        - `computeCost` number, required: License-included Single-AZ instance cost over `durationHours`, USD.
        - `licensingCost` number, required: Separate SQL Server license surcharge over the interval, USD. Zero for this bounded Express license-included catalog because licensing is already included in computeCost.
        - `storageCost` number, required: Selected gp2/gp3 storage cost over `durationHours`, USD, using a 730-hour reference month.
        - `cpuCreditCost` number, required: Charged Unlimited surplus-credit cost over the interval, USD.
        - `totalCost` number, required: Sum of modeled instance, storage, and CPU-credit components, USD.
        - `effectiveHourlyCost` number, required: Effective interval total divided by durationHours, USD/hr.
        - `workloadVcpus` number, required: Fixed absolute CPU demand used for size comparisons, equal to class vCPUs times sustained CPU fraction.
        - `credits` RdsSqlServerCreditLedger, required: CPU-credit ledger for the caller-defined interval. One CPU credit is one vCPU-minute. Earned and consumed credits are totals; ending earned and surplus balances remain distinct.
          - `earnedCredits` number, required: Baseline credits earned during the interval.
          - `consumedCredits` number, required: Credits consumed by the declared vCPU utilization during the interval.
          - `creditCap` number, required: Maximum banked earned credits or uncharged surplus debt, equal to 24 hours of baseline earnings.
          - `endingCreditBalance` number, required: Earned credits remaining after consumption and repayment of any initial surplus.
          - `endingSurplusCreditBalance` number, required: Uncharged Unlimited surplus debt retained at interval end; zero when end settlement is requested.
          - `chargedCredits` number, required: Total credits billed as surplus, equal to overflow plus explicit end-settlement credits.
          - `overflowChargedCredits` number, required: Surplus credits beyond the 24-hour uncharged debt cap.
          - `settlementChargedCredits` number, required: Surplus debt charged because `settleSurplusAtEnd` was true.
        - `assumptions` string[], required: Human-readable pricing, interval, provenance, and exclusion assumptions that qualify this estimate.
      - `alternatives` RdsSqlServerBillingResult[], required
        - `input` RdsSqlServerBillingConfig, required: Bounded caller-provided billing assumptions for AWS RDS SQL Server Express. Attach this object only to an `aws` `database` resource whose `serviceFamily` is `rds-sqlserver-express`. CPU is a constant interval assumption, not inferred from traffic, database load, generic simulated CPU, or a managed-service process. The initial earned-credit and surplus-credit ledgers are separate and cannot both be positive.
          - `engine` 'sqlserver-ex': SQL Server Express, license included. Other engines and editions are outside this bounded model.
          - `region` 'us-east-1': Pricing region supported by this model. It must agree with `resource.location.regionKey` when that field is supplied.
          - `deployment` 'single-az': Single-AZ deployment. Multi-AZ pricing is not included.
          - `instanceClass` 'db.t3.micro' | 'db.t3.small' | 'db.t3.medium' | 'db.t3.large' | 'db.t3.xlarge', required: Supported SQL Server Express T3 instance class. If `characteristics.size` or `instanceType` is also present, it must equal this value. Non-burstable classes are intentionally unsupported because this bounded regional Express catalog has no verified non-burstable SKU/rate; they fail validation rather than receiving a fabricated or generic fallback price.
          - `storageType` 'gp2' | 'gp3', required: General Purpose SSD storage price to apply. Additional gp3 IOPS and throughput are not modeled.
          - `allocatedStorageGiB` integer, required: Caller-declared allocated database storage in GiB.
          - `durationHours` number, required: Billing interval in hours. Storage is prorated over a documented 730-hour reference month.
          - `sustainedCpuPercent` number, required: Caller-provided constant average CPU utilization over the interval. This is neither an application-load attribution nor evidence that RdsAdminService, SQL Server, the OS, or any other process caused it.
          - `creditMode` 'unlimited': T3 Unlimited credit accounting. Disabling Unlimited is not modeled and would not remove the underlying CPU demand.
          - `initialCreditBalance` number: Earned CPU credits available at interval start, in vCPU-minutes. Bounded by the selected class's 24-hour earning limit.
          - `initialSurplusCreditBalance` number: Uncharged Unlimited surplus-credit debt at interval start, in vCPU-minutes. It is repaid before new credits are banked and is bounded by the selected class's 24-hour earning limit.
          - `settleSurplusAtEnd` boolean: Whether to charge and clear otherwise uncharged surplus debt at interval end, representing an explicit stop/delete settlement assumption. False keeps debt up to the 24-hour cap in the ending surplus ledger.
        - `computeCost` number, required: License-included Single-AZ instance cost over `durationHours`, USD.
        - `licensingCost` number, required: Separate SQL Server license surcharge over the interval, USD. Zero for this bounded Express license-included catalog because licensing is already included in computeCost.
        - `storageCost` number, required: Selected gp2/gp3 storage cost over `durationHours`, USD, using a 730-hour reference month.
        - `cpuCreditCost` number, required: Charged Unlimited surplus-credit cost over the interval, USD.
        - `totalCost` number, required: Sum of modeled instance, storage, and CPU-credit components, USD.
        - `effectiveHourlyCost` number, required: Effective interval total divided by durationHours, USD/hr.
        - `workloadVcpus` number, required: Fixed absolute CPU demand used for size comparisons, equal to class vCPUs times sustained CPU fraction.
        - `credits` RdsSqlServerCreditLedger, required: CPU-credit ledger for the caller-defined interval. One CPU credit is one vCPU-minute. Earned and consumed credits are totals; ending earned and surplus balances remain distinct.
          - `earnedCredits` number, required: Baseline credits earned during the interval.
          - `consumedCredits` number, required: Credits consumed by the declared vCPU utilization during the interval.
          - `creditCap` number, required: Maximum banked earned credits or uncharged surplus debt, equal to 24 hours of baseline earnings.
          - `endingCreditBalance` number, required: Earned credits remaining after consumption and repayment of any initial surplus.
          - `endingSurplusCreditBalance` number, required: Uncharged Unlimited surplus debt retained at interval end; zero when end settlement is requested.
          - `chargedCredits` number, required: Total credits billed as surplus, equal to overflow plus explicit end-settlement credits.
          - `overflowChargedCredits` number, required: Surplus credits beyond the 24-hour uncharged debt cap.
          - `settlementChargedCredits` number, required: Surplus debt charged because `settleSurplusAtEnd` was true.
        - `assumptions` string[], required: Human-readable pricing, interval, provenance, and exclusion assumptions that qualify this estimate.
      - `comparisonBasis` string, required: Exact fixed-workload assumptions used across the alternatives.
      - `recommendation` unknown, required
  - object
    - `hasHint` boolean
    - `rdsSqlServerComparisons` RdsSqlServerComparison[]: Bounded RDS SQL Server Express cost comparisons, returned independently of generic right-sizing hints. Read the comparison basis rather than treating entries as recommendations.
      - `resourceId` string, required
      - `current` RdsSqlServerBillingResult, required: Deterministic interval estimate for one bounded RDS SQL Server Express configuration. This is not an AWS invoice reconstruction. It excludes free tier, discounts, taxes, backup overage, transfer, additional gp3 IOPS/throughput, and account-specific adjustments; actual CloudWatch sampling and AWS hourly settlement can also differ.
        - `input` RdsSqlServerBillingConfig, required: Bounded caller-provided billing assumptions for AWS RDS SQL Server Express. Attach this object only to an `aws` `database` resource whose `serviceFamily` is `rds-sqlserver-express`. CPU is a constant interval assumption, not inferred from traffic, database load, generic simulated CPU, or a managed-service process. The initial earned-credit and surplus-credit ledgers are separate and cannot both be positive.
          - `engine` 'sqlserver-ex': SQL Server Express, license included. Other engines and editions are outside this bounded model.
          - `region` 'us-east-1': Pricing region supported by this model. It must agree with `resource.location.regionKey` when that field is supplied.
          - `deployment` 'single-az': Single-AZ deployment. Multi-AZ pricing is not included.
          - `instanceClass` 'db.t3.micro' | 'db.t3.small' | 'db.t3.medium' | 'db.t3.large' | 'db.t3.xlarge', required: Supported SQL Server Express T3 instance class. If `characteristics.size` or `instanceType` is also present, it must equal this value. Non-burstable classes are intentionally unsupported because this bounded regional Express catalog has no verified non-burstable SKU/rate; they fail validation rather than receiving a fabricated or generic fallback price.
          - `storageType` 'gp2' | 'gp3', required: General Purpose SSD storage price to apply. Additional gp3 IOPS and throughput are not modeled.
          - `allocatedStorageGiB` integer, required: Caller-declared allocated database storage in GiB.
          - `durationHours` number, required: Billing interval in hours. Storage is prorated over a documented 730-hour reference month.
          - `sustainedCpuPercent` number, required: Caller-provided constant average CPU utilization over the interval. This is neither an application-load attribution nor evidence that RdsAdminService, SQL Server, the OS, or any other process caused it.
          - `creditMode` 'unlimited': T3 Unlimited credit accounting. Disabling Unlimited is not modeled and would not remove the underlying CPU demand.
          - `initialCreditBalance` number: Earned CPU credits available at interval start, in vCPU-minutes. Bounded by the selected class's 24-hour earning limit.
          - `initialSurplusCreditBalance` number: Uncharged Unlimited surplus-credit debt at interval start, in vCPU-minutes. It is repaid before new credits are banked and is bounded by the selected class's 24-hour earning limit.
          - `settleSurplusAtEnd` boolean: Whether to charge and clear otherwise uncharged surplus debt at interval end, representing an explicit stop/delete settlement assumption. False keeps debt up to the 24-hour cap in the ending surplus ledger.
        - `computeCost` number, required: License-included Single-AZ instance cost over `durationHours`, USD.
        - `licensingCost` number, required: Separate SQL Server license surcharge over the interval, USD. Zero for this bounded Express license-included catalog because licensing is already included in computeCost.
        - `storageCost` number, required: Selected gp2/gp3 storage cost over `durationHours`, USD, using a 730-hour reference month.
        - `cpuCreditCost` number, required: Charged Unlimited surplus-credit cost over the interval, USD.
        - `totalCost` number, required: Sum of modeled instance, storage, and CPU-credit components, USD.
        - `effectiveHourlyCost` number, required: Effective interval total divided by durationHours, USD/hr.
        - `workloadVcpus` number, required: Fixed absolute CPU demand used for size comparisons, equal to class vCPUs times sustained CPU fraction.
        - `credits` RdsSqlServerCreditLedger, required: CPU-credit ledger for the caller-defined interval. One CPU credit is one vCPU-minute. Earned and consumed credits are totals; ending earned and surplus balances remain distinct.
          - `earnedCredits` number, required: Baseline credits earned during the interval.
          - `consumedCredits` number, required: Credits consumed by the declared vCPU utilization during the interval.
          - `creditCap` number, required: Maximum banked earned credits or uncharged surplus debt, equal to 24 hours of baseline earnings.
          - `endingCreditBalance` number, required: Earned credits remaining after consumption and repayment of any initial surplus.
          - `endingSurplusCreditBalance` number, required: Uncharged Unlimited surplus debt retained at interval end; zero when end settlement is requested.
          - `chargedCredits` number, required: Total credits billed as surplus, equal to overflow plus explicit end-settlement credits.
          - `overflowChargedCredits` number, required: Surplus credits beyond the 24-hour uncharged debt cap.
          - `settlementChargedCredits` number, required: Surplus debt charged because `settleSurplusAtEnd` was true.
        - `assumptions` string[], required: Human-readable pricing, interval, provenance, and exclusion assumptions that qualify this estimate.
      - `alternatives` RdsSqlServerBillingResult[], required
        - `input` RdsSqlServerBillingConfig, required: Bounded caller-provided billing assumptions for AWS RDS SQL Server Express. Attach this object only to an `aws` `database` resource whose `serviceFamily` is `rds-sqlserver-express`. CPU is a constant interval assumption, not inferred from traffic, database load, generic simulated CPU, or a managed-service process. The initial earned-credit and surplus-credit ledgers are separate and cannot both be positive.
          - `engine` 'sqlserver-ex': SQL Server Express, license included. Other engines and editions are outside this bounded model.
          - `region` 'us-east-1': Pricing region supported by this model. It must agree with `resource.location.regionKey` when that field is supplied.
          - `deployment` 'single-az': Single-AZ deployment. Multi-AZ pricing is not included.
          - `instanceClass` 'db.t3.micro' | 'db.t3.small' | 'db.t3.medium' | 'db.t3.large' | 'db.t3.xlarge', required: Supported SQL Server Express T3 instance class. If `characteristics.size` or `instanceType` is also present, it must equal this value. Non-burstable classes are intentionally unsupported because this bounded regional Express catalog has no verified non-burstable SKU/rate; they fail validation rather than receiving a fabricated or generic fallback price.
          - `storageType` 'gp2' | 'gp3', required: General Purpose SSD storage price to apply. Additional gp3 IOPS and throughput are not modeled.
          - `allocatedStorageGiB` integer, required: Caller-declared allocated database storage in GiB.
          - `durationHours` number, required: Billing interval in hours. Storage is prorated over a documented 730-hour reference month.
          - `sustainedCpuPercent` number, required: Caller-provided constant average CPU utilization over the interval. This is neither an application-load attribution nor evidence that RdsAdminService, SQL Server, the OS, or any other process caused it.
          - `creditMode` 'unlimited': T3 Unlimited credit accounting. Disabling Unlimited is not modeled and would not remove the underlying CPU demand.
          - `initialCreditBalance` number: Earned CPU credits available at interval start, in vCPU-minutes. Bounded by the selected class's 24-hour earning limit.
          - `initialSurplusCreditBalance` number: Uncharged Unlimited surplus-credit debt at interval start, in vCPU-minutes. It is repaid before new credits are banked and is bounded by the selected class's 24-hour earning limit.
          - `settleSurplusAtEnd` boolean: Whether to charge and clear otherwise uncharged surplus debt at interval end, representing an explicit stop/delete settlement assumption. False keeps debt up to the 24-hour cap in the ending surplus ledger.
        - `computeCost` number, required: License-included Single-AZ instance cost over `durationHours`, USD.
        - `licensingCost` number, required: Separate SQL Server license surcharge over the interval, USD. Zero for this bounded Express license-included catalog because licensing is already included in computeCost.
        - `storageCost` number, required: Selected gp2/gp3 storage cost over `durationHours`, USD, using a 730-hour reference month.
        - `cpuCreditCost` number, required: Charged Unlimited surplus-credit cost over the interval, USD.
        - `totalCost` number, required: Sum of modeled instance, storage, and CPU-credit components, USD.
        - `effectiveHourlyCost` number, required: Effective interval total divided by durationHours, USD/hr.
        - `workloadVcpus` number, required: Fixed absolute CPU demand used for size comparisons, equal to class vCPUs times sustained CPU fraction.
        - `credits` RdsSqlServerCreditLedger, required: CPU-credit ledger for the caller-defined interval. One CPU credit is one vCPU-minute. Earned and consumed credits are totals; ending earned and surplus balances remain distinct.
          - `earnedCredits` number, required: Baseline credits earned during the interval.
          - `consumedCredits` number, required: Credits consumed by the declared vCPU utilization during the interval.
          - `creditCap` number, required: Maximum banked earned credits or uncharged surplus debt, equal to 24 hours of baseline earnings.
          - `endingCreditBalance` number, required: Earned credits remaining after consumption and repayment of any initial surplus.
          - `endingSurplusCreditBalance` number, required: Uncharged Unlimited surplus debt retained at interval end; zero when end settlement is requested.
          - `chargedCredits` number, required: Total credits billed as surplus, equal to overflow plus explicit end-settlement credits.
          - `overflowChargedCredits` number, required: Surplus credits beyond the 24-hour uncharged debt cap.
          - `settlementChargedCredits` number, required: Surplus debt charged because `settleSurplusAtEnd` was true.
        - `assumptions` string[], required: Human-readable pricing, interval, provenance, and exclusion assumptions that qualify this estimate.
      - `comparisonBasis` string, required: Exact fixed-workload assumptions used across the alternatives.
      - `recommendation` unknown, required
    - `hints` object[]
      - `resourceType` 'compute' | 'database' | 'network' | 'storage' | 'kubernetes'
      - `reason` 'low_cpu' | 'scale_in' | 'both' | 'low_connection_util' | 'low_throughput' | 'low_throughput_util' | 'high_throughput_util' | 'low_cpu_util' | 'cross_provider_alternative' | 'gpu-underutilized' | 'gpu-saturated' | 'gpu-api-breakeven': What triggered the hint. - `low_cpu` — CPU utilization has been consistently below 40%. - `scale_in` — a scale-in event was observed recently. - `both` — both low CPU and a recent scale-in apply. - `low_cpu_util` — CPU-based trigger for OCI/HeatWave shapes. - `low_connection_util` — database connection utilization below 40%. - `low_throughput` / `low_throughput_util` — I/O or network throughput well below capacity. - `high_throughput_util` — approaching a throughput ceiling (scale-up signal). - `cross_provider_alternative` — the recommended slug belongs to a *different* cloud provider than the simulation's current resources. Treat this as a migration option, not a direct resize; additional setup is required to move workloads across providers. - `gpu-underutilized` / `gpu-saturated` / `gpu-api-breakeven` — GPU inference right-sizing signals on `kubernetes` resources running in inference mode (based on `metrics.gpuUtilization`).
      - `affectedResourceId` string, nullable
      - `affectedResourceName` string, nullable
      - `recommendedSlug` string: Recommended smaller size slug
      - `hourlyRate` number: Estimated hourly cost of the recommended size (USD)
      - `estimatedSavingsPct` integer: Estimated percentage cost saving
      - `tradeOffNote` string: Operational trade-off to consider before resizing
      - `currentUtilization` number, nullable: Current utilization percentage driving the recommendation
      - `utilizationMetric` 'cpu' | 'gpu' | 'memory' | 'connections' | 'iops' | 'unknown': Which metric produced `currentUtilization` — without this label a consumer cannot tell whether `3` means 3% CPU, 3% GPU, 3% connection-pool utilization, or something else. `unknown` when the source metric is not a percentage of a labelled metric (e.g. raw RPS on network hints).
      - `reversibility` object: How hard this recommendation is to reverse, classified by the same shared rule-based engine used by `GET /api/analysis/jobs/{jobId}/recommendations`.
        - `tier` 'instant' | 'minutes' | 'hours' | 'days'
        - `estimatedMinutesMin` number
        - `estimatedMinutesMax` number
        - `reason` string: Human-readable explanation naming the dominant action.
        - `basis` 'rule_based'

## Other responses

- `401`: No credentials provided to an API-key-protected endpoint. The response body includes a machine-readable `apiKeyAuth` block pointing to the key creation endpoint so agents can self-serve an API key without consulting the spec.
- `403`: Access denied
- `404`: Resource not found
- `500`: Internal server error

---

[API](https://skmtc.dev/cloudworldmodel/apis/cloud-world-model-agent-api.md) · [All operations](https://skmtc.dev/cloudworldmodel/apis/cloud-world-model-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cloudworldmodel/apis/cloud-world-model-agent-api/revisions/ecc3ad1ff07f?raw)