--- title: "Fetch the latest per-resource cost breakdown" method: GET path: "/simulations/{simulationId}/cost-breakdown" tags: ["Simulations"] --- # Fetch the latest per-resource cost breakdown `GET /simulations/{simulationId}/cost-breakdown` ## Request - Base URL: `https://www.cloudworldmodel.ai/api` - URL: `https://www.cloudworldmodel.ai/api/simulations/{simulationId}/cost-breakdown` - Auth: none required Returns the per-resource hourly cost array from the simulation's most recent metrics record, joined with each resource's current status and serving state. `status` is raw health severity/cooldown; use `availabilityState`, `isRoutable`, and `routedRps` to determine whether the resource is currently serving. A critical resource may therefore be `availabilityState: degraded` with `isRoutable: true` after it rejoins routing. Use this after a failure or traffic surge to identify resources that continue billing while genuinely unavailable ("residual" spend). `totalCostPerHour` is the exact sum of all `resources[].costPerHour` values. The response is always a flat array (no paging, no metrics history), making it cheap to call between scenario steps. Aurora Serverless v2 rows identify writer/reader role, reader scaling mode, billable ACU and the per-ACU-hour rate. An unavailable quick-failure writer retains its pre-failure allocated ACU in this model; this is a modeling assumption, not a claim that AWS bills a failed instance like a stopped cluster. AWS distinguishes stopped clusters from running instances: https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/aurora-cluster-stop-start.html (reviewed 2026-09-25). Aurora capacity/reader behavior: https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/aurora-serverless-v2.how-it-works.html (reviewed 2026-09-25). OpenShift rows retain their billing metadata. For ARO, compare like-for-like units: `publishedUnitRatePerHour` is the official `$0.171/hour` rate per 4-vCPU billing unit, while `derivedPlatformFeePerHour` and `costPerHour` are the topology-derived total. For example, three 2-vCPU workers produce `effectiveWorkerVcpu: 6` and a `$0.2565/hour` platform total (`publishedUnitRatePerHour × effectiveWorkerVcpu ÷ billingUnitVcpu`). Platform, control-plane, and worker rows are separate additive entries; the estimated control-plane charge must not be folded into the platform unit comparison or added a second time. Returns 404 when the simulation has not been stepped yet (no metrics record exists). Requires `read` scope and ownership, or an x402 micro-payment (`simulation_cost_breakdown`, $0.0030). ## Path parameters - `simulationId` string, required ## Response `200` Latest per-resource cost breakdown - object - `simulationId` string, required - `stepIndex` number, required: Simulation step (metrics timestamp) the breakdown was computed at - `totalCostPerHour` number, required: Exact sum of all resources[].costPerHour values (USD/hr) - `residualCostPerHour` number, required: Exact subtotal of costPerHour for resources that are currently unavailable/parked or stopped. Healthy/degraded idle resources, including ALBs, are excluded. - `residualCostDefinition` string, required: Explains which billed resources are included in residualCostPerHour; totalCostPerHour includes all billed resources. - `resources` object[], required - `resourceId` string, required - `name` string, required - `resourceType` string, required - `provider` string, required - `costPerHour` number, required - `instanceRole` 'writer' | 'reader': Aurora Serverless v2 instance role. - `scalingMode` 'writer-mirror' | 'independent': Reader promotion tier 0/1 mirror or tier 2–15 independent mode. - `billableAcu` number: Allocated ACU billed for this instance; frozen pre-failure ACU on modeled quick writer park. - `ratePerAcuHour` number: Aurora per-instance ACU-hour rate derived from the authoritative AWS rate. - `rateBasis` string - `billingReason` string - `rdsSqlServerBilling` RdsSqlServerBillingResult: 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. - `storageCostPerHour` number: RDS SQL Server allocated-storage component expressed as USD/hr. - `storageGb` number: Normalized allocated RDS SQL Server storage in GiB. - `status` 'healthy' | 'warning' | 'critical' | 'stopped' | 'billed' | 'removed', required: Current resource status ("stopped" when billingState is stopped; "billed" for synthetic egress/data-transfer charges; "removed" when a real resource no longer exists) - `availabilityState` 'available' | 'degraded' | 'unavailable' | 'scaled_to_zero' | 'cold_start': Current serving classification for compute, Kubernetes, and database rows. `available` means healthy and serving; `degraded` means warning or critical severity while still serving; `unavailable` means a failed or parked resource is not serving. `scaled_to_zero` means an ECS Fargate service has no running tasks; `cold_start` means its tasks are starting and not yet routable. These Fargate lifecycle states are distinct from generic `unavailable`. Do not infer unavailability from status: critical alone. - `isRoutable` boolean: Whether this resource is currently receiving routed traffic. True for available/degraded rows and false for unavailable, scaled_to_zero, or cold_start rows. - `routedRps` number: Current routed requests per second for tracked compute, Kubernetes, and database rows when available. - `offering` string: OpenShift offering associated with this row, when the resource is an OpenShift overlay. - `chargeType` 'platform' | 'control-plane' | 'worker': OpenShift accounting component; platform, control-plane, and worker rows are additive. - `pricingStatus` 'official' | 'estimated': Provenance status for the pricing represented by this row. - `pricingSource` string: Pricing source associated with this row. - `effectiveDate` string: ISO date of the pricing evidence represented by this row. - `referenceRegion` string: Region represented by the published pricing evidence. - `pricingArithmetic` string: Published amount and conversion used for an OpenShift platform/license row. - `billingUnit` '4-vcpu-hour' | 'cluster-hour': Published OpenShift platform billing unit used before topology proration. - `billingUnitVcpu` number: Number of worker vCPUs in one published billing unit; 4 for ARO. - `publishedUnitRatePerHour` number: Published platform rate for one billing unit, before topology proration. For ARO this is $0.171/hour per 4 vCPU in the published East US reference. - `effectiveWorkerCount` integer: Total worker count represented by the derived OpenShift platform charge. - `effectiveWorkerVcpu` number: Total worker vCPU-equivalents used to prorate the published platform unit. - `derivedPlatformFeePerHour` number: Topology-derived platform charge; equals publishedUnitRatePerHour × effectiveWorkerVcpu ÷ billingUnitVcpu for ARO. For three 2-vCPU workers this is $0.2565/hour, not a second published rate. - `workerTopology` object: Per-pool worker quantities used to derive the OpenShift platform charge. - `workerCount` integer, required - `effectiveWorkerVcpu` number, required - `nodePools` object[], required - `name` string, required - `workerCount` integer, required - `workerVcpu` number, required - `effectiveWorkerVcpu` number, required ## Other responses - `401`: No credentials provided to a wallet-session-protected endpoint. The response body includes a machine-readable `walletAuth` block with the endpoints and ordered steps needed to complete EIP-191 wallet authentication and obtain a JWT. - `403`: Access denied — caller does not own this simulation - `404`: Simulation not found, or no metrics record exists yet (simulation not stepped) - `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)