Create

Create a cloud simulation

Creates a simulation with cloud resources (compute, network, database, storage). The simulation serves as the environment for RL training.

Ownership: If an Authorization: Bearer <key> header is provided, the new simulation is immediately assigned to that API key and is fully write-accessible without any additional steps. Without authentication the simulation is created as a "demo" simulation (apiKeyId: null), subject to a 20-step limit; use POST /simulations/{simulationId}/claim to adopt it once you have a key.

post/simulations

Request

  • Base URL: https://www.cloudworldmodel.ai/api
  • URL: https://www.cloudworldmodel.ai/api/simulations
  • Auth: none required

Request body

OR

Example request

{
  "name": "Production Web App Autoscaling",
  "scenarioId": "web-autoscaling",
  "scenarioOverrides": {
    "sqsQueueBacklogSaturation": {
      "includeEventBurst": true,
      "eventBurstStartStep": 10
    },
    "eksSpotInterruption": {
      "startupSeconds": 60
    },
    "webAutoscaling": {
      "includeTrafficRecovery": true
    },
    "dbFailover": {
      "includeTrafficRecovery": true
    },
    "redisCacheCrashRecovery": {
      "cacheableRequestShare": 0.8,
      "cacheHitRate": 0.8
    }
  },
  "description": "Multi-tier web application with load balancer and database",
  "resources": [
    {
      "id": "ec2-1",
      "type": "compute",
      "name": "Web Server 1",
      "provider": "aws",
      "location": {
        "regionKey": "us-east-2"
      },
      "characteristics": {
        "workload": "crud",
        "appRuntime": "node",
        "appWorkerCount": 2,
        "appDbPoolSize": 250,
        "workloadDatabaseVersion": "8.0",
        "workloadDatabaseEngine": "mysql",
        "rdsSqlServerBilling": {
          "instanceClass": "db.t3.micro",
          "storageType": "gp2",
          "allocatedStorageGiB": 20,
          "durationHours": 480,
          "sustainedCpuPercent": 43
        },
        "serviceFamily": "ec2",
        "containerCpu": 0.5,
        "containerMemoryGiB": 1,
        "runtimeMemoryProfile": {
          "workingSetGiB": 0.78125
        },
        "concurrency": 80,
        "requestDurationSeconds": 0.25,
        "requestServingTargetUtilizationPct": 70,
        "billingState": "stopped",
        "size": "m5.large",
        "instanceType": "t3.medium",
        "ocpus": 4,
        "maxThroughput": 2000,
        "capacityRps": 100,
        "baseLatency": 3,
        "maxConnections": 800,
        "capacityGB": 500,
        "maxIops": 3000,
        "inferenceMode": true,
        "accelerator": "a10g",
        "managedComputePlatform": "nvidia-dgx-cloud",
        "openshiftOffering": "rosa-hcp",
        "topology": {
          "intraNode": "nvlink-nvswitch",
          "interNode": "infiniband"
        },
        "intraNode": "nvlink-nvswitch",
        "interNode": "infiniband",
        "includesControlPlane": true,
        "bundledNetworking": true,
        "trainingMode": true,
        "tokensPerRequest": 500,
        "inputTokensPerRequest": 1000,
        "cacheHitRate": 0.85,
        "cacheableRequestShare": 0.75,
        "asynchronousRequestShare": 0.15,
        "queueConsumerCount": 4,
        "queueDrainRatePerConsumerRps": 125,
        "queueCapacityMessages": 20000,
        "queueSimulationStepSeconds": 1,
        "autoscaling": true,
        "maxInstances": 5,
        "minInstances": 2,
        "scaleOutCpuThreshold": 60,
        "scaleInCpuThreshold": 25,
        "nodeCount": 2,
        "workerVcpu": 4,
        "minNodes": 2,
        "maxNodes": 10,
        "perNodeRate": 3.2,
        "pricingModel": "on-demand",
        "nodePools": [
          {
            "name": "general",
            "nodeCount": 2,
            "workerVcpu": 8,
            "minNodes": 2,
            "maxNodes": 10,
            "perNodeRate": 0.096,
            "maxThroughput": 10000
          }
        ],
        "streamShardsCount": 4,
        "streamWriteRps": 3500,
        "eventNotificationsEnabled": true,
        "partitionCount": 8,
        "streamPartitions": 4,
        "partitionWriteRps": 5000,
        "warmupSteps": 5,
        "warmupSeverity": 0.8
      },
      "routedRps": 15,
      "availabilityState": "available",
      "isRoutable": true,
      "failureParkStepsRemaining": 3,
      "recoveryPolicy": {
        "criticalCpuThreshold": 75,
        "criticalSteps": 2,
        "warningCpuThreshold": 60,
        "warningSteps": 1,
        "failureParkSteps": 2
      }
    }
  ],
  "traffic": 5000,
  "maxInstances": 6,
  "minInstances": 2,
  "autoscalingTargetCpu": 70,
  "scaleOutCpuThreshold": 70,
  "scaleOutCpuPercent": 70,
  "autoscaleTargetCpuPercent": 70,
  "resilienceConfig": {
    "dependencies": [
      {
        "id": "web-to-db",
        "sourceId": "web-1",
        "targetId": "db-1",
        "requestRatio": 1,
        "authDependencyId": "gateway-to-token-service",
        "retryPolicy": {
          "maxRetries": 3,
          "backoffMs": 100,
          "backoffMultiplier": 2,
          "jitterRatio": 0.1,
          "timeoutMs": 2000,
          "retryBudgetRatio": 2,
          "retryBudgetRps": 1000,
          "retryActorId": "gateway_optimistic_retries"
        },
        "capacity": {
          "maxRps": 10000,
          "maxConcurrent": 200,
          "meanServiceTimeMs": 100
        },
        "protection": {
          "circuitBreaker": {
            "failureRateThreshold": 0.5,
            "minimumRequests": 20,
            "openSteps": 3,
            "halfOpenMaxRequests": 10
          },
          "rateLimitRps": 5000
        }
      }
    ],
    "scheduledFaults": [
      {
        "id": "db-capacity-fault",
        "targetResourceId": "db-1",
        "dependencyId": "web-to-db",
        "startStep": 5,
        "endStep": 15,
        "capacityPercent": 30,
        "maxConcurrent": 5,
        "addedLatencyMs": 500,
        "errorRate": 0.3,
        "trafficMultiplier": 2.25
      }
    ],
    "maxCascadeDepth": 4,
    "maxGeneratedRps": 100000,
    "maxStepWork": 512
  }
}

