---
title: "Run a stateless synchronous cloud simulation"
method: POST
path: "/simulations/stateless"
tags: ["Execute"]
---

# Run a stateless synchronous cloud simulation

`POST /simulations/stateless`

## Request

- Base URL: `https://www.cloudworldmodel.ai/api`
- URL: `https://www.cloudworldmodel.ai/api/simulations/stateless`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-PAYMENT`
  - API key in header `PAYMENT-SIGNATURE`

Executes a tightly bounded cloud scenario entirely in memory through the
production hybrid, pricing, failure, and autoscaling engine paths. No
simulation, metric, event, result, ownership, or job record is created.
The same seed and input produce the same result. This REST-only operation
requires write scope via a bearer key or one x402 payment; MCP transport
is intentionally omitted because it cannot preserve payment challenge,
settlement, and replay semantics end to end.

## Request body

- object
  - `seed` integer: Deterministic seed for reproducible execution with identical input.
  - `steps` integer: Number of simulation steps to execute synchronously.
  - `resources` object[], required: Required resource graph to model; each resource needs an ID, name, type, and provider.
    - `id` string, required: Unique caller-supplied identifier used to connect and target this resource.
    - `name` string, required: Human-readable resource name shown in simulation results.
    - `type` 'compute' | 'database' | 'storage' | 'network' | 'cache' | 'queue' | 'kubernetes', required: Modeled cloud resource category.
    - `provider` 'aws' | 'gcp' | 'azure' | 'oci' | 'digitalocean', required: Cloud provider whose resource and pricing model to use.
    - `characteristics` object: Optional provider-specific sizing and behavior settings for this resource.
      - `instanceType` string: Compatibility alias for size. If size is omitted, this value is canonicalized into size; if both are supplied they must match, with size remaining canonical.
      - `size` string: Provider size or SKU used to resolve modeled capacity and hourly price.
      - `serviceFamily` string: Provider service family used to select resource-specific behavior and rates.
      - `maxThroughput` number: Optional modeled maximum request throughput for the resource.
      - `baseLatency` number: Optional baseline request latency in milliseconds.
      - `costMultiplier` number: Optional multiplier applied to the resource's modeled hourly cost.
      - `maxConnections` integer: Maximum concurrent database connections used for pool-capacity modeling.
      - `connectionDemand` object: Optional database connection-demand model. Declared counts are ASSUMPTION / plan-time budgets, not live connection observations. Omission preserves the load-derived behavior. Over-budget declared demand adds a bounded rule-based pool-saturation error signal; it is not a provider-calibrated rate. The optional saturationErrorThreshold suppresses the load-derived pool error below the configured utilization without changing connection capacity.
        - `mode` 'load-derived' | 'declared' | 'max', required: load-derived uses the existing RPS-derived estimate; declared ignores instantaneous RPS; max uses the greatest of load-derived and declared/floor demand.
        - `saturationErrorThreshold` number: Optional threshold for the load-derived pool error curve. Below it, connection-pool saturation adds no errors; above it, the curve rises with utilization beyond the threshold. When multiple databases exist, set the same value on all of them for this override to apply. Does not change connection capacity.
        - `declaredConnections` integer: ASSUMPTION / plan-time peak pool budget, e.g. replicas × per-pod pool size; not observed live DB connections.
        - `idlePoolFloor` integer: ASSUMPTION / plan-time minimum idle pool footprint; not observed live DB connections.
      - `nodeCount` integer: Initial Kubernetes worker-node count.
      - `minNodes` integer: Minimum Kubernetes worker-node count when autoscaling is enabled.
      - `maxNodes` integer: Maximum Kubernetes worker-node count when autoscaling is enabled.
      - `autoscaling` boolean: Whether the resource may scale within its configured bounds.
      - `pricingModel` 'on-demand' | 'spot': Modeled Kubernetes node pricing class.
      - `eksSpotInterruption` object
        - `enabled` true
        - `triggerAtStep` integer
        - `noticeWindowSeconds` 120
        - `simulationSecondsPerStep` number
        - `workloadReplicas` integer
        - `imageSizeMiB` number
        - `imageCacheState` 'warm' | 'cold'
        - `imageCacheHit` boolean
        - `pullBandwidthMiBPerSecond` number
        - `schedulingCapacity` integer
        - `startupSeconds` number
        - `interruptionHandling` 'reschedule' | 'drain-only' | 'fail-fast'
  - `connections` object[]: Optional directed resource links; each connection identifies a source and target resource.
    - `sourceId` string, required: ID of the resource sending traffic or requests along this connection.
    - `targetId` string, required: ID of the resource receiving traffic or requests along this connection.
  - `traffic` object, required: Required starting traffic and optional one-time traffic change during the run.
    - `initialRps` integer, required: Starting offered request rate in requests per second.
    - `change` object
      - `atStep` integer, required: One-based simulation step at which to change the offered request rate.
      - `targetRps` integer, required: Offered request rate in requests per second from atStep onward.
  - `autoscaling` object: Optional compute fleet autoscaling bounds and CPU target.
    - `minInstances` integer: Minimum number of compute instances retained by autoscaling.
    - `maxInstances` integer: Maximum number of compute instances autoscaling may create.
    - `targetCpuPercent` number: CPU utilization target used to make autoscaling decisions.
  - `failure` object: Optional single failure to inject against one resource during the run.
    - `type` 'instance_kill' | 'instance_down' | 'az_outage' | 'database_overload' | 'network_latency' | 'spot_interruption', required: Failure mode to inject during the synchronous run.
    - `targetResourceId` string, required: ID of the resource affected by the failure.
    - `atStep` integer, required: One-based simulation step when the failure starts.
    - `durationSteps` integer: Number of simulation steps for which the failure remains active.
    - `spotInterruption` object
      - `triggerAtStep` integer
      - `noticeWindowSeconds` 120
      - `simulationSecondsPerStep` number
      - `workloadReplicas` integer
      - `imageSizeMiB` number
      - `imageCacheState` 'warm' | 'cold'
      - `imageCacheHit` boolean
      - `pullBandwidthMiBPerSecond` number
      - `schedulingCapacity` integer
      - `startupSeconds` number
      - `interruptionHandling` 'reschedule' | 'drain-only' | 'fail-fast'

## Response `200`

Synchronous stateless simulation result

- object
  - `execution` object, required
    - `stateless` boolean, required
    - `synchronous` boolean, required
    - `steps` integer, required
    - `seed` integer, required
    - `engineVersion` string, required
  - `cost` object, required
    - `baselinePerHourUsd` number, required
    - `finalPerHourUsd` number, required
    - `deltaPerHourUsd` number, required
    - `deltaPercent` number, required
  - `performance` object, required
    - `latencyPercentileStatus` 'modeled' | 'unavailable', required
    - `latencyUnavailableReason` string
    - `latencyP50Ms` number, nullable, required
    - `latencyP95Ms` number, nullable, required
    - `latencyP99Ms` number, nullable, required
    - `throughputRps` number, required
  - `autoscaling` object, required: Normalized autoscaling settings and the fleet size materialized before the first step.
    - `enabled` boolean, required
    - `requestedMinInstances` integer, nullable, required
    - `requestedMaxInstances` integer, nullable, required
    - `effectiveMinInstances` integer, nullable, required
    - `effectiveMaxInstances` integer, nullable, required
    - `targetCpuPercent` number, nullable, required
    - `initialFleetSize` integer, required
  - `utilization` object, required
    - `cpuPercent` number, required
    - `memoryPercent` number, required
    - `kubernetesNodePercent` number
    - `resourceCount` integer, required
  - `error` object, required
    - `ratePercent` number, required
    - `successfulThroughputRps` number, required
    - `breakdown` object, nullable, required
      - `staleDNS` number: Modeled stale-DNS failed-request contribution in percentage points, included in ratePercent.
      - `poolSaturation` number, required
      - `databasePressure` number: Provider-fit database connection pressure below the usable pool limit; shares a 5-point cap with poolSaturation.
      - `dbFailure` number, required
      - `computeFailure` number, required
      - `capacityOverload` number, required
      - `cpuOverload` number, required
      - `ociStorage` number, required
      - `queueAbsorption` number, required
      - `dependencyFailure` number
      - `runtimeMemory` number
      - `endpointPropagation` number
      - `startupBackpressure` number
  - `reliability` object, required
    - `availabilityPercent` number, required
    - `unavailableResourceIds` string[], required
    - `failureApplied` boolean, required
  - `eksSpotInterruptions` EksSpotInterruptionTelemetry[], required: Final deterministic EKS Spot interruption telemetry for each configured lifecycle, including optional authoritative seeded migrationEvaluation and field-level provenance.
    - `resourceId` string, required
    - `name` string, required
    - `phase` 'armed' | 'notice' | 'terminated' | 'complete', required
    - `interruptionNotice` boolean, required
    - `triggerAtStep` integer, required
    - `noticeWindowSeconds` 120, required
    - `elapsedNoticeSeconds` number, required
    - `remainingDeadlineSeconds` number, required
    - `affectedWorkloadCount` integer, required
    - `pendingWorkloadCount` integer, required
    - `pullingWorkloadCount` integer, required
    - `startingWorkloadCount` integer, required
    - `readyWorkloadCount` integer, required
    - `missedDeadlineWorkloadCount` integer, required
    - `drainProgress` number, required
    - `imagePullProgress` number, required
    - `startupProgress` number, required
    - `unavailableNodeCount` integer, required
    - `replacementNodeCount` integer, required
    - `migrationEvaluation` EksSpotMigrationEvaluation: Additive immutable deadline evaluation for one seeded characteristics.eksSpotInterruption lifecycle. It is independent of the resource phase and later service health. All times use the simulation clock, never HTTP retrieval or event wall-clock time. migrationDurationSeconds is derived only as allAffectedWorkloadsReadyAtSimulationSeconds minus interruptionNoticeAtSimulationSeconds when both recorded milestones exist; otherwise it is null.
      - `status` 'not_started' | 'in_progress' | 'completed', required
      - `deadlineSeconds` 120, required
      - `deadlineMet` boolean, nullable, required: Null until evaluation completes; frozen once evaluated.
      - `interruptionNoticeAtSimulationSeconds` number, nullable, required
      - `deadlineAtSimulationSeconds` number, nullable, required
      - `migrationStartedAtSimulationSeconds` number, nullable, required
      - `allAffectedWorkloadsReadyAtSimulationSeconds` number, nullable, required
      - `migrationDurationSeconds` number, nullable, required: Derived notice-to-all-ready duration; null when all-ready was not recorded.
      - `affectedWorkloadCount` integer, nullable, required
      - `readyWorkloadCountAtDeadline` integer, nullable, required
      - `missedDeadlineWorkloadCount` integer, nullable, required
      - `evaluatedAtSimulationSeconds` number, nullable, required
      - `limitingReasons` EksSpotMigrationEvaluationReason[], required
        - `code` 'no_reschedule' | 'scheduling_capacity_exhausted' | 'image_pull_incomplete' | 'startup_incomplete' | 'unclassified_runtime_work_remaining', required: Stable reason code based on recorded residual pull/startup/scheduling work.
        - `workloadCount` integer, required
        - `pendingWorkloadCount` integer, required
        - `pullingWorkloadCount` integer, required
        - `startingWorkloadCount` integer, required
        - `residualPullSeconds` number, required
        - `residualStartupSeconds` number, required
        - `schedulingCapacity` integer, required
        - `interruptionHandling` 'reschedule' | 'drain-only' | 'fail-fast', required
        - `provenance` 'recorded', required
      - `fieldProvenance` object, required: Field-name keyed provenance for every exposed evaluation value.
        - `status` EksSpotEvaluationFieldProvenance, required: Field-level source classification for seeded migration evaluation evidence. recorded is direct model/runtime evidence, derived identifies source fields, and unavailable includes an explicit reason.
          - `kind` 'recorded' | 'derived' | 'unavailable', required
          - `sourceFields` string[]: Present for a derived value and names its recorded source fields.
          - `reason` string: Present for unavailable evidence and explains the missing runtime evidence.
        - `interruptionNoticeAtSimulationSeconds` EksSpotEvaluationFieldProvenance, required: Field-level source classification for seeded migration evaluation evidence. recorded is direct model/runtime evidence, derived identifies source fields, and unavailable includes an explicit reason.
          - `kind` 'recorded' | 'derived' | 'unavailable', required
          - `sourceFields` string[]: Present for a derived value and names its recorded source fields.
          - `reason` string: Present for unavailable evidence and explains the missing runtime evidence.
        - `deadlineAtSimulationSeconds` EksSpotEvaluationFieldProvenance, required: Field-level source classification for seeded migration evaluation evidence. recorded is direct model/runtime evidence, derived identifies source fields, and unavailable includes an explicit reason.
          - `kind` 'recorded' | 'derived' | 'unavailable', required
          - `sourceFields` string[]: Present for a derived value and names its recorded source fields.
          - `reason` string: Present for unavailable evidence and explains the missing runtime evidence.
        - `migrationStartedAtSimulationSeconds` EksSpotEvaluationFieldProvenance, required: Field-level source classification for seeded migration evaluation evidence. recorded is direct model/runtime evidence, derived identifies source fields, and unavailable includes an explicit reason.
          - `kind` 'recorded' | 'derived' | 'unavailable', required
          - `sourceFields` string[]: Present for a derived value and names its recorded source fields.
          - `reason` string: Present for unavailable evidence and explains the missing runtime evidence.
        - `allAffectedWorkloadsReadyAtSimulationSeconds` EksSpotEvaluationFieldProvenance, required: Field-level source classification for seeded migration evaluation evidence. recorded is direct model/runtime evidence, derived identifies source fields, and unavailable includes an explicit reason.
          - `kind` 'recorded' | 'derived' | 'unavailable', required
          - `sourceFields` string[]: Present for a derived value and names its recorded source fields.
          - `reason` string: Present for unavailable evidence and explains the missing runtime evidence.
        - `migrationDurationSeconds` EksSpotEvaluationFieldProvenance, required: Field-level source classification for seeded migration evaluation evidence. recorded is direct model/runtime evidence, derived identifies source fields, and unavailable includes an explicit reason.
          - `kind` 'recorded' | 'derived' | 'unavailable', required
          - `sourceFields` string[]: Present for a derived value and names its recorded source fields.
          - `reason` string: Present for unavailable evidence and explains the missing runtime evidence.
        - `deadlineSeconds` EksSpotEvaluationFieldProvenance, required: Field-level source classification for seeded migration evaluation evidence. recorded is direct model/runtime evidence, derived identifies source fields, and unavailable includes an explicit reason.
          - `kind` 'recorded' | 'derived' | 'unavailable', required
          - `sourceFields` string[]: Present for a derived value and names its recorded source fields.
          - `reason` string: Present for unavailable evidence and explains the missing runtime evidence.
        - `deadlineMet` EksSpotEvaluationFieldProvenance, required: Field-level source classification for seeded migration evaluation evidence. recorded is direct model/runtime evidence, derived identifies source fields, and unavailable includes an explicit reason.
          - `kind` 'recorded' | 'derived' | 'unavailable', required
          - `sourceFields` string[]: Present for a derived value and names its recorded source fields.
          - `reason` string: Present for unavailable evidence and explains the missing runtime evidence.
        - `affectedWorkloadCount` EksSpotEvaluationFieldProvenance, required: Field-level source classification for seeded migration evaluation evidence. recorded is direct model/runtime evidence, derived identifies source fields, and unavailable includes an explicit reason.
          - `kind` 'recorded' | 'derived' | 'unavailable', required
          - `sourceFields` string[]: Present for a derived value and names its recorded source fields.
          - `reason` string: Present for unavailable evidence and explains the missing runtime evidence.
        - `readyWorkloadCountAtDeadline` EksSpotEvaluationFieldProvenance, required: Field-level source classification for seeded migration evaluation evidence. recorded is direct model/runtime evidence, derived identifies source fields, and unavailable includes an explicit reason.
          - `kind` 'recorded' | 'derived' | 'unavailable', required
          - `sourceFields` string[]: Present for a derived value and names its recorded source fields.
          - `reason` string: Present for unavailable evidence and explains the missing runtime evidence.
        - `missedDeadlineWorkloadCount` EksSpotEvaluationFieldProvenance, required: Field-level source classification for seeded migration evaluation evidence. recorded is direct model/runtime evidence, derived identifies source fields, and unavailable includes an explicit reason.
          - `kind` 'recorded' | 'derived' | 'unavailable', required
          - `sourceFields` string[]: Present for a derived value and names its recorded source fields.
          - `reason` string: Present for unavailable evidence and explains the missing runtime evidence.
        - `evaluatedAtSimulationSeconds` EksSpotEvaluationFieldProvenance, required: Field-level source classification for seeded migration evaluation evidence. recorded is direct model/runtime evidence, derived identifies source fields, and unavailable includes an explicit reason.
          - `kind` 'recorded' | 'derived' | 'unavailable', required
          - `sourceFields` string[]: Present for a derived value and names its recorded source fields.
          - `reason` string: Present for unavailable evidence and explains the missing runtime evidence.
        - `limitingReasons` EksSpotEvaluationFieldProvenance, required: Field-level source classification for seeded migration evaluation evidence. recorded is direct model/runtime evidence, derived identifies source fields, and unavailable includes an explicit reason.
          - `kind` 'recorded' | 'derived' | 'unavailable', required
          - `sourceFields` string[]: Present for a derived value and names its recorded source fields.
          - `reason` string: Present for unavailable evidence and explains the missing runtime evidence.
    - `checkpointEvidence` EksSpotInterruptionCheckpointEvidence: Persisted seeded-EKS per-metric checkpoint evidence. engineInputStepIndex is the engine input-step timestamp, not seconds; simulationSeconds is derived using the recorded tick. Traffic values remain in the outer metric, and the provenance fields name those outer metric paths.
      - `engineInputStepIndex` integer, required
      - `simulationSeconds` number, required
      - `tickDurationSeconds` number, required
      - `pointRateSemantics` 'post_step_point_rate', required
      - `intervalAttribution` unknown, required
      - `fieldProvenance` object, required
        - `engineInputStepIndex` EksSpotEvaluationFieldProvenance, required: Field-level source classification for seeded migration evaluation evidence. recorded is direct model/runtime evidence, derived identifies source fields, and unavailable includes an explicit reason.
          - `kind` 'recorded' | 'derived' | 'unavailable', required
          - `sourceFields` string[]: Present for a derived value and names its recorded source fields.
          - `reason` string: Present for unavailable evidence and explains the missing runtime evidence.
        - `simulationSeconds` EksSpotEvaluationFieldProvenance, required: Field-level source classification for seeded migration evaluation evidence. recorded is direct model/runtime evidence, derived identifies source fields, and unavailable includes an explicit reason.
          - `kind` 'recorded' | 'derived' | 'unavailable', required
          - `sourceFields` string[]: Present for a derived value and names its recorded source fields.
          - `reason` string: Present for unavailable evidence and explains the missing runtime evidence.
        - `tickDurationSeconds` EksSpotEvaluationFieldProvenance, required: Field-level source classification for seeded migration evaluation evidence. recorded is direct model/runtime evidence, derived identifies source fields, and unavailable includes an explicit reason.
          - `kind` 'recorded' | 'derived' | 'unavailable', required
          - `sourceFields` string[]: Present for a derived value and names its recorded source fields.
          - `reason` string: Present for unavailable evidence and explains the missing runtime evidence.
        - `pointRateSemantics` EksSpotEvaluationFieldProvenance, required: Field-level source classification for seeded migration evaluation evidence. recorded is direct model/runtime evidence, derived identifies source fields, and unavailable includes an explicit reason.
          - `kind` 'recorded' | 'derived' | 'unavailable', required
          - `sourceFields` string[]: Present for a derived value and names its recorded source fields.
          - `reason` string: Present for unavailable evidence and explains the missing runtime evidence.
        - `intervalAttribution` EksSpotEvaluationFieldProvenance, required: Field-level source classification for seeded migration evaluation evidence. recorded is direct model/runtime evidence, derived identifies source fields, and unavailable includes an explicit reason.
          - `kind` 'recorded' | 'derived' | 'unavailable', required
          - `sourceFields` string[]: Present for a derived value and names its recorded source fields.
          - `reason` string: Present for unavailable evidence and explains the missing runtime evidence.
      - `trafficFieldProvenance` object, required
        - `throughputRps` EksSpotEvaluationFieldProvenance, required: Field-level source classification for seeded migration evaluation evidence. recorded is direct model/runtime evidence, derived identifies source fields, and unavailable includes an explicit reason.
          - `kind` 'recorded' | 'derived' | 'unavailable', required
          - `sourceFields` string[]: Present for a derived value and names its recorded source fields.
          - `reason` string: Present for unavailable evidence and explains the missing runtime evidence.
        - `offeredRps` EksSpotEvaluationFieldProvenance, required: Field-level source classification for seeded migration evaluation evidence. recorded is direct model/runtime evidence, derived identifies source fields, and unavailable includes an explicit reason.
          - `kind` 'recorded' | 'derived' | 'unavailable', required
          - `sourceFields` string[]: Present for a derived value and names its recorded source fields.
          - `reason` string: Present for unavailable evidence and explains the missing runtime evidence.
        - `errorRatePercent` EksSpotEvaluationFieldProvenance, required: Field-level source classification for seeded migration evaluation evidence. recorded is direct model/runtime evidence, derived identifies source fields, and unavailable includes an explicit reason.
          - `kind` 'recorded' | 'derived' | 'unavailable', required
          - `sourceFields` string[]: Present for a derived value and names its recorded source fields.
          - `reason` string: Present for unavailable evidence and explains the missing runtime evidence.
        - `latencyP50Ms` EksSpotEvaluationFieldProvenance, required: Field-level source classification for seeded migration evaluation evidence. recorded is direct model/runtime evidence, derived identifies source fields, and unavailable includes an explicit reason.
          - `kind` 'recorded' | 'derived' | 'unavailable', required
          - `sourceFields` string[]: Present for a derived value and names its recorded source fields.
          - `reason` string: Present for unavailable evidence and explains the missing runtime evidence.
    - `workloads` object[], required
      - `id` string, required
      - `state` 'pending' | 'pulling' | 'starting' | 'ready' | 'missed_deadline', required
      - `node` 'interrupted' | 'surviving' | 'replacement'
      - `remainingSeconds` number, required
      - `missedDeadline` boolean: Historical deadline miss marker; live state may later become ready.
  - `coverage` object, required
    - `level` 'full' | 'partial' | 'limited', required
    - `modeledCount` number, required
    - `estimatedCount` number, required
    - `knownGapCount` number, required
    - `notObservableCategories` string[], required
    - `structuralLimitations` string[], required
    - `modeledCostShareOfTotal` number, required
    - `billingPolicyCoverage` object, required
      - `complete` boolean, required
      - `status` 'complete' | 'excluded_policies', required
      - `exclusions` object[], required
    - `resources` object[], required
      - `name` string, required
      - `resourceType` string, required
      - `costFidelity` string, required
      - `behaviourFidelity` string, required
      - `shareOfSimulatedCost` number, required
      - `shareExcluded` boolean
      - `reason` string, required
      - `coverageBasis` 'deterministic' | 'ml' | 'estimated' | 'unsupported', required
      - `note` string
  - `decisions` object, required
    - `blendedSteps` integer, required
    - `fallbackSteps` integer, required
    - `events` object[], required
      - `step` integer, required
      - `severity` string, required
      - `message` string, required
  - `settlement` object: Added by successful x402 settlement; absent for API-key calls.
    - `transactionHash` string
    - `network` string
    - `payer` string
  - `walletSession` object: Short-lived wallet session added by successful x402 settlement; absent for API-key calls.
    - `token` string
    - `expiresAt` string

## Other responses

- `400`: Invalid request data — structured field-level error
- `401`: Authentication required or invalid API key
- `402`: x402 payment required or insufficient credits
- `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)