---
title: "Run a chaos engineering test"
method: POST
path: "/chaos/run"
tags: ["Execute"]
---

# Run a chaos engineering test

`POST /chaos/run`

## Request

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

Execute a chaos engineering test by injecting failures into a simulation.
Can use pre-built scenarios or custom failure injections.

This endpoint works with simulations built on **any supported provider**,
including AWS, GCP, Azure, OCI, and **DigitalOcean**. When targeting a
DigitalOcean-based simulation, failure types such as `kill_instance`
affect Droplets, `zone_failure` targets DigitalOcean datacenter regions,
and `database_crash` targets Managed Database clusters.

**Failure naming surfaces** — three zone-related names, three different contexts:
- `zone_outage` — custom injection type in `customInjections[].failureType` (this endpoint)
- `az_outage` — failure type in the synchronous `POST /simulations/{id}/failures` API
- `zone_failure` — pre-built scenario ID used in `scenarioId`

**Multi-fault cascade example** — inject a zone outage and a database slowdown simultaneously
via `customInjections` to test correlated failure handling:

```json
{
  "simulationId": "sim-abc123",
  "customInjections": [
    { "failureType": "zone_outage", "targetZone": "us-east-1a", "duration": 120 },
    { "failureType": "database_slowdown", "targetResourceId": "db-primary", "intensity": 80, "duration": 120 }
  ]
}
```

For `database_crash` custom injections, `promotionDelaySeconds` (default 30)
and `restartDelaySeconds` (default 1800) are bounded integer simulation-clock
assumptions, not measured provider behavior or SLAs. A healthy database
explicitly linked by `replicaOf` promotes after the first delay; without
one, the writer restarts after the injection duration plus the second delay.
Crashes scheduled for the same simulation instant are considered together:
a simultaneously crashed replica is not eligible. In that case the writer
uses sole_writer_restart, with promotionUnavailableReason set to
related_replica_unavailable_at_injection; a replica lost after promotion
was announced instead produces an Explicit replica promotion failed event.
`multiAz` and `instanceCount` do not imply an eligible replica. The chosen
effective values are returned per target in
`resilienceScore.metrics.databaseCrashAssumptions`.
While no database serves, positive offered work has 100% errors and zero
goodput; promotion restores service without a residual writer-outage
penalty. Chaos samples every 10 simulation seconds (default promotion
at 30 seconds). Quick `inject-failure` instead advances one simulation
second per step, promotes on the second step (one second after injection),
and rejoins after its bounded park window. Compare equivalent
unavailable/serving phases, not equal step indices or wall-clock times.

The prebuilt `scenarioId: "database_crash"` also accepts these two fields
at the top level of this request (not inside `customInjections`). They
override only this job, not the saved scenario. Other scenario IDs and
custom injections cannot use the top-level fields.

 **Resilience grade** — the `grade` in the result is derived from the
 live weighted `overall` score, including recovery, availability, data
 integrity, and graceful degradation. Vulnerability findings remain
 architectural evidence and may be similar across fault combinations,
 but the grade is not a static SPOF label. To inspect both, pair
 `POST /chaos/run` (vulnerability report) with the synchronous
 `POST /simulations/{id}/failures` + step-loop pattern (live metrics).

## Request body

- object
  - `simulationId` string, uuid, required: ID of the base simulation to test
  - `scenarioId` 'zone_failure' | 'database_crash' | 'network_partition' | 'cascading_failure' | 'random_instance_failure' | 'database_slowdown' | 'database_overload': Pre-built scenario ID (optional)
  - `promotionDelaySeconds` integer: Prebuilt database_crash scenario only: simulated explicit-replica promotion delay (default 30 seconds); not a provider SLA. Cannot be combined with customInjections.
  - `restartDelaySeconds` integer: Prebuilt database_crash scenario only: simulated sole-writer restart delay (default 1800 seconds); not a provider SLA. Cannot be combined with customInjections.
  - `customInjections` object[]: Custom failure injections (optional)
    - `failureType` 'database_crash' | 'database_slowdown' | 'database_overload' | 'zone_outage' | 'region_outage' | 'permanent_data_loss' | 'instance_failure' | 'eks_spot_interruption' | 'network_latency' | 'network_partition' | 'cascading_failure' | 'cpu_stress', required: Type of failure to inject
    - `targetResourceId` string: Internal ID of the specific resource to target (optional)
    - `targetResourceName` string: Resource display name to target instead of an internal ID. Resolved case-insensitively — exact name match first, then unique-prefix match (e.g. "aws-server" finds "aws-server-01"). If the name matches multiple resources the request fails with 400 and a `candidates` list of matching resources.
    - `targetZone` string: Availability zone to target (optional, e.g. for zone_outage)
    - `targetRegion` string: Canonical region key for region_outage or permanent_data_loss.
    - `targetProvider` 'aws' | 'gcp' | 'azure' | 'oci' | 'digitalocean': Cloud provider to scope the injection to (optional)
    - `duration` number: How long the failure lasts in simulation seconds (optional)
    - `promotionDelaySeconds` integer: database_crash only: explicit replica promotion delay in simulation seconds (default 30); not a provider SLA.
    - `restartDelaySeconds` integer: database_crash only: sole-writer restart delay after injection ends in simulation seconds (default 1800); not a provider SLA.
    - `intensity` number: Failure severity from 0 (minimal) to 100 (maximum, optional)
    - `startTime` number: Simulation time at which the failure begins (optional)
    - `affectedResources` string[]: Additional resource IDs affected by the injection (optional)
  - `duration` integer, required: Test duration in simulation steps
  - `webhookUrl` string, uri: Optional HTTPS URL to receive webhook notification when job completes
  - `webhookSecret` string: Optional secret for HMAC-SHA256 webhook signature verification

## Response `202`

Chaos test job accepted and started

- object
  - `jobId` string, uuid: Top-level chaos job ID (mirrors `job.id`) for convenient access.
  - `job` object
    - `id` string, uuid
    - `type` 'chaos_test'
    - `status` 'pending' | 'running'
    - `simulationId` string, uuid
    - `createdAt` string, date-time
  - `message` string

## Other responses

- `400`: Invalid request data — structured field-level error
- `401`: Authentication required or invalid API key
- `402`: Payment required — the endpoint is metered and no API key was provided. The response body follows the [x402 v2 protocol](https://x402.org) and describes one or more USDC payment options that the caller can select before retrying the request. Base is always the first option and uses `X-PAYMENT`. When an `accepts` entry for Solana is present, it is an additional USDC-SPL option that uses `PAYMENT-SIGNATURE` and its `extra.feePayer` value. The server verifies either payment through the PayAI facilitator at `https://facilitator.payai.network`. The `PAYMENT-REQUIRED` response header carries this entire JSON body as a base64-encoded string for protocol-aware clients. Call `GET /api/billing/x402/config` to retrieve the current price table and wallet address and `paymentOptions` before constructing a payment.
- `404`: Simulation 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)