--- title: "Fetch partial multi-cloud results from a running job" method: GET path: "/multi-cloud/jobs/{jobId}/partial-results" tags: ["Multi-Cloud Strategy"] --- # Fetch partial multi-cloud results from a running job `GET /multi-cloud/jobs/{jobId}/partial-results` ## Request - Base URL: `https://www.cloudworldmodel.ai/api` - URL: `https://www.cloudworldmodel.ai/api/multi-cloud/jobs/{jobId}/partial-results` - Auth: one of: - HTTP bearer - API key in header `X-PAYMENT` - API key in header `PAYMENT-SIGNATURE` Retrieve strategies accumulated so far for a multi-cloud exploration job, even while the job is still running. This endpoint is the dedicated channel for polling partial results during job execution. The `/results` endpoint requires the job to be completed; use this endpoint instead when you want to start analyzing strategies before the full exploration finishes. **Polling pattern:** ``` while true: data = GET /api/multi-cloud/jobs/{jobId}/partial-results show data.allStrategies to user if data.isComplete: break sleep(2s) # Fetch ranked results and comparison report from /results once complete full = GET /api/multi-cloud/jobs/{jobId}/results ``` **isComplete flag:** - `false` — job is still `pending` or `running`; more strategies may arrive - `true` — job has reached a terminal state (`completed`, `failed`, or `cancelled`) **When `isComplete` is true and `status` is `completed`**, fetch the ranked `topStrategies` and `comparisonReport` from `GET /api/multi-cloud/jobs/{jobId}/results`. ## Path parameters - `jobId` string, uuid, required ## Query parameters - `providers` string ## Response `200` Partial or terminal results for the job - object - `jobId` string, required - `status` 'pending' | 'running' | 'completed' | 'failed' | 'cancelled', required - `progress` number, required: Job progress percentage (0-100) - `isComplete` boolean, required: True if job has reached a terminal state, false if still pending or running - `strategiesGenerated` number, required: Number of strategies generated so far - `allStrategies` Strategy[], required: All raw strategies generated so far - `id` string, required: Unique strategy identifier - `name` string, required: Strategy name - `description` string, required: Strategy description - `allocations` ProviderAllocation[], required: Provider allocations in this strategy - `provider` 'aws' | 'gcp' | 'azure' | 'oci' | 'digitalocean': Cloud provider name - `computeInstances` integer: Number of compute instances on this provider - `databaseInstances` integer: Number of database instances on this provider - `storageGB` integer: Storage allocated to this provider (GB) - `trafficPercentage` number: Percentage of traffic routed to this provider - `regions` string[]: Regions used on this provider - `skuClass` string, required: Primary product-class label for this allocation. Derived from the two per-dimension fields below (`computeSkuClass`, `databaseSkuClass`) using the following precedence: if `computeSkuClass` is non-default (i.e. `do-droplet`, `bare-metal-compute`, or `free-tier-compute`), that compute class is used even when a `databaseSkuClass` is also present. Otherwise the `databaseSkuClass` is used when present; the final fallback is `general-compute`. Allocations that share the same `skuClass` are cost-comparable at the class level; allocations with different values are not directly comparable — see the parent Strategy's `crossClassNote` when present. - `computeSkuClass` string: Compute-dimension SKU class for this allocation. `general-compute` — standard dedicated-vCPU VMs (EC2, Compute Engine, Azure VMs, OCI VM.Standard/Flex; the default when no specific compute family is set), `do-droplet` — DigitalOcean Droplets (shared-vCPU cloud VMs; different resource model and performance guarantees from dedicated-vCPU instances), `free-tier-compute` — always-free / zero-cost compute (OCI Always Free AMD micro VMs; costs excluded from estimate totals), `bare-metal-compute` — dedicated bare-metal servers (OCI BM.Standard3.64, BM.Optimized3.36; no hypervisor overhead, full core isolation). Always present after annotation; defaults to `general-compute`. - `databaseSkuClass` string: Database-dimension SKU class for this allocation. Absent when no database service family is set (allocation carries no bespoke database tier). `managed-rdbms` — provisioned relational databases (RDS, Cloud SQL, Azure SQL, …), `oci-heatwave` — OCI MySQL HeatWave DB System and HeatWave Analytics Cluster (in-memory analytics accelerator; distinct billing model and capability profile from standard managed-rdbms — not directly cost-comparable), `serverless-db` — pay-per-use / auto-scaling databases (Aurora Serverless, Cloud Spanner, Autonomous DB, …), `managed-nosql` — wide-column or key-value NoSQL (Bigtable SSD/HDD, …). - `metrics` StrategyMetrics, required - `totalCostPerHour` number: Total hourly cost across all providers - `avgLatencyMs` number: Average latency (P50 estimate) in milliseconds - `p95LatencyMs` number: Estimated P95 latency in milliseconds (avgLatencyMs × 1.5) - `vendorLockInScore` number: Vendor lock-in score (0-100, higher = more locked in / harder to migrate away). Single-provider strategies score 55-84 depending on service proprietary-ness (Aurora Serverless scores higher than standard RDS); multi-provider strategies score 20-50 depending on traffic distribution and provider count. - `dataPortabilityScore` number: Data portability score (0-100, higher = more portable) - `geographicCoverage` number: Geographic coverage score (0-100) - `compositeScore` number: Overall weighted composite score (0-10) - `migrationEgressCost` number: One-time data-migration egress cost estimate (USD) — the cost of moving the workload's stored data out of the source provider. Computed as `EGRESS_PER_GB_RATES[sourceProvider] × storageGB`. Always present; zero-valued strategies have zero storage in the workload profile. - `egressCostPerHour` number: Estimated ongoing internet egress cost per hour (USD) — the recurring cost of serving outbound responses to external users. Derived from `trafficRPS` using a 2 KB average response payload (RPS × 3600 s/hr × 0.000002 GB/request) and each provider's `INTERNET_EGRESS_RATES` overage rate (USD/GB), after deducting each provider's free monthly egress allowance (converted to an hourly GB budget): OCI 10,000 GB/month (Always Free, flat), DigitalOcean 1,000 GB/instance/month (scales with computeInstances), AWS 100 GB/month, GCP 200 GB/month (Americas), Azure 5 GB/month. For multi-provider strategies the cost is traffic-share-weighted across all allocations. This estimate is added into `totalCostPerHour` so rankings reflect the full ongoing cost including egress. Absent only on strategies with zero traffic. Volume within a provider's free tier produces `egressCostPerHour: 0`. - `latencyHeadroomPct` number: How far below the user's latency SLO this strategy sits, expressed as a percentage of the SLO limit. Computed as max(0, (SLO − p95LatencyMs) / SLO × 100). A value of 13.75 means p95 latency is 13.75% below the SLO limit — the strategy has that much buffer before it would breach the target. 0 means the strategy is at or above the SLO limit. Absent for strategies that exceed the SLO. - `tradeoffs` string[], required: Key tradeoffs of this strategy - `recommendations` string[], required: Recommendations for this strategy - `suggestedResources` object[]: Materializable SKU objects for each resource type in this strategy. Each entry identifies the canonical instance size, unit count, and per-unit hourly rate so consumers can pre-populate infrastructure manifests or compare costs directly. - `provider` 'aws' | 'gcp' | 'azure' | 'oci' | 'digitalocean', required - `resourceType` 'compute' | 'database' | 'storage', required - `size` string, required: Canonical instance/SKU identifier (e.g. "t3.medium", "db.t3.medium", "s3-standard") - `count` number, required: Number of instances (or GB for storage) - `hourlyRate` number, required: Per-unit hourly cost in USD - `securityRecommendations` string[]: Security product identifiers recommended for this strategy (e.g. `aws-waf`, `gcp-cloud-armor`, `azure-waf`, `oci-waf`). These are WAF/firewall palette IDs that operators can add to protect each provider footprint. - `crossClassNote` string: Present only when this strategy's allocations span more than one class in either the compute dimension (comparing `computeSkuClass` values) or the database dimension (comparing `databaseSkuClass` values). Each dimension is evaluated independently so a compute-tier mismatch is never masked by a shared database tier, and vice-versa. The note names the mismatched dimension(s) and warns that cost and latency figures across those allocations may not be directly comparable because they model different product tiers. Absent when all allocations share the same class in both dimensions. - `costBreakdown` ProviderCostBreakdown[], required: Per-provider cost breakdown for this strategy. One entry per provider allocation, each showing compute, database, storage, and egress costs attributed to that provider's slice of the workload. `egressCostPerHour` in each entry reflects the overage cost after deducting the provider's free monthly egress allowance (see `ProviderCostBreakdown`). `totalCostPerHour` in each entry is the sum of all four line items for that slice. - `provider` 'aws' | 'gcp' | 'azure' | 'oci' | 'digitalocean', required: Cloud provider for this allocation slice - `computeCostPerHour` number, required: Hourly compute cost for this provider slice (USD) - `databaseCostPerHour` number, required: Hourly database cost for this provider slice (USD) - `storageCostPerHour` number, required: Hourly storage cost for this provider slice (USD) - `egressCostPerHour` number, required: Hourly internet egress cost attributed to this provider slice (USD), after deducting the provider's free monthly egress allowance (converted to an hourly GB budget — ÷ 730). Free allowances: OCI 10,000 GB/month (Always Free, flat), DigitalOcean 1,000 GB/instance/month (scales with computeInstances), AWS 100 GB/month, GCP 200 GB/month (Americas), Azure 5 GB/month. Volume within the free tier produces zero. Zero also when trafficRPS is 0. - `totalCostPerHour` number, required: Sum of compute + database + storage + egress costs for this slice (USD) - `computeInstances` number, required: Number of compute instances in this provider slice - `databaseInstances` number, required: Number of database instances in this provider slice - `storageGB` number, required: Total storage provisioned in this provider slice (GB) - `computeUnitRate` number: Per-instance hourly compute rate used for this slice (USD/hr) - `databaseUnitRate` number: Per-instance hourly database rate used for this slice (USD/hr) - `storageUnitRate` number: Per-GB storage rate used (USD/GB/hr, on a per-1000-GB basis) - `egressFreeTierExhaustedAtRPS` number: The requests-per-second (RPS) threshold at which this provider's hourly egress free-tier allowance is fully consumed, given the current traffic share and instance count. Below this value egressCostPerHour is $0; above it the overage rate applies. Computed as Math.round(freeHourlyGB / (RPS_TO_GB_PER_HOUR × share)), where RPS_TO_GB_PER_HOUR = 0.0072 and freeHourlyGB = monthlyFreeGB / 730 (DigitalOcean scales by computeInstances). Omitted when trafficPercentage is 0 or when the provider has no free egress allowance. - `databaseServiceFamily` string: Database product sub-family override applied to this slice (e.g. "cloud-sql", "aurora-serverless", "autonomous-db"). Absent when the provider's default managed database rate is used. - `providerTrustLevels` object: Per-provider rate trust level — the worst rateProvenance.basis across the pricing constants behind that provider's cost figures, derived from strategies accumulated so far. "on-demand" means every contributing rate is a verified published list price; "estimated" means at least one contributing rate is a flat or usage-based floor approximation (e.g. Aurora Serverless v2/DSQL, GPU inference families). Present for every job status; updates as strategies accumulate. Empty object while no strategies exist yet. - `preProvisionVerdict` PreProvisionVerdict: Conservative machine-readable verdict for the highest-ranked returned strategy. Exploration alone cannot return ship. The verdict endpoint can return ship when cost, latency, error-budget and recorded caller-attested resilience checks all pass. This is a planning decision, not independent verification or a production guarantee. - `decision` 'ship' | 'hold' | 'ship_with_changes', required: hold means a known supplied budget or latency requirement failed, or no candidate is available. ship_with_changes means the visible checks have no known failure but evidence or explicit budgets are missing. ship requires every required check to pass. - `candidateFingerprint` string, nullable, required: SHA-256 identity of the candidate ID, allocations, suggested resources and workload. Retain with test inputs; null when no candidate exists. - `strategy` PreProvisionVerdictStrategy, required - `id` string, required - `name` string, required - `reasons` object[], required - `code` 'no_candidate_strategy' | 'cost_budget_exceeded' | 'latency_slo_missed' | 'error_budget_exceeded' | 'resilience_validation_required' | 'resilience_check_failed' | 'resilience_evidence_insufficient' | 'required_checks_incomplete' | 'required_checks_passed', required - `message` string, required - `evidence` object, required - `cost` object, required - `estimatedPerHour` number, nullable, required: Modeled total cost per hour, including modeled egress. - `budgetCheck` 'pass' | 'fail' | 'not_provided', required - `latency` object, required - `estimatedP95Ms` number, nullable, required - `requirementMs` number, required - `sloCheck` 'pass' | 'fail' | 'not_evaluated', required - `headroomPct` number, nullable, required - `errorRate` object, required - `modeledFraction` number, nullable, required: Allocation-count-based modeled proxy, not an observed failure rate. - `budgetCheck` 'pass' | 'fail' | 'not_provided', required - `resilience` object, required - `status` 'not_evaluated' | 'pass' | 'fail', required - `reason` string, required - `provenance` 'recorded' | 'estimated' - `verification` 'caller_attested' - `report` CompletedResilienceEvidence: Caller-attested completed test report for the exact candidateFingerprint. Keep the fingerprint with the actual test inputs; never relabel a report from another architecture or workload. Recorded means observations recorded during the test, not externally verified production evidence. Estimated reports remain unevaluated for deployment gating. - `candidateFingerprint` string, required - `reportRef` string, required - `status` 'completed', required - `completedAt` string, date-time, required: Actual completion timestamp, not in the future. - `provenance` 'recorded' | 'estimated', required - `failureInjected` boolean, required - `recoveryObserved` boolean, required - `finalHealthy` boolean, required - `resilienceCheck` 'pass' | 'fail' | 'not_evaluated', required - `scope` string, required: Tested failures, test coverage, and pass criteria. - `uncertainty` object, required - `dataSource` 'simulation-model', required - `externallyValidated` false, required - `providerRateTrust` object, required - `limitations` string[], required - `methodology` object: Describes the data origin and validation basis for these results. Agents should read this object before interpreting cross-provider rankings or citing consistency across multiple independent runs as external evidence. - `dataSource` 'simulation-model': Origin of the result data. simulation-model means results come from the Cloud World Model deterministic simulation engine. - `validationBasis` 'simulation_only' | 'calibrated_public_data' | 'provider_benchmark' | 'customer_observed' | 'mixed': Characterises how the underlying data has been validated externally. Currently only simulation_only is emitted. - `externallyValidated` boolean: Convenience boolean — false whenever validationBasis is simulation_only. - `seedCount` integer: The number of random seeds used in this job own simulation. Always 1 per job. - `note` string: Authoritative plain-English statement for agents calibrating recommendation language. Static across all runs. - `interpretationScope` object: Machine-readable interpretation constraints attached alongside methodology. Agents must consult this object before forming any conclusion about provider performance. - `providerPerformanceScope` 'simulation-only': Scope of any provider-performance statement derivable from these results. Currently only simulation-only is emitted; future values (calibrated, empirically-validated) may be added without breaking change. - `externalValidation` boolean: Mirrors methodology.externallyValidated so agents that reach interpretationScope first get an unambiguous false without cross-referencing. - `crossSeedConsistencyMeans` 'simulation-model-consistency': Agreement across seeds proves the model is deterministic, not that cloud providers behave that way. - `untestedLoadExtrapolationAllowed` boolean: When false, any load level outside testedLoadLevels must be presented as a hypothesis requiring a new simulation, not a derived conclusion. - `prohibitedClaimCategories` string[]: Machine-readable constraint list; agents must check planned conclusions against each entry. Category labels are hyphenated enum tokens, not prose. - `permittedUses` string[]: What these results may legitimately be used for. - `testedLoadLevels` string[]: Derived from job config; only these levels are validated by this simulation run. - `untestedScenariosNote` string: Authoritative sentence defining how untested scenarios must be labelled. - `error` string: Error message — only present when status is failed ## 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. - `404`: Resource not found --- [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)