---
title: "Cancel deployment"
method: POST
path: "/v2/deployments.cancelDeployment"
tags: ["deployments"]
---

# Cancel deployment

`POST /v2/deployments.cancelDeployment`

## Request

- Base URL: `https://api.unkey.com`
- URL: `https://api.unkey.com/v2/deployments.cancelDeployment`
- Auth: HTTP bearer

Cancel a deployment that has not finished yet: queued, waiting for
approval, building, or deploying. Cancelling aborts its run and marks it
`cancelled`.

Only in-progress deployments can be cancelled. To take a `ready` preview
deployment offline, use `stopDeployment` instead.

Cancellation is asynchronous: this endpoint only enqueues it and returns
immediately. Poll `getDeployment` until the status reaches `cancelled`.

**Required Permissions**

Your root key must have the following permission:
- `unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>/environments/<environment_id>/deployments/<deployment_id>#write`

## Request body

- V2DeploymentsCancelDeploymentRequestBody
  - `deploymentId` string, required: Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.

## Response `202`

Cancellation accepted and enqueued. The deployment moves to
`cancelled` asynchronously; poll `getDeployment` to observe it.

- V2DeploymentsCancelDeploymentResponseBody: Cancel a deployment that is still in progress.
  - `meta` Meta, required: Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The `requestId` is particularly important when troubleshooting issues with the Unkey support team.
    - `requestId` string, required: A unique id for this request. Always include this ID when contacting support about a specific API request. This identifier allows Unkey's support team to trace the exact request through logs and diagnostic systems to provide faster assistance.
  - `data` EmptyResponse, required: Empty response object by design. A successful response indicates this operation was successfully executed.

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden - Your root key can read the deployment but lacks the required permission.
- `404`: Not Found - The deployment does not exist in your workspace, or your root key cannot read it. Both cases return the same response, so deployment existence is never revealed. A root key that can read the deployment but lacks the required permission receives 403 instead.
- `412`: Precondition failed - The deployment already finished, so there is nothing to cancel.
- `429`: Too Many Requests
- `500`: Internal server error

## Changes

- **2026-10-27** `6ed4b9847395`: 1 info
  - added the non-success response with the status `403`
- **2026-10-19** `06ba29618fe2`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/unkeyed/apis/unkey-api/changes/v2/deployments.cancelDeployment/post.md)

---

[API](https://skmtc.dev/unkeyed/apis/unkey-api.md) - [All operations](https://skmtc.dev/unkeyed/apis/unkey-api/llms.txt) - [OpenAPI document](https://skmtc.dev/unkeyed/apis/unkey-api/revisions/6fbaa27f19e0?raw)