---
title: "Create a scheduled failure injection"
method: POST
path: "/simulations/{simulationId}/failures"
tags: ["Simulations"]
---

# Create a scheduled failure injection

`POST /simulations/{simulationId}/failures`

## Request

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

Creates a new failure injection that will be applied to the simulation
during the specified time window. The injection is applied immediately
to the resource state (the affected resource's status changes) and an
event is recorded.

**Failure types:**
- `instance_kill` — PERMANENTLY removes a compute instance from the simulation (deleting the failure does not restore it)
- `instance_down` — reversible single-node outage: marks a compute instance critical without removing it; deactivating (`isActive: false`) or deleting the failure restores the node
- `az_outage` — simulates an availability zone outage
- `database_overload` — modeled load-sensitive database CPU, bounded Aurora ACU, latency and failed requests; thresholds are assumptions, not AWS guarantees. Set top-level `severity` (minor/moderate/severe, default moderate) or `intensity` (0–1, mapped into those three bands), not both; the response echoes effective severity. Do not place controls in `parameters`.
- `network_latency` — adds latency to all network resources

**Precondition — already-critical targets:** an `instance_down` or
`instance_kill` element whose `targetResourceId` refers to a resource
that is already in `critical` status is rejected with `400` and error
code `RESOURCE_NOT_FAILEABLE` — the same code and reason semantics as
`POST /simulations/{simulationId}/inject-failure`. Consistent with the
batch contract, one rejected element aborts the whole request
(all-or-nothing) and no failure injection is created or applied. In an
array (batch) body the error pointer is index-prefixed
(`/2/targetResourceId`) and the message is prefixed with `failures[2]: `.

Requires `write` scope and ownership.

## Path parameters

- `simulationId` string, required

## Request body

- object
  - `name` string, required: Human-readable label for this failure
  - `type` 'instance_kill' | 'instance_down' | 'az_outage' | 'region_outage' | 'permanent_data_loss' | 'database_overload' | 'network_latency' | 'spot_interruption', required: Type of failure to inject
  - `startTime` integer, required: Simulation time step at which to begin the failure
  - `endTime` integer, nullable: Simulation time step at which the failure resolves (null = permanent)
  - `targetResourceId` string, nullable: ID of the specific resource to target (optional)
  - `targetZone` string, nullable: Availability zone to target for az_outage (optional)
  - `targetRegion` string: Canonical region key. region_outage requires this and targetProvider. Permanent data loss requires a resource ID or provider-qualified region/zone scope; expiration never restores destroyed data.
  - `targetProvider` 'aws' | 'gcp' | 'azure' | 'oci' | 'digitalocean'
  - `severity` 'minor' | 'moderate' | 'severe': Top-level database_overload severity; mutually exclusive with intensity.
  - `intensity` number: Alternative database_overload control, mapped to minor below 0.34, moderate below 0.67, severe otherwise; mutually exclusive with severity.
  - `isActive` boolean

## Response `201`

Failure injection created

- object
  - `id` string
  - `simulationId` string
  - `name` string
  - `type` string
  - `severity` 'minor' | 'moderate' | 'severe': Effective severity (including when intensity was supplied).
  - `isActive` boolean
  - `startTime` integer
  - `endTime` integer, nullable
  - `parameters` object
    - `_databaseFailoverSucceeded` boolean
    - `_databaseFailoverReason` 'primary_crash' | 'database_overload'

## Other responses

- `400`: Validation failed, or the target resource is not in a faileable state. For `instance_down` / `instance_kill` with a `targetResourceId` that resolves to an already-critical resource, the error code is `RESOURCE_NOT_FAILEABLE` — identical to the precondition enforced by `POST /inject-failure`. Nothing is persisted or applied (all-or-nothing for batch bodies).
- `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.
- `403`: Access denied
- `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)