v13

OpenAPI 3.0.32026-07-31359869.4 MB

deployments

Cancel a deployment

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

Path parameters

idstring required

The unique identifier of the deployment.

Example:dpl_5WJWYSyB7BpgTj3EuwF37WMRBXBtPQ2iTMJHJBJyRfd

The unique identifier of the deployment.

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.

alwaysRefuseToBuildfalse | true

buildArtifactUrlsstring[]

envstring[] required

inspectorUrlstring nullable required

isInConcurrentBuildsQueuefalse | true required

isInSystemBuildsQueuefalse | true required

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

bootedAtnumber required

buildingAtnumber required

buildContainerFinishedAtnumber

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

buildSkippedfalse | true required

initReadyAtnumber

isFirstBranchDeploymentfalse | true

publicfalse | true required

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

readynumber

userAliasesstring[]

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

previewCommentsEnabledfalse | true

Whether or not preview comments are enabled for the deployment

ttyBuildLogsfalse | true

oomReport'out-of-memory'

readyStateReasonstring

idstring required

A string holding the unique ID of the deployment

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.

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

errorCodestring

errorMessagestring nullable

createdAtnumber required

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

namestring required

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

type'LAMBDAS' required

aliasFinalstring nullable

autoAssignCustomDomainsfalse | true

applies to custom domains only, defaults to true

automaticAliasesstring[]

buildErrorAtnumber

checksState'completed' | 'registered' | 'running'

checksConclusion'canceled' | 'failed' | 'skipped' | 'succeeded'

deletedAtnumber nullable

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

defaultRoutestring

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

canceledAtnumber

errorLinkstring

errorStepstring

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

metaobject required

originCacheRegionstring

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

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

prebuiltfalse | true

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

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

undeletedAtnumber

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

urlstring required

A string with the unique URL of 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.

projectIdstring required

plan'enterprise' | 'hobby' | 'pro' required

connectBuildsEnabledfalse | true

connectConfigurationIdstring

createdInstring required

functionsobject nullable

monorepoManagerstring nullable

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)

Example response

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