---
title: "Start a rolling ECS Fargate deployment"
method: POST
path: "/simulations/{simulationId}/deploy"
tags: ["Simulations"]
---

# Start a rolling ECS Fargate deployment

`POST /simulations/{simulationId}/deploy`

## Request

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

Starts a rolling replacement of all running tasks in an `ecsFargate`
resource. Tasks are replaced in batches of `maxSurge`: each new batch
warms through `taskStartupSeconds` (the resource's configured startup
delay) before the corresponding old tasks begin draining through
`taskScaleDownSeconds`. During the drain window the ready new tasks
serve new connections while the old tasks finish existing ones, so
effective serving capacity is preserved throughout the deploy.

Progress is visible in subsequent `GET /simulations/{simulationId}`
responses under each resource's `metadata.fargateDeployReplacingCount`
and in `normalizedConfig.requestServing[].rollingDeploy` (present only
while a deploy is in flight). A `"success"` event is emitted when the
final batch completes.

Only `ecsFargate` resources support this action. Provide `resourceId`
or `resourceName` to target a specific resource; omit both to
auto-detect the first ecsFargate resource in the simulation.

Requires `write` scope and ownership.

## Path parameters

- `simulationId` string, required

## Request body

- object: Target a specific ecsFargate resource by `resourceId` or `resourceName`. Omit both to auto-detect the first ecsFargate resource. `maxSurge` controls how many new tasks are launched per batch before the corresponding old tasks begin draining (default 1).
  - `resourceId` string: ID of the ecsFargate resource to deploy. Takes precedence over resourceName.
  - `resourceName` string: Human-readable name of the ecsFargate resource to deploy.
  - `maxSurge` integer: Number of new tasks to launch per batch before the corresponding old tasks drain (default 1). Larger values speed up the deploy at the cost of temporarily running more tasks.

## Response `200`

Rolling deployment initiated

- object
  - `simulation` object: Updated simulation state (resources with deploy metadata set)
  - `event` object: Deployment-started event emitted to the simulation event log
  - `deployedResourceId` string: ID of the ecsFargate resource being deployed
  - `deployedResourceName` string: Name of the ecsFargate resource being deployed

## Other responses

- `400`: No ecsFargate resource found, or resource already deploying
- `402`: Payment required (x402)
- `403`: Access denied (not the owner)
- `404`: Simulation or 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)