Response

Simulation created successfully

appWeight'lean' | 'typical' | 'heavy'

Immutable root-level simulation.create input. Omission selects typical and appWeightDefaulted=true; explicit typical has identical numerical predictions. In the generic fallback at 100 total RPS across two m5.large apps (50 per server), typical targets 20% app-host CPU, P50 18.5 ms and P95 45 ms, not the deliberately lean benchmark's 1.9% CPU. These are placeholder guidance, not AWS measurements; the separately eligible owned typical Node CRUD workload uses its measured 20/100/200 RPS fit instead. Heavy doubles typical load/latency multipliers as an unsupported product assumption.

appWeightDefaultedboolean

True only when the create request omitted appWeight. Immutable intake provenance.

idstring uuid

Unique simulation identifier

namestring
descriptionstring
trafficnumber
runtimeTrafficOverrideActiveboolean

Server-managed runtime control. When true on the SQS Queue Backlog Saturation scenario, steps ignore finalized traffic patterns without changing replay identity. Callers cannot set this field.

currentTimeinteger

Current simulation time step

scenarioHashstring

Canonical SHA-256 of the persisted scenario graph and attached traffic-pattern order.

effectiveConfigHashstring

Versioned prediction SHA-256 over the replay startup-input hash, engine version, and calibration identity. The original replay-only hash remains at replayIdentity.effectiveConfigHash.

predictionEffectiveConfigHashstring

Engine-versioned prediction identity, separate from the replay-input identity.

engineVersionstring

Simulation engine version used to produce the prediction.

effectiveMaxInstancesinteger

The autoscaled fleet-size ceiling the engine will enforce — autoscalingConfig.maxInstances when set, otherwise the primary provider's default (AWS 50, GCP 15, Azure/OCI/DigitalOcean 10).

effectiveMinInstancesinteger

The autoscaled fleet-size floor the engine will enforce — autoscalingConfig.minInstances when set, otherwise the primary provider's default.

Example response

