Skip to content
Docs

Cancel a deployment

PATCHhttps://api.vercel.com/v12/deployments/{id}/cancel
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.
Request
import { Vercel } from "@vercel/sdk";


const vercel = new Vercel({
  bearerToken: "<YOUR_BEARER_TOKEN_HERE>",
});


async function run() {
  const result = await vercel.deployments.cancelDeployment({
    id: "dpl_5WJWYSyB7BpgTj3EuwF37WMRBXBtPQ2iTMJHJBJyRfd",
    teamId: "team_1a2b3c4d5e6f7g8h9i0j1k2l",
    slug: "my-team-url-slug",
  });


  console.log(result);
}


run();
Response
{
  "alias": [],
  "aliasAssigned": "true",
  "aliasAssignedAt": "123",
  "aliasError": {
    "code": "string",
    "message": "string"
  },
  "aliasFinal": "string",
  "aliasWarning": {
    "action": "string",
    "code": "string",
    "link": "string",
    "message": "string"
  },
  "alwaysRefuseToBuild": "false",
  "atproto": {
    "enabled": "false"
  },
  "attribution": {
    "commitMeta": {
      "email": "user@example.com",
      "isVerified": "false",
      "name": "Example Name"
    },
    "gitUser": {
      "id": "icfg_1234567890",
      "login": "string",
      "provider": "example_id",
      "type": "string"
    },
    "vercelUser": {
      "id": "icfg_1234567890",
      "teamRoles": [],
      "username": "string"
    }
  },
  "autoAssignCustomDomains": "false",
  "automaticAliases": [],
  "bootedAt": "123",
  "build": {
    "env": []
  },
  "buildArtifactUrls": [],
  "buildContainerFinishedAt": "123",
  "buildErrorAt": "123",
  "buildingAt": "123",
  "builds": [
    {
      "config": "value",
      "src": "string",
      "use": "string"
    }
  ],
  "buildSkipped": "false",
  "canceledAt": "123",
  "checks": {
    "deployment-alias": {
      "completedAt": "123",
      "startedAt": "123",
      "state": "failed"
    }
  },
  "checksConclusion": "canceled",
  "checksState": "completed",
  "config": {
    "functionMemoryType": "performance",
    "functionTimeout": "123",
    "functionType": "fluid",
    "isUsingActiveCPU": "false",
    "resourceConfig": {
      "buildQueue": {
        "configuration": "SKIP_NAMESPACE_QUEUE"
      },
      "elasticConcurrency": "PROJECT_SETTING",
      "buildMachine": {
        "purchaseType": "basic"
      }
    },
    "secureComputeFallbackRegion": "string",
    "secureComputePrimaryRegion": "string",
    "version": "123"
  },
  "connectBuildsEnabled": "false",
  "connectConfigurationId": "example_id",
  "createdAt": "1540257589405",
  "createdIn": "string",
  "creator": {
    "avatar": "string",
    "type": "app",
    "uid": "96SnxkFiMyVKsK3pnoHfx3Hz",
    "username": "john-doe"
  },
  "crons": [
    {
      "path": "string",
      "schedule": "string"
    }
  ],
  "customEnvironment": {
    "branchMatcher": {
      "pattern": "string",
      "type": "endsWith"
    },
    "createdAt": "123",
    "currentDeploymentAliases": [],
    "description": "string",
    "domains": [
      {
        "apexName": "Example Name",
        "createdAt": "123",
        "customEnvironmentId": "example_id",
        "gitBranch": "string",
        "name": "Example Name",
        "projectId": "example_id",
        "redirect": "string",
        "redirectStatusCode": "301",
        "updatedAt": "123",
        "verification": [
          {
            "domain": "string",
            "reason": "Customer requested refund",
            "type": "string",
            "value": "string"
          }
        ],
        "verified": "false"
      }
    ],
    "id": "icfg_1234567890",
    "slug": "string",
    "type": "development",
    "updatedAt": "123"
  },
  "defaultRoute": "string",
  "deletedAt": "1540257589405",
  "duration": {
    "endTime": "123",
    "endTimeCapped": "123",
    "startTime": "123",
    "timeForBilling": "123",
    "timeToContainerExit": "123",
    "timeToContainerExitCapped": "123",
    "timeToReady": "123"
  },
  "env": [],
  "errorCode": "string",
  "errorLink": "string",
  "errorMessage": "string",
  "errorStep": "string",
  "flags": {
    "definitions": "value"
  },
  "functions": "value",
  "gitRepo": {
    "defaultBranch": "string",
    "name": "Example Name",
    "namespace": "Example Name",
    "ownerType": "team",
    "path": "string",
    "private": "false",
    "projectId": "123",
    "type": "gitlab",
    "url": "https://example.com"
  },
  "gitSource": {
    "prId": "123",
    "ref": "string",
    "repoId": "example_id",
    "sha": "string",
    "type": "github"
  },
  "id": "dpl_89qyp1cskzkLrVicDaZoDbjyHuDJ",
  "images": {
    "contentDispositionType": "attachment",
    "contentSecurityPolicy": "https://example.com",
    "dangerouslyAllowSVG": "false",
    "domains": [],
    "formats": [],
    "localPatterns": [
      {
        "pathname": "Example Name",
        "search": "string"
      }
    ],
    "minimumCacheTTL": "123",
    "qualities": [],
    "remotePatterns": [
      {
        "hostname": "Example Name",
        "pathname": "Example Name",
        "port": "string",
        "protocol": "http",
        "search": "string"
      }
    ],
    "sizes": []
  },
  "initReadyAt": "123",
  "inspectorUrl": "https://example.com",
  "integrations": {
    "claimedAt": "123",
    "completedAt": "123",
    "skippedAt": "123",
    "skippedBy": "string",
    "startedAt": "123",
    "status": "error"
  },
  "isFirstBranchDeployment": "false",
  "isInConcurrentBuildsQueue": "false",
  "isInstantStatic": "false",
  "isInSystemBuildsQueue": "false",
  "lambdas": [
    {
      "createdAt": "123",
      "entrypoint": "string",
      "id": "icfg_1234567890",
      "readyState": "BUILDING",
      "readyStateAt": "123",
      "output": [
        {
          "functionName": "Example Name",
          "path": "string"
        }
      ]
    }
  ],
  "manualProvisioning": {
    "completedAt": "123",
    "state": "COMPLETE"
  },
  "meta": "value",
  "microfrontends": {
    "defaultAppProjectName": "Example Name",
    "defaultRoute": "string",
    "groupIds": [],
    "isDefaultApp": "false"
  },
  "monorepoManager": "string",
  "name": "my-project",
  "nodeVersion": "10.x",
  "oidcTokenClaims": {
    "aud": "string",
    "custom_environment_id": "example_id",
    "deployment_id": "example_id",
    "environment": "string",
    "iss": "string",
    "mfe_group_ids": [],
    "owner": "string",
    "owner_id": "example_id",
    "plan": "string",
    "project": "string",
    "project_id": "example_id",
    "scope": "string",
    "sub": "string"
  },
  "oomReport": "out-of-memory",
  "originCacheRegion": "string",
  "ownerId": "example_id",
  "passiveConnectConfigurationId": "example_id",
  "passiveRegions": [],
  "plan": "enterprise",
  "platform": {
    "creator": {
      "avatar": "string",
      "name": "Example Name"
    },
    "meta": "value",
    "origin": {
      "type": "id",
      "value": "string"
    },
    "source": {
      "name": "Example Name"
    }
  },
  "prebuilt": "false",
  "previewCommentsEnabled": "false",
  "project": {
    "framework": "string",
    "id": "icfg_1234567890",
    "name": "Example Name"
  },
  "projectId": "example_id",
  "projectSettings": {
    "buildCommand": "string",
    "commandForIgnoringBuildStep": "string",
    "devCommand": "string",
    "framework": "actix-web",
    "installCommand": "string",
    "nodeVersion": "10.x",
    "outputDirectory": "string",
    "speedInsights": {
      "canceledAt": "123",
      "dataReceivedAt": "123",
      "disabledAt": "123",
      "enabledAt": "123",
      "hasData": "false",
      "id": "icfg_1234567890",
      "paidAt": "123"
    },
    "webAnalytics": {
      "canceledAt": "123",
      "disabledAt": "123",
      "enabledAt": "123",
      "hasData": "true",
      "id": "icfg_1234567890"
    }
  },
  "public": "false",
  "ready": "123",
  "readyState": "READY",
  "readyStateReason": "Customer requested refund",
  "readySubstate": "PROMOTED",
  "regions": [],
  "resourceConfig": {
    "buildMachine": {
      "cores": "123",
      "defaultPurchaseType": "basic",
      "machineSelectionType": "elastic",
      "memory": "123",
      "purchaseType": "basic",
      "selectionSource": "deployment-override"
    }
  },
  "routes": [
    {
      "caseSensitive": "false",
      "check": "false",
      "continue": "false",
      "dest": "string",
      "destination": "string",
      "env": [],
      "has": [
        {
          "type": "host",
          "value": "string"
        }
      ],
      "headers": "value",
      "important": "false",
      "locale": {
        "cookie": "string",
        "redirect": "value"
      },
      "methods": [],
      "middleware": "123",
      "middlewarePath": "example_id",
      "middlewareRawSrc": [],
      "missing": [
        {
          "type": "host",
          "value": "string"
        }
      ],
      "mitigate": {
        "action": "challenge"
      },
      "override": "false",
      "respectOriginCacheControl": "false",
      "source": "string",
      "src": "string",
      "status": "123",
      "statusCode": "123",
      "transforms": [
        {
          "args": "string",
          "env": [],
          "op": "append",
          "target": {
            "key": "string"
          },
          "type": "request.headers"
        }
      ]
    }
  ],
  "seatBlock": {
    "blockCode": "COMMIT_AUTHOR_REQUIRED",
    "gitProvider": "bitbucket",
    "gitUserId": "example_id",
    "isVerified": "false",
    "userId": "example_id"
  },
  "services": [
    {
      "buildCommand": "string",
      "builder": {
        "config": {
          "buildCommand": "string",
          "buildpack": "string",
          "bundle": "false",
          "bunVersion": "string",
          "debug": "false",
          "devCommand": "string",
          "excludeFiles": "string",
          "framework": "string",
          "functions": "value",
          "helpers": "false",
          "import": "value",
          "includeFiles": "string",
          "installCommand": "string",
          "ldsflags": "string",
          "maxLambdaSize": "string",
          "middleware": "false",
          "middlewareMatcher": "example_id",
          "middlewareRuntime": "nodejs",
          "nodeVersion": "string",
          "outputDirectory": "string",
          "projectSettings": {
            "autoExposeSystemEnvs": "false",
            "buildCommand": "string",
            "commandForIgnoringBuildStep": "string",
            "createdAt": "123",
            "devCommand": "string",
            "directoryListing": "false",
            "framework": "string",
            "gitForkProtection": "false",
            "installCommand": "string",
            "monorepoManager": "string",
            "nodeVersion": "string",
            "outputDirectory": "string",
            "rootDirectory": "string",
            "sourceFilesOutsideRootDirectory": "false"
          },
          "rust": "string",
          "scheduleFunction": {
            "entrypoints": [
              {
                "entrypoint": "string",
                "scheduleNames": [],
                "sourceFile": "string"
              }
            ],
            "outputPath": "string"
          },
          "serviceName": "Example Name",
          "zeroConfig": "false"
        },
        "src": "string",
        "use": "string"
      },
      "entrypoint": "string",
      "env": "value",
      "framework": "string",
      "group": "string",
      "handlerFunction": "string",
      "installCommand": "string",
      "name": "Example Name",
      "preDeployCommand": "string",
      "routePrefix": "string",
      "routePrefixSource": "configured",
      "runtime": "string",
      "schedule": "string",
      "schema": "experimentalServices",
      "subdomain": "string",
      "topics": [],
      "trigger": "queue",
      "type": "cron",
      "workspace": "string"
    }
  ],
  "softDeletedByRetention": "true",
  "source": "cli",
  "status": "BLOCKED",
  "target": "null",
  "team": {
    "avatar": "string",
    "id": "icfg_1234567890",
    "name": "Example Name",
    "slug": "string"
  },
  "ttyBuildLogs": "false",
  "type": "LAMBDAS",
  "undeletedAt": "1540257589405",
  "url": "my-instant-deployment-3ij3cxz9qr.now.sh",
  "userAliases": [],
  "userConfiguredDeploymentId": "abc123",
  "version": "2"
}

