deployments

Cancel a deployment

Changed on

Cancels a deployment that is currently in progress, stopping the build before it completes. Use this to recover quickly from accidental deploys, wrong-branch pushes, or builds with known errors — without waiting for them to finish. Returns 400 if the deployment is no longer cancelable (already READY, ERROR, or CANCELED). Returns the updated deployment object with readyState: 'CANCELED' on success.

patch/v12/deployments/{id}/cancel

Request

  • Base URL: https://api.vercel.com
  • URL: https://api.vercel.com/v12/deployments/{id}/cancel
  • Auth: HTTP bearer

Path parameters

idstring required

The unique identifier of the deployment.

Example:dpl_5WJWYSyB7BpgTj3EuwF37WMRBXBtPQ2iTMJHJBJyRfd

Query parameters

teamIdstring
Example:team_1a2b3c4d5e6f7g8h9i0j1k2l

The Team identifier to perform the request on behalf of.

slugstring
Example:my-team-url-slug

The Team slug to perform the request on behalf of.

Response

Returns the updated deployment object with readyState set to CANCELED. The build has been stopped and this action is irreversible.

aliasstring[]

A list of all the aliases (default aliases, staging aliases and production aliases) that were assigned upon deployment creation

aliasAssignedfalse | true required

A boolean that will be true when the aliases from the alias property were assigned successfully

aliasFinalstring nullable
alwaysRefuseToBuildfalse | true
autoAssignCustomDomainsfalse | true

applies to custom domains only, defaults to true

automaticAliasesstring[]
bootedAtnumber required
buildArtifactUrlsstring[]
buildContainerFinishedAtnumber

Since April 2025 it necessary for On-Demand Concurrency Minutes calculation

buildErrorAtnumber
buildingAtnumber required
buildSkippedfalse | true required
canceledAtnumber
checksConclusion'canceled' | 'failed' | 'skipped' | 'succeeded'
checksState'completed' | 'registered' | 'running'
connectBuildsEnabledfalse | true
connectConfigurationIdstring
createdAtnumber required

A number containing the date when the deployment was created in milliseconds

createdInstring required
defaultRoutestring

Computed field that is only available for deployments with a microfrontend configuration.

deletedAtnumber nullable

A number containing the date when the deployment was deleted at milliseconds

envstring[] required
errorCodestring
errorLinkstring
errorMessagestring nullable
errorStepstring
functionsobject nullable
idstring required

A string holding the unique ID of the deployment

initReadyAtnumber
inspectorUrlstring nullable required
isFirstBranchDeploymentfalse | true
isInConcurrentBuildsQueuefalse | true required
isInstantStaticfalse | true

Whether this deployment completed through the instant static fast path.

isInSystemBuildsQueuefalse | true required
metaobject required
monorepoManagerstring nullable
namestring required

The name of the project associated with the deployment at the time that the deployment was created

nodeVersion'10.x' | '12.x' | '14.x' | '16.x' | '18.x' | '20.x' | '22.x' | '24.x' | '26.x' | '8.10.x'

If set it overrides the projectSettings.nodeVersion for this deployment.

oomReport'out-of-memory'
originCacheRegionstring
ownerIdstring required
passiveConnectConfigurationIdstring

Since November 2023 this field defines a Secure Compute network that will only be used to deploy passive lambdas to (as in passiveRegions)

passiveRegionsstring[]

Since November 2023 this field defines a set of regions that we will deploy the lambda to passively Lambdas will be deployed to these regions but only invoked if all of the primary regions are marked as out of service

plan'enterprise' | 'hobby' | 'pro' required
prebuiltfalse | true
previewCommentsEnabledfalse | true

Whether or not preview comments are enabled for the deployment

projectIdstring required
publicfalse | true required

A boolean representing if the deployment is public or not. By default this is false

readynumber
readyState'BLOCKED' | 'BUILDING' | 'CANCELED' | 'ERROR' | 'INITIALIZING' | 'QUEUED' | 'READY' required

The state of the deployment depending on the process of deploying, or if it is ready or in an error state

readyStateReasonstring
readySubstate'PROMOTED' | 'ROLLING' | 'STAGED'

Substate of deployment when readyState is 'READY' Tracks whether or not deployment has seen production traffic: - STAGED: never seen production traffic - ROLLING: in the process of having production traffic gradually transitioned. - PROMOTED: has seen production traffic

regionsstring[] required

The regions the deployment exists in

softDeletedByRetentionfalse | true

flag to indicate if the deployment was deleted by retention policy

source'api-trigger-git-deploy' | 'cli' | 'clone/repo' | 'drop' | 'git' | 'git-deploy-hook' | 'import' | 'import/repo' | 'redeploy' | 'v0-web'

Where was the deployment created from. Best-effort guess for metrics only — not authoritative; do not gate behavior on it.

status'BLOCKED' | 'BUILDING' | 'CANCELED' | 'ERROR' | 'INITIALIZING' | 'QUEUED' | 'READY' required
target'production' | 'staging' | 'null' nullable

If defined, either staging if a staging alias in the format <project>.<team>.now.sh was assigned upon creation, or production if the aliases from alias were assigned. null value indicates the "preview" deployment.

ttyBuildLogsfalse | true
type'LAMBDAS' required
undeletedAtnumber

A number containing the date when the deployment was undeleted at milliseconds

urlstring required

A string with the unique URL of the deployment

userAliasesstring[]

An array of domains that were provided by the user when creating the Deployment.

userConfiguredDeploymentIdstring

Since January 2025 User-configured deployment ID for skew protection with pre-built deployments. This is set when users configure a custom deploymentId in their next.config.js file. This allows Next.js to use skew protection even when deployments are pre-built outside of Vercel's build system.

version2 required

The platform version that was used to create the deployment.

Example response

{
  "alias": [],
  "aliasAssigned": true,
  "createdAt": 1540257589405,
  "creator": {
    "uid": "96SnxkFiMyVKsK3pnoHfx3Hz",
    "username": "john-doe"
  },
  "deletedAt": 1540257589405,
  "id": "dpl_89qyp1cskzkLrVicDaZoDbjyHuDJ",
  "name": "my-project",
  "readyState": "READY",
  "regions": [
    "sfo1"
  ],
  "source": "cli",
  "undeletedAt": 1540257589405,
  "url": "my-instant-deployment-3ij3cxz9qr.now.sh",
  "userAliases": [
    "sub1.example.com",
    "sub2.example.com"
  ],
  "userConfiguredDeploymentId": "abc123",
  "version": 2
}

Changes

  • 2060b55dc517Revision changes
    • warning

      added the new project enum value to the / response property for the response status

  • 74d3a3591515Revision changes
    • breaking

      added subschema #1 subschema #2 to the / response property oneOf list for the response status

    • info

      removed subschema #1 subschema #2 from the / response property oneOf list for the response status