{
  "resources": [
    {
      "id": "ec2-1",
      "type": "compute",
      "name": "Web Server 1",
      "provider": "aws",
      "location": {
        "regionKey": "us-east-2"
      },
      "characteristics": {
        "workload": "crud",
        "appRuntime": "node",
        "appWorkerCount": 2,
        "appDbPoolSize": 250,
        "workloadDatabaseVersion": "8.0",
        "workloadDatabaseEngine": "mysql",
        "rdsSqlServerBilling": {
          "instanceClass": "db.t3.micro",
          "storageType": "gp2",
          "allocatedStorageGiB": 20,
          "durationHours": 480,
          "sustainedCpuPercent": 43
        },
        "serviceFamily": "ec2",
        "containerCpu": 0.5,
        "containerMemoryGiB": 1,
        "runtimeMemoryProfile": {
          "workingSetGiB": 0.78125
        },
        "concurrency": 80,
        "requestDurationSeconds": 0.25,
        "requestServingTargetUtilizationPct": 70,
        "billingState": "stopped",
        "size": "m5.large",
        "instanceType": "t3.medium",
        "ocpus": 4,
        "maxThroughput": 2000,
        "capacityRps": 100,
        "baseLatency": 3,
        "maxConnections": 800,
        "capacityGB": 500,
        "maxIops": 3000,
        "inferenceMode": true,
        "accelerator": "a10g",
        "managedComputePlatform": "nvidia-dgx-cloud",
        "openshiftOffering": "rosa-hcp",
        "topology": {
          "intraNode": "nvlink-nvswitch",
          "interNode": "infiniband"
        },
        "intraNode": "nvlink-nvswitch",
        "interNode": "infiniband",
        "includesControlPlane": true,
        "bundledNetworking": true,
        "trainingMode": true,
        "tokensPerRequest": 500,
        "inputTokensPerRequest": 1000,
        "cacheHitRate": 0.85,
        "cacheableRequestShare": 0.75,
        "asynchronousRequestShare": 0.15,
        "queueConsumerCount": 4,
        "queueDrainRatePerConsumerRps": 125,
        "queueCapacityMessages": 20000,
        "queueSimulationStepSeconds": 1,
        "autoscaling": true,
        "maxInstances": 5,
        "minInstances": 2,
        "scaleOutCpuThreshold": 60,
        "scaleInCpuThreshold": 25,
        "nodeCount": 2,
        "workerVcpu": 4,
        "minNodes": 2,
        "maxNodes": 10,
        "perNodeRate": 3.2,
        "pricingModel": "on-demand",
        "nodePools": [
          {
            "name": "general",
            "nodeCount": 2,
            "workerVcpu": 8,
            "minNodes": 2,
            "maxNodes": 10,
            "perNodeRate": 0.096,
            "maxThroughput": 10000
          }
        ],
        "streamShardsCount": 4,
        "streamWriteRps": 3500,
        "eventNotificationsEnabled": true,
        "partitionCount": 8,
        "streamPartitions": 4,
        "partitionWriteRps": 5000,
        "warmupSteps": 5,
        "warmupSeverity": 0.8
      },
      "routedRps": 15,
      "availabilityState": "available",
      "isRoutable": true,
      "failureParkStepsRemaining": 3,
      "recoveryPolicy": {
        "criticalCpuThreshold": 75,
        "criticalSteps": 2,
        "warningCpuThreshold": 60,
        "warningSteps": 1,
        "failureParkSteps": 2
      }
    }
  ],
  "normalizedConfig": {
    "resources": [
      {
        "rdsSqlServerBilling": {
          "input": {
            "instanceClass": "db.t3.micro",
            "storageType": "gp2",
            "allocatedStorageGiB": 20,
            "durationHours": 480,
            "sustainedCpuPercent": 43
          }
        },
        "rateProvenance": {
          "sku": "m7g.large",
          "source": "AWS EC2 Price List API (Linux, shared tenancy, on-demand)"
        },
        "dynamoDbBilling": {
          "referenceRequestRateRps": 50000
        },
        "requestServing": {
          "serviceFamily": "lambda"
        },
        "behaviorModel": {
          "latencyPath": "gpu-inference/ttft-decode",
          "description": "Token-economics model: TTFT + decode, weighted by throughput and batch pressure.",
          "modelingNote": "TTFT and decode-throughput figures are CWM simulation-model estimates, not externally measured hardware benchmarks.",
          "topologyThroughputFactor": 0.92,
          "topologyThroughputCalibrationStatus": "estimated",
          "ibNetworkingCostPerNodePerHour": 2
        },
        "inferenceWarnings": [
          "Resource has inference/GPU characteristics (accelerator: h100, tokensPerRequest: 512) but inferenceMode is not enabled. The generic-kubernetes/load-saturation latency model will be used. Set characteristics.inferenceMode: true to activate gpu-inference/ttft-decode."
        ]
      }
    ]
  },
  "resilienceConfig": {
    "dependencies": [
      {
        "id": "web-to-db",
        "sourceId": "web-1",
        "targetId": "db-1",
        "requestRatio": 1,
        "authDependencyId": "gateway-to-token-service",
        "retryPolicy": {
          "maxRetries": 3,
          "backoffMs": 100,
          "backoffMultiplier": 2,
          "jitterRatio": 0.1,
          "timeoutMs": 2000,
          "retryBudgetRatio": 2,
          "retryBudgetRps": 1000,
          "retryActorId": "gateway_optimistic_retries"
        },
        "capacity": {
          "maxRps": 10000,
          "maxConcurrent": 200,
          "meanServiceTimeMs": 100
        },
        "protection": {
          "circuitBreaker": {
            "failureRateThreshold": 0.5,
            "minimumRequests": 20,
            "openSteps": 3,
            "halfOpenMaxRequests": 10
          },
          "rateLimitRps": 5000
        }
      }
    ],
    "scheduledFaults": [
      {
        "id": "db-capacity-fault",
        "targetResourceId": "db-1",
        "dependencyId": "web-to-db",
        "startStep": 5,
        "endStep": 15,
        "capacityPercent": 30,
        "maxConcurrent": 5,
        "addedLatencyMs": 500,
        "errorRate": 0.3,
        "trafficMultiplier": 2.25
      }
    ],
    "maxCascadeDepth": 4,
    "maxGeneratedRps": 100000,
    "maxStepWork": 512
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.