Authentication

AuthorizationbearerToken

Default authentication mechanism

Path parameters

idstringRequired
The unique identifier of the deployment.

Query parameters

teamIdstringOptional
The Team identifier to perform the request on behalf of.
slugstringOptional
The Team slug to perform the request on behalf of.

Response

200Returns the updated deployment object with `readyState` set to `CANCELED`. The build has been stopped and this action is irreversible.
aliasarrayOptional
A list of all the aliases (default aliases, staging aliases and production aliases) that were assigned upon deployment creation
aliasAssignedbooleanRequired
A boolean that will be true when the aliases from the alias property were assigned successfully
aliasAssignedAtobjectOptional2 variants
aliasErrorobjectOptional
An object that will contain a code and a message when the aliasing fails, otherwise the value will be null
aliasFinalstringOptional
aliasWarningobjectOptional
alwaysRefuseToBuildbooleanOptional
atprotoobjectOptional2 variants
attributionobjectOptional
Attribution metadata for the deployment, linking commit author to git and Vercel users. Only populated when the enable-deployment-attribution flag is enabled.
autoAssignCustomDomainsbooleanOptional
applies to custom domains only, defaults to true
automaticAliasesarrayOptional
bootedAtnumberRequired
buildobjectRequired
buildArtifactUrlsarrayOptional
buildContainerFinishedAtnumberOptional
Since April 2025 it necessary for On-Demand Concurrency Minutes calculation
buildErrorAtnumberOptional
buildingAtnumberRequired
buildsarrayOptional
buildSkippedbooleanRequired
canceledAtnumberOptional
checksobjectOptional
checksConclusionstringOptional
checksStatestringOptional
configobjectOptional
Since February 2025 the configuration must include snapshot data at the time of deployment creation to capture properties for the /deployments/:id/config endpoint utilized for displaying Deployment Configuration on the frontend This is optional because older deployments may not have this data captured
connectBuildsEnabledbooleanOptional
connectConfigurationIdstringOptional
createdAtnumberRequired
A number containing the date when the deployment was created in milliseconds
createdInstringRequired
creatorobjectRequired
Information about the deployment creator
cronsarrayOptional
customEnvironmentobjectOptional2 variants
defaultRoutestringOptional
Computed field that is only available for deployments with a microfrontend configuration.
deletedAtnumberOptional
A number containing the date when the deployment was deleted at milliseconds
durationobjectRequired
envarrayRequired
errorCodestringOptional
errorMessagestringOptional
errorStepstringOptional
flagsobjectOptional
Flags defined in the Build Output API, used by this deployment. Primarily used by the Toolbar to know about the used flags.
functionsobjectOptional
gitRepoobjectOptional5 variants
gitSourceobjectOptional19 variants
idstringRequired
A string holding the unique ID of the deployment
imagesobjectOptional
initReadyAtnumberOptional
inspectorUrlstringRequired
integrationsobjectOptional
isFirstBranchDeploymentbooleanOptional
isInConcurrentBuildsQueuebooleanRequired
isInstantStaticbooleanOptional
Whether this deployment completed through the instant static fast path.
isInSystemBuildsQueuebooleanRequired
lambdasarrayOptional
manualProvisioningobjectOptional
Present when deployment was created with manual provisioning enabled, either explicitly or via the experimental BYOC git flow. The deployment stays in INITIALIZING until /continue is called.
metaobjectRequired
microfrontendsobjectOptional2 variants
monorepoManagerstringOptional
namestringRequired
The name of the project associated with the deployment at the time that the deployment was created
nodeVersionstringOptional
If set it overrides the projectSettings.nodeVersion for this deployment.
oidcTokenClaimsobjectOptional
oomReportstringOptional
originCacheRegionstringOptional
ownerIdstringRequired
passiveConnectConfigurationIdstringOptional
Since November 2023 this field defines a Secure Compute network that will only be used to deploy passive lambdas to (as in passiveRegions)
passiveRegionsarrayOptional
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
planstringRequired
platformobjectOptional
Metadata about the source platform that triggered the deployment. Allows us to map a deployment back to a platform (e.g. the chat that created it)
prebuiltbooleanOptional
previewCommentsEnabledbooleanOptional
Whether or not preview comments are enabled for the deployment
projectobjectOptional
The public project information associated with the deployment.
projectIdstringRequired
projectSettingsobjectRequired
publicbooleanRequired
A boolean representing if the deployment is public or not. By default this is false
readynumberOptional
readyStatestringRequired
The state of the deployment depending on the process of deploying, or if it is ready or in an error state
readyStateReasonstringOptional
readySubstatestringOptional
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
regionsarrayRequired
The regions the deployment exists in
resourceConfigobjectOptional
routesarrayRequired
seatBlockobjectOptional
NSNB Blocked metadata
servicesarrayOptional
Services detected during build from vercel.json experimentalServices or auto-detected from project structure. Used to inject service URLs as environment variables at runtime.
softDeletedByRetentionbooleanOptional
flag to indicate if the deployment was deleted by retention policy
sourcestringOptional
Where was the deployment created from. Best-effort guess for metrics only — not authoritative; do not gate behavior on it.
statusstringRequired
targetstringOptional
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.
teamobjectOptional
The team that owns the deployment if any
ttyBuildLogsbooleanOptional
typestringRequired
undeletedAtnumberOptional
A number containing the date when the deployment was undeleted at milliseconds
urlstringRequired
A string with the unique URL of the deployment
userAliasesarrayOptional
An array of domains that were provided by the user when creating the Deployment.
userConfiguredDeploymentIdstringOptional
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.
versionnumberRequired
The platform version that was used to create the deployment.

Errors

400One of the provided values in the request query is invalid.
401The request is not authorized.
403You do not have permission to access this resource.
404Error
410Error