--- title: cancel-a-deployment product: vercel url: /docs/rest-api/deployments/cancel-a-deployment type: reference prerequisites: [] related: - /docs/rest-api summary: Learn about cancel-a-deployment on Vercel. install_vercel_plugin: npx plugins add vercel/vercel-plugin --- # Cancel a deployment ```http PATCH /v12/deployments/{id}/cancel ``` This endpoint allows you to cancel a deployment which is currently building, by supplying its `id` in the URL. ## Authentication **bearerToken**: HTTP bearer ## Path parameters | Name | Type | Required | Description | |---|---|---|---| | `id` | string | Yes | The unique identifier of the deployment. | ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `teamId` | string | No | The Team identifier to perform the request on behalf of. | | `slug` | string | No | The Team slug to perform the request on behalf of. | ## Responses ### 200: No description Content-Type: `application/json` ```json { "type": "object", "description": "The private deployment representation of a Deployment.", "required": [ "aliasAssigned", "bootedAt", "build", "buildSkipped", "buildingAt", "createdAt", "createdIn", "creator", "env", "id", "inspectorUrl", "isInConcurrentBuildsQueue", "isInSystemBuildsQueue", "meta", "name", "ownerId", "plan", "projectId", "projectSettings", "public", "readyState", "regions", "routes", "status", "type", "url", "version" ], "properties": { "aliasAssignedAt": { "nullable": true, "oneOf": [ { "type": "number" }, { "type": "boolean", "enum": [ false, true ] } ] }, "alwaysRefuseToBuild": { "type": "boolean", "enum": [ false, true ] }, "build": { "type": "object", "required": [ "env" ], "properties": { "env": { "type": "array", "items": { "type": "string" } } } }, "buildArtifactUrls": { "type": "array", "items": { "type": "string" } }, "builds": { "type": "array", "items": { "type": "object", "required": [ "use" ], "properties": { "use": { "type": "string" }, "src": { "type": "string" }, "config": { "type": "object", "additionalProperties": true } } } }, "env": { "type": "array", "items": { "type": "string" } }, "inspectorUrl": { "type": "string", "nullable": true }, "isInConcurrentBuildsQueue": { "type": "boolean", "enum": [ false, true ] }, "isInSystemBuildsQueue": { "type": "boolean", "enum": [ false, true ] }, "projectSettings": { "type": "object", "properties": { "nodeVersion": { "type": "string", "enum": [ "24.x", "22.x", "20.x", "18.x", "16.x", "14.x", "12.x", "10.x", "8.10.x" ] }, "buildCommand": { "type": "string", "nullable": true }, "devCommand": { "type": "string", "nullable": true }, "framework": { "type": "string", "enum": [ "blitzjs", "nextjs", "gatsby", "remix", "react-router", "astro", "hexo", "eleventy", "docusaurus-2", "docusaurus", "preact", "solidstart-1", "solidstart", "dojo", "ember", "vue", "scully", "ionic-angular", "angular", "polymer", "svelte", "sveltekit", "sveltekit-1", "ionic-react", "create-react-app", "gridsome", "umijs", "sapper", "saber", "stencil", "nuxtjs", "redwoodjs", "hugo", "jekyll", "brunch", "middleman", "zola", "hydrogen", "vite", "tanstack-start", "vitepress", "vuepress", "parcel", "fastapi", "flask", "fasthtml", "django", "sanity-v3", "sanity", "storybook", "nitro", "hono", "express", "h3", "koa", "nestjs", "elysia", "fastify", "xmcp", "python", "ruby", "rust", "node", "go", "services" ], "nullable": true }, "commandForIgnoringBuildStep": { "type": "string", "nullable": true }, "installCommand": { "type": "string", "nullable": true }, "outputDirectory": { "type": "string", "nullable": true }, "speedInsights": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" }, "enabledAt": { "type": "number" }, "disabledAt": { "type": "number" }, "canceledAt": { "type": "number" }, "hasData": { "type": "boolean", "enum": [ false, true ] }, "paidAt": { "type": "number" } } }, "webAnalytics": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" }, "disabledAt": { "type": "number" }, "canceledAt": { "type": "number" }, "enabledAt": { "type": "number" }, "hasData": { "type": "boolean", "enum": [ true ] } } } } }, "integrations": { "type": "object", "required": [ "startedAt", "status" ], "properties": { "status": { "type": "string", "enum": [ "skipped", "pending", "ready", "error", "timeout" ] }, "startedAt": { "type": "number" }, "claimedAt": { "type": "number" }, "completedAt": { "type": "number" }, "skippedAt": { "type": "number" }, "skippedBy": { "type": "string" } } }, "images": { "type": "object", "properties": { "sizes": { "type": "array", "items": { "type": "number" } }, "qualities": { "type": "array", "items": { "type": "number" } }, "domains": { "type": "array", "items": { "type": "string" } }, "remotePatterns": { "type": "array", "items": { "type": "object", "required": [ "hostname" ], "properties": { "protocol": { "type": "string", "description": "Must be `http` or `https`.", "enum": [ "http", "https" ] }, "hostname": { "type": "string", "description": "Can be literal or wildcard. Single `*` matches a single subdomain. Double `**` matches any number of subdomains." }, "port": { "type": "string", "description": "Can be literal port such as `8080` or empty string meaning no port." }, "pathname": { "type": "string", "description": "Can be literal or wildcard. Single `*` matches a single path segment. Double `**` matches any number of path segments." }, "search": { "type": "string", "description": "Can be literal query string such as `?v=1` or empty string meaning no query string." } } } }, "localPatterns": { "type": "array", "items": { "type": "object", "properties": { "pathname": { "type": "string", "description": "Can be literal or wildcard. Single `*` matches a single path segment. Double `**` matches any number of path segments." }, "search": { "type": "string", "description": "Can be literal query string such as `?v=1` or empty string meaning no query string." } } } }, "minimumCacheTTL": { "type": "number" }, "formats": { "type": "array", "items": { "type": "string", "enum": [ "image/avif", "image/webp" ] } }, "dangerouslyAllowSVG": { "type": "boolean", "enum": [ false, true ] }, "contentSecurityPolicy": { "type": "string" }, "contentDispositionType": { "type": "string", "enum": [ "inline", "attachment" ] } } }, "alias": { "type": "array", "description": "A list of all the aliases (default aliases, staging aliases and production aliases) that were assigned upon deployment creation", "items": { "type": "string" } }, "aliasAssigned": { "type": "boolean", "description": "A boolean that will be true when the aliases from the alias property were assigned successfully", "enum": [ false, true ] }, "bootedAt": { "type": "number" }, "buildingAt": { "type": "number" }, "buildContainerFinishedAt": { "type": "number", "description": "Since April 2025 it necessary for On-Demand Concurrency Minutes calculation" }, "buildSkipped": { "type": "boolean", "enum": [ false, true ] }, "creator": { "type": "object", "description": "Information about the deployment creator", "required": [ "uid" ], "properties": { "uid": { "type": "string", "description": "The ID of the user that created the deployment" }, "username": { "type": "string", "description": "The username of the user that created the deployment" }, "avatar": { "type": "string", "description": "The avatar of the user that created the deployment" } } }, "initReadyAt": { "type": "number" }, "isFirstBranchDeployment": { "type": "boolean", "enum": [ false, true ] }, "lambdas": { "type": "array", "items": { "type": "object", "description": "A partial representation of a Build used by the deployment endpoint.", "required": [ "id", "output" ], "properties": { "id": { "type": "string" }, "createdAt": { "type": "number" }, "readyState": { "type": "string", "enum": [ "BUILDING", "ERROR", "INITIALIZING", "READY" ] }, "entrypoint": { "type": "string", "nullable": true }, "readyStateAt": { "type": "number" }, "output": { "type": "array", "items": { "type": "object", "required": [ "functionName", "path" ], "properties": { "path": { "type": "string" }, "functionName": { "type": "string" } } } } } } }, "public": { "type": "boolean", "description": "A boolean representing if the deployment is public or not. By default this is `false`", "enum": [ false, true ] }, "ready": { "type": "number" }, "status": { "type": "string", "enum": [ "QUEUED", "BUILDING", "ERROR", "INITIALIZING", "READY", "CANCELED" ] }, "team": { "type": "object", "description": "The team that owns the deployment if any", "required": [ "id", "name", "slug" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "avatar": { "type": "string" } } }, "userAliases": { "type": "array", "description": "An array of domains that were provided by the user when creating the Deployment.", "items": { "type": "string" } }, "previewCommentsEnabled": { "type": "boolean", "description": "Whether or not preview comments are enabled for the deployment", "enum": [ false, true ] }, "ttyBuildLogs": { "type": "boolean", "enum": [ false, true ] }, "customEnvironment": { "oneOf": [ { "type": "object", "description": "If the deployment was created using a Custom Environment, then this property contains information regarding the environment used.", "required": [ "createdAt", "id", "slug", "type", "updatedAt" ], "properties": { "id": { "type": "string", "description": "Unique identifier for the custom environment (format: env_*)" }, "slug": { "type": "string", "description": "URL-friendly name of the environment" }, "type": { "type": "string", "description": "The type of environment (production, preview, or development)", "enum": [ "production", "preview", "development" ] }, "description": { "type": "string", "description": "Optional description of the environment's purpose" }, "branchMatcher": { "type": "object", "description": "Configuration for matching git branches to this environment", "required": [ "pattern", "type" ], "properties": { "type": { "type": "string", "description": "The type of matching to perform", "enum": [ "endsWith", "startsWith", "equals" ] }, "pattern": { "type": "string", "description": "The pattern to match against branch names" } } }, "domains": { "type": "array", "description": "List of domains associated with this environment", "items": { "type": "object", "description": "List of domains associated with this environment", "required": [ "apexName", "name", "projectId", "verified" ], "properties": { "name": { "type": "string" }, "apexName": { "type": "string" }, "projectId": { "type": "string" }, "redirect": { "type": "string", "nullable": true }, "redirectStatusCode": { "type": "number", "enum": [ 307, 301, 302, 308 ], "nullable": true }, "gitBranch": { "type": "string", "nullable": true }, "customEnvironmentId": { "type": "string", "nullable": true }, "updatedAt": { "type": "number" }, "createdAt": { "type": "number" }, "verified": { "type": "boolean", "description": "`true` if the domain is verified for use with the project. If `false` it will not be used as an alias on this project until the challenge in `verification` is completed.", "enum": [ false, true ] }, "verification": { "type": "array", "description": "A list of verification challenges, one of which must be completed to verify the domain for use on the project. After the challenge is complete `POST /projects/:idOrName/domains/:domain/verify` to verify the domain. Possible challenges: - If `verification.type = TXT` the `verification.domain` will be checked for a TXT record matching `verification.value`.", "items": { "type": "object", "description": "A list of verification challenges, one of which must be completed to verify the domain for use on the project. After the challenge is complete `POST /projects/:idOrName/domains/:domain/verify` to verify the domain. Possible challenges: - If `verification.type = TXT` the `verification.domain` will be checked for a TXT record matching `verification.value`.", "required": [ "domain", "reason", "type", "value" ], "properties": { "type": { "type": "string" }, "domain": { "type": "string" }, "value": { "type": "string" }, "reason": { "type": "string" } } } } } } }, "currentDeploymentAliases": { "type": "array", "description": "List of aliases for the current deployment", "items": { "type": "string" } }, "createdAt": { "type": "number", "description": "Timestamp when the environment was created" }, "updatedAt": { "type": "number", "description": "Timestamp when the environment was last updated" } } }, { "type": "object", "description": "If the deployment was created using a Custom Environment, then this property contains information regarding the environment used.", "required": [ "id" ], "properties": { "id": { "type": "string" } } } ] }, "oomReport": { "type": "string", "enum": [ "out-of-memory" ] }, "readyStateReason": { "type": "string" }, "aliasWarning": { "type": "object", "nullable": true, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "link": { "type": "string" }, "action": { "type": "string" } } }, "id": { "type": "string", "description": "A string holding the unique ID of the deployment" }, "createdAt": { "type": "number", "description": "A number containing the date when the deployment was created in milliseconds" }, "readyState": { "type": "string", "description": "The state of the deployment depending on the process of deploying, or if it is ready or in an error state", "enum": [ "QUEUED", "BUILDING", "ERROR", "INITIALIZING", "READY", "CANCELED" ] }, "name": { "type": "string", "description": "The name of the project associated with the deployment at the time that the deployment was created" }, "type": { "type": "string", "enum": [ "LAMBDAS" ] }, "aliasError": { "type": "object", "description": "An object that will contain a `code` and a `message` when the aliasing fails, otherwise the value will be `null`", "nullable": true, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "aliasFinal": { "type": "string", "nullable": true }, "autoAssignCustomDomains": { "type": "boolean", "description": "applies to custom domains only, defaults to `true`", "enum": [ false, true ] }, "automaticAliases": { "type": "array", "items": { "type": "string" } }, "buildErrorAt": { "type": "number" }, "checksState": { "type": "string", "enum": [ "registered", "running", "completed" ] }, "checksConclusion": { "type": "string", "enum": [ "succeeded", "failed", "skipped", "canceled" ] }, "deletedAt": { "type": "number", "description": "A number containing the date when the deployment was deleted at milliseconds", "nullable": true }, "defaultRoute": { "type": "string", "description": "Computed field that is only available for deployments with a microfrontend configuration." }, "canceledAt": { "type": "number" }, "errorCode": { "type": "string" }, "errorLink": { "type": "string" }, "errorMessage": { "type": "string", "nullable": true }, "errorStep": { "type": "string" }, "passiveRegions": { "type": "array", "description": "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", "items": { "type": "string" } }, "gitSource": { "oneOf": [ { "type": "object", "required": [ "repoId", "type" ], "properties": { "type": { "type": "string", "enum": [ "github" ] }, "repoId": { "oneOf": [ { "type": "string" }, { "type": "number" } ] }, "ref": { "type": "string", "nullable": true }, "sha": { "type": "string" }, "prId": { "type": "number", "nullable": true } } }, { "type": "object", "required": [ "org", "repo", "type" ], "properties": { "type": { "type": "string", "enum": [ "github" ] }, "org": { "type": "string" }, "repo": { "type": "string" }, "ref": { "type": "string", "nullable": true }, "sha": { "type": "string" }, "prId": { "type": "number", "nullable": true } } }, { "type": "object", "required": [ "host", "repoId", "type" ], "properties": { "type": { "type": "string", "enum": [ "github-custom-host" ] }, "host": { "type": "string" }, "repoId": { "oneOf": [ { "type": "string" }, { "type": "number" } ] }, "ref": { "type": "string", "nullable": true }, "sha": { "type": "string" }, "prId": { "type": "number", "nullable": true } } }, { "type": "object", "required": [ "host", "org", "repo", "type" ], "properties": { "type": { "type": "string", "enum": [ "github-custom-host" ] }, "host": { "type": "string" }, "org": { "type": "string" }, "repo": { "type": "string" }, "ref": { "type": "string", "nullable": true }, "sha": { "type": "string" }, "prId": { "type": "number", "nullable": true } } }, { "type": "object", "required": [ "repoId", "type" ], "properties": { "type": { "type": "string", "enum": [ "github-limited" ] }, "repoId": { "oneOf": [ { "type": "string" }, { "type": "number" } ] }, "ref": { "type": "string", "nullable": true }, "sha": { "type": "string" }, "prId": { "type": "number", "nullable": true } } }, { "type": "object", "required": [ "org", "repo", "type" ], "properties": { "type": { "type": "string", "enum": [ "github-limited" ] }, "org": { "type": "string" }, "repo": { "type": "string" }, "ref": { "type": "string", "nullable": true }, "sha": { "type": "string" }, "prId": { "type": "number", "nullable": true } } }, { "type": "object", "required": [ "projectId", "type" ], "properties": { "type": { "type": "string", "enum": [ "gitlab" ] }, "projectId": { "oneOf": [ { "type": "string" }, { "type": "number" } ] }, "ref": { "type": "string", "nullable": true }, "sha": { "type": "string" }, "prId": { "type": "number", "nullable": true } } }, { "type": "object", "required": [ "repoUuid", "type" ], "properties": { "type": { "type": "string", "enum": [ "bitbucket" ] }, "workspaceUuid": { "type": "string" }, "repoUuid": { "type": "string" }, "ref": { "type": "string", "nullable": true }, "sha": { "type": "string" }, "prId": { "type": "number", "nullable": true } } }, { "type": "object", "required": [ "owner", "slug", "type" ], "properties": { "type": { "type": "string", "enum": [ "bitbucket" ] }, "owner": { "type": "string" }, "slug": { "type": "string" }, "ref": { "type": "string", "nullable": true }, "sha": { "type": "string" }, "prId": { "type": "number", "nullable": true } } }, { "type": "object", "required": [ "sha", "type" ], "properties": { "type": { "type": "string", "enum": [ "vercel" ] }, "org": { "type": "string" }, "repo": { "type": "string" }, "sha": { "type": "string" }, "repoPushedAt": { "type": "number" }, "ref": { "type": "string", "nullable": true }, "prId": { "type": "number", "nullable": true } } }, { "type": "object", "description": "Allows custom git sources (local folder mounted to the container) in test mode", "required": [ "gitUrl", "ref", "sha", "type" ], "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "ref": { "type": "string" }, "sha": { "type": "string" }, "gitUrl": { "type": "string" } } }, { "type": "object", "required": [ "ref", "repoId", "sha", "type" ], "properties": { "type": { "type": "string", "enum": [ "github" ] }, "ref": { "type": "string" }, "sha": { "type": "string" }, "repoId": { "type": "number" }, "org": { "type": "string" }, "repo": { "type": "string" } } }, { "type": "object", "required": [ "host", "ref", "repoId", "sha", "type" ], "properties": { "type": { "type": "string", "enum": [ "github-custom-host" ] }, "host": { "type": "string" }, "ref": { "type": "string" }, "sha": { "type": "string" }, "repoId": { "type": "number" }, "org": { "type": "string" }, "repo": { "type": "string" } } }, { "type": "object", "required": [ "ref", "repoId", "sha", "type" ], "properties": { "type": { "type": "string", "enum": [ "github-limited" ] }, "ref": { "type": "string" }, "sha": { "type": "string" }, "repoId": { "type": "number" }, "org": { "type": "string" }, "repo": { "type": "string" } } }, { "type": "object", "required": [ "projectId", "ref", "sha", "type" ], "properties": { "type": { "type": "string", "enum": [ "gitlab" ] }, "ref": { "type": "string" }, "sha": { "type": "string" }, "projectId": { "type": "number" } } }, { "type": "object", "required": [ "ref", "repoUuid", "sha", "type", "workspaceUuid" ], "properties": { "type": { "type": "string", "enum": [ "bitbucket" ] }, "ref": { "type": "string" }, "sha": { "type": "string" }, "owner": { "type": "string" }, "slug": { "type": "string" }, "workspaceUuid": { "type": "string" }, "repoUuid": { "type": "string" } } }, { "type": "object", "required": [ "org", "ref", "repo", "sha", "type" ], "properties": { "type": { "type": "string", "enum": [ "vercel" ] }, "ref": { "type": "string" }, "sha": { "type": "string" }, "org": { "type": "string" }, "repo": { "type": "string" }, "repoPushedAt": { "type": "number" } } } ] }, "manualProvisioning": { "type": "object", "description": "Present when deployment was created with VERCEL_MANUAL_PROVISIONING=true. The deployment stays in INITIALIZING until /continue is called.", "required": [ "state" ], "properties": { "state": { "type": "string", "description": "Current provisioning state", "enum": [ "PENDING", "COMPLETE", "TIMEOUT" ] }, "completedAt": { "type": "number", "description": "Timestamp when manual provisioning completed" } } }, "meta": { "type": "object", "additionalProperties": { "type": "string" } }, "originCacheRegion": { "type": "string" }, "nodeVersion": { "type": "string", "description": "If set it overrides the `projectSettings.nodeVersion` for this deployment.", "enum": [ "24.x", "22.x", "20.x", "18.x", "16.x", "14.x", "12.x", "10.x", "8.10.x" ] }, "project": { "type": "object", "description": "The public project information associated with the deployment.", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "framework": { "type": "string", "nullable": true } } }, "prebuilt": { "type": "boolean", "enum": [ false, true ] }, "readySubstate": { "type": "string", "description": "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", "enum": [ "STAGED", "ROLLING", "PROMOTED" ] }, "regions": { "type": "array", "description": "The regions the deployment exists in", "items": { "type": "string" } }, "softDeletedByRetention": { "type": "boolean", "description": "flag to indicate if the deployment was deleted by retention policy", "enum": [ false, true ] }, "source": { "type": "string", "description": "Where was the deployment created from", "enum": [ "api-trigger-git-deploy", "cli", "clone/repo", "git", "import", "import/repo", "redeploy", "v0-web" ] }, "target": { "type": "string", "description": "If defined, either `staging` if a staging alias in the format `..now.sh` was assigned upon creation, or `production` if the aliases from `alias` were assigned. `null` value indicates the \"preview\" deployment.", "enum": [ "staging", "production" ], "nullable": true }, "undeletedAt": { "type": "number", "description": "A number containing the date when the deployment was undeleted at milliseconds" }, "url": { "type": "string", "description": "A string with the unique URL of the deployment" }, "userConfiguredDeploymentId": { "type": "string", "description": "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." }, "version": { "type": "number", "description": "The platform version that was used to create the deployment.", "enum": [ 2 ] }, "oidcTokenClaims": { "type": "object", "required": [ "aud", "environment", "iss", "owner", "owner_id", "project", "project_id", "scope", "sub" ], "properties": { "iss": { "type": "string" }, "sub": { "type": "string" }, "scope": { "type": "string" }, "aud": { "type": "string" }, "owner": { "type": "string" }, "owner_id": { "type": "string" }, "project": { "type": "string" }, "project_id": { "type": "string" }, "environment": { "type": "string" }, "plan": { "type": "string" } } }, "projectId": { "type": "string" }, "plan": { "type": "string", "enum": [ "pro", "enterprise", "hobby" ] }, "platform": { "type": "object", "description": "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)", "required": [ "creator", "origin", "source" ], "properties": { "source": { "type": "object", "description": "The external platform that created the deployment (e.g. its display name).", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Display name of the platform." } } }, "origin": { "type": "object", "description": "Reference back to the entity on the platform that initiated the deployment.", "required": [ "type", "value" ], "properties": { "type": { "type": "string", "description": "Whether the value is an opaque identifier or a URL.", "enum": [ "id", "url" ] }, "value": { "type": "string", "description": "The identifier or URL pointing to the originating entity." } } }, "creator": { "type": "object", "description": "The user on the external platform who triggered the deployment.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Display name of the platform user." }, "avatar": { "type": "string", "description": "URL of the platform user's avatar image." } } }, "meta": { "type": "object", "description": "Arbitrary key-value metadata provided by the platform.", "additionalProperties": { "type": "string" } } } }, "connectBuildsEnabled": { "type": "boolean", "enum": [ false, true ] }, "connectConfigurationId": { "type": "string" }, "createdIn": { "type": "string" }, "crons": { "type": "array", "items": { "type": "object", "required": [ "path", "schedule" ], "properties": { "schedule": { "type": "string" }, "path": { "type": "string" } } } }, "functions": { "type": "object", "nullable": true, "additionalProperties": { "type": "object", "properties": { "architecture": { "type": "string", "enum": [ "x86_64", "arm64" ] }, "memory": { "type": "number" }, "maxDuration": { "oneOf": [ { "type": "number" }, { "type": "string", "enum": [ "max" ] } ] }, "regions": { "type": "array", "items": { "type": "string" } }, "functionFailoverRegions": { "type": "array", "items": { "type": "string" } }, "runtime": { "type": "string" }, "includeFiles": { "type": "string" }, "excludeFiles": { "type": "string" }, "experimentalTriggers": { "type": "array", "items": { "oneOf": [ { "type": "object", "description": "Queue trigger input event for v1beta (from vercel.json config). Requires explicit consumer name.", "required": [ "consumer", "topic", "type" ], "properties": { "type": { "type": "string", "description": "Event type - must be \"queue/v1beta\" (REQUIRED)", "enum": [ "queue/v1beta" ] }, "consumer": { "type": "string", "description": "Name of the consumer group for this trigger (REQUIRED)" }, "topic": { "type": "string", "description": "Name of the queue topic to consume from (REQUIRED)" }, "maxDeliveries": { "type": "number", "description": "Maximum number of delivery attempts for message processing (OPTIONAL) This represents the total number of times a message can be delivered, not the number of retries. Must be at least 1 if specified. Behavior when not specified depends on the server's default configuration." }, "retryAfterSeconds": { "type": "number", "description": "Delay in seconds before retrying failed executions (OPTIONAL) Behavior when not specified depends on the server's default configuration." }, "initialDelaySeconds": { "type": "number", "description": "Initial delay in seconds before first execution attempt (OPTIONAL) Must be 0 or greater. Use 0 for no initial delay. Behavior when not specified depends on the server's default configuration." }, "maxConcurrency": { "type": "number", "description": "Maximum number of concurrent executions for this consumer (OPTIONAL) Must be at least 1 if specified. Behavior when not specified depends on the server's default configuration." } } }, { "type": "object", "description": "Queue trigger input event for v2beta (from vercel.json config). Consumer name is implicitly derived from the function path. Only one trigger per function is allowed.", "required": [ "topic", "type" ], "properties": { "type": { "type": "string", "description": "Event type - must be \"queue/v2beta\" (REQUIRED)", "enum": [ "queue/v2beta" ] }, "topic": { "type": "string", "description": "Name of the queue topic to consume from (REQUIRED)" }, "maxDeliveries": { "type": "number", "description": "Maximum number of delivery attempts for message processing (OPTIONAL) This represents the total number of times a message can be delivered, not the number of retries. Must be at least 1 if specified. Behavior when not specified depends on the server's default configuration." }, "retryAfterSeconds": { "type": "number", "description": "Delay in seconds before retrying failed executions (OPTIONAL) Behavior when not specified depends on the server's default configuration." }, "initialDelaySeconds": { "type": "number", "description": "Initial delay in seconds before first execution attempt (OPTIONAL) Must be 0 or greater. Use 0 for no initial delay. Behavior when not specified depends on the server's default configuration." }, "maxConcurrency": { "type": "number", "description": "Maximum number of concurrent executions for this consumer (OPTIONAL) Must be at least 1 if specified. Behavior when not specified depends on the server's default configuration." } } } ] } }, "supportsCancellation": { "type": "boolean", "enum": [ false, true ] } } } }, "monorepoManager": { "type": "string", "nullable": true }, "ownerId": { "type": "string" }, "passiveConnectConfigurationId": { "type": "string", "description": "Since November 2023 this field defines a Secure Compute network that will only be used to deploy passive lambdas to (as in passiveRegions)" }, "routes": { "type": "array", "nullable": true, "items": { "oneOf": [ { "type": "object", "required": [ "src" ], "properties": { "src": { "type": "string" }, "dest": { "type": "string" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } }, "methods": { "type": "array", "items": { "type": "string" } }, "continue": { "type": "boolean", "enum": [ false, true ] }, "override": { "type": "boolean", "enum": [ false, true ] }, "caseSensitive": { "type": "boolean", "enum": [ false, true ] }, "check": { "type": "boolean", "enum": [ false, true ] }, "important": { "type": "boolean", "enum": [ false, true ] }, "status": { "type": "number" }, "has": { "type": "array", "items": { "oneOf": [ { "type": "object", "required": [ "type", "value" ], "properties": { "type": { "type": "string", "enum": [ "host" ] }, "value": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "eq": { "oneOf": [ { "type": "string" }, { "type": "number" } ] }, "neq": { "type": "string" }, "inc": { "type": "array", "items": { "type": "string" } }, "ninc": { "type": "array", "items": { "type": "string" } }, "pre": { "type": "string" }, "suf": { "type": "string" }, "re": { "type": "string" }, "gt": { "type": "number" }, "gte": { "type": "number" }, "lt": { "type": "number" }, "lte": { "type": "number" } } } ] } } }, { "type": "object", "required": [ "key", "type" ], "properties": { "type": { "type": "string", "enum": [ "header", "cookie", "query" ] }, "key": { "type": "string" }, "value": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "eq": { "oneOf": [ { "type": "string" }, { "type": "number" } ] }, "neq": { "type": "string" }, "inc": { "type": "array", "items": { "type": "string" } }, "ninc": { "type": "array", "items": { "type": "string" } }, "pre": { "type": "string" }, "suf": { "type": "string" }, "re": { "type": "string" }, "gt": { "type": "number" }, "gte": { "type": "number" }, "lt": { "type": "number" }, "lte": { "type": "number" } } } ] } } } ] } }, "missing": { "type": "array", "items": { "oneOf": [ { "type": "object", "required": [ "type", "value" ], "properties": { "type": { "type": "string", "enum": [ "host" ] }, "value": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "eq": { "oneOf": [ { "type": "string" }, { "type": "number" } ] }, "neq": { "type": "string" }, "inc": { "type": "array", "items": { "type": "string" } }, "ninc": { "type": "array", "items": { "type": "string" } }, "pre": { "type": "string" }, "suf": { "type": "string" }, "re": { "type": "string" }, "gt": { "type": "number" }, "gte": { "type": "number" }, "lt": { "type": "number" }, "lte": { "type": "number" } } } ] } } }, { "type": "object", "required": [ "key", "type" ], "properties": { "type": { "type": "string", "enum": [ "header", "cookie", "query" ] }, "key": { "type": "string" }, "value": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "eq": { "oneOf": [ { "type": "string" }, { "type": "number" } ] }, "neq": { "type": "string" }, "inc": { "type": "array", "items": { "type": "string" } }, "ninc": { "type": "array", "items": { "type": "string" } }, "pre": { "type": "string" }, "suf": { "type": "string" }, "re": { "type": "string" }, "gt": { "type": "number" }, "gte": { "type": "number" }, "lt": { "type": "number" }, "lte": { "type": "number" } } } ] } } } ] } }, "mitigate": { "type": "object", "required": [ "action" ], "properties": { "action": { "type": "string", "enum": [ "challenge", "deny" ] } } }, "transforms": { "type": "array", "items": { "type": "object", "required": [ "op", "target", "type" ], "properties": { "type": { "type": "string", "enum": [ "request.headers", "request.query", "response.headers" ] }, "op": { "type": "string", "enum": [ "append", "set", "delete" ] }, "target": { "type": "object", "required": [ "key" ], "properties": { "key": { "oneOf": [ { "type": "string" }, { "type": "object", "properties": { "eq": { "oneOf": [ { "type": "string" }, { "type": "number" } ] }, "neq": { "type": "string" }, "inc": { "type": "array", "items": { "type": "string" } }, "ninc": { "type": "array", "items": { "type": "string" } }, "pre": { "type": "string" }, "suf": { "type": "string" }, "gt": { "type": "number" }, "gte": { "type": "number" }, "lt": { "type": "number" }, "lte": { "type": "number" } } } ] } } }, "args": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "env": { "type": "array", "items": { "type": "string" } } } } }, "env": { "type": "array", "items": { "type": "string" } }, "locale": { "type": "object", "properties": { "redirect": { "type": "object", "additionalProperties": { "type": "string" } }, "cookie": { "type": "string" } } }, "source": { "type": "string", "description": "Aliases for `src`, `dest`, and `status`. These provide consistency with the `rewrites`, `redirects`, and `headers` fields which use `source`, `destination`, and `statusCode`. During normalization, these are converted to their canonical forms (`src`, `dest`, `status`) and stripped from the route object." }, "destination": { "type": "string" }, "statusCode": { "type": "number" }, "middlewarePath": { "type": "string", "description": "A middleware key within the `output` key under the build result. Overrides a `middleware` definition." }, "middlewareRawSrc": { "type": "array", "description": "The original middleware matchers.", "items": { "type": "string" } }, "middleware": { "type": "number", "description": "A middleware index in the `middleware` key under the build result" }, "respectOriginCacheControl": { "type": "boolean", "enum": [ false, true ] } } }, { "type": "object", "required": [ "handle" ], "properties": { "handle": { "type": "string", "enum": [ "error", "filesystem", "hit", "miss", "rewrite", "resource" ] }, "src": { "type": "string" }, "dest": { "type": "string" }, "status": { "type": "number" } } }, { "type": "object", "required": [ "continue", "middleware", "src" ], "properties": { "src": { "type": "string" }, "continue": { "type": "boolean", "enum": [ false, true ] }, "middleware": { "type": "number", "enum": [ 0 ] } } } ] } }, "gitRepo": { "nullable": true, "oneOf": [ { "type": "object", "required": [ "defaultBranch", "name", "namespace", "ownerType", "path", "private", "projectId", "type", "url" ], "properties": { "namespace": { "type": "string" }, "projectId": { "type": "number" }, "type": { "type": "string", "enum": [ "gitlab" ] }, "url": { "type": "string" }, "path": { "type": "string" }, "defaultBranch": { "type": "string" }, "name": { "type": "string" }, "private": { "type": "boolean", "enum": [ false, true ] }, "ownerType": { "type": "string", "enum": [ "team", "user" ] } } }, { "type": "object", "required": [ "defaultBranch", "name", "org", "ownerType", "path", "private", "repo", "repoId", "repoOwnerId", "type" ], "properties": { "org": { "type": "string" }, "repo": { "type": "string" }, "repoId": { "type": "number" }, "type": { "type": "string", "enum": [ "github" ] }, "repoOwnerId": { "type": "number" }, "path": { "type": "string" }, "defaultBranch": { "type": "string" }, "name": { "type": "string" }, "private": { "type": "boolean", "enum": [ false, true ] }, "ownerType": { "type": "string", "enum": [ "team", "user" ] } } }, { "type": "object", "required": [ "defaultBranch", "name", "owner", "ownerType", "path", "private", "repoUuid", "slug", "type", "workspaceUuid" ], "properties": { "owner": { "type": "string" }, "repoUuid": { "type": "string" }, "slug": { "type": "string" }, "type": { "type": "string", "enum": [ "bitbucket" ] }, "workspaceUuid": { "type": "string" }, "path": { "type": "string" }, "defaultBranch": { "type": "string" }, "name": { "type": "string" }, "private": { "type": "boolean", "enum": [ false, true ] }, "ownerType": { "type": "string", "enum": [ "team", "user" ] } } }, { "type": "object", "required": [ "defaultBranch", "name", "org", "ownerType", "path", "private", "repo", "type" ], "properties": { "org": { "type": "string" }, "repo": { "type": "string" }, "type": { "type": "string", "enum": [ "vercel" ] }, "path": { "type": "string" }, "defaultBranch": { "type": "string" }, "name": { "type": "string" }, "private": { "type": "boolean", "enum": [ false, true ] }, "ownerType": { "type": "string", "enum": [ "team", "user" ] } } } ] }, "flags": { "oneOf": [ { "type": "object", "description": "Flags defined in the Build Output API, used by this deployment. Primarily used by the Toolbar to know about the used flags.", "required": [ "definitions" ], "properties": { "definitions": { "type": "object", "additionalProperties": { "type": "object", "properties": { "options": { "type": "array", "items": { "type": "object", "required": [ "value" ], "properties": { "value": { "nullable": true, "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "array", "description": "TODO: The following types will eventually be exported by a more relevant package.", "items": { "type": "object", "description": "(circular reference)" } }, { "type": "object", "additionalProperties": { "type": "object", "description": "(circular reference)" } }, { "type": "boolean", "enum": [ false, true ] } ] }, "label": { "type": "string" } } } }, "url": { "type": "string" }, "description": { "type": "string" } } } } } }, { "type": "array", "description": "Flags defined in the Build Output API, used by this deployment. Primarily used by the Toolbar to know about the used flags.", "items": { "type": "object", "description": "Flags defined in the Build Output API, used by this deployment. Primarily used by the Toolbar to know about the used flags." } } ] }, "microfrontends": { "oneOf": [ { "type": "object", "required": [ "defaultAppProjectName", "groupIds" ], "properties": { "isDefaultApp": { "type": "boolean", "enum": [ false ] }, "defaultAppProjectName": { "type": "string", "description": "The project name of the default app of this deployment's microfrontends group." }, "defaultRoute": { "type": "string", "description": "A path that is used to take screenshots and as the default path in preview links when a domain for this microfrontend is shown in the UI." }, "groupIds": { "type": "array", "description": "The group of microfrontends that this project belongs to. Each microfrontend project must belong to a microfrontends group that is the set of microfrontends that are used together.", "items": { "type": "string" } } } }, { "type": "object", "required": [ "defaultAppProjectName", "groupIds", "isDefaultApp" ], "properties": { "isDefaultApp": { "type": "boolean", "enum": [ true ] }, "mfeConfigUploadState": { "type": "string", "description": "The result of the microfrontends config upload during deployment creation / build. Only set for default app deployments. The config upload is attempted during deployment create, and then again during the build. If the config is not in the root directory, or the deployment is prebuilt, the config cannot be uploaded during deployment create. The upload during deployment build finds the config even if it's not in the root directory, as it has access to all files. Uploading the config during create is ideal, as then all child deployments are guaranteed to have access to the default app deployment config even if the default app has not yet started building. If the config is not uploaded, the child app will show as building until the config has been uploaded during the default app build. - `success` - The config was uploaded successfully, either when the deployment was created or during the build. - `waiting_on_build` - The config could not be uploaded during deployment create, will be attempted again during the build. - `no_config` - No config was found. Only set once the build has not found the config in any of the deployment's files. - `undefined` - Legacy deployments, or there was an error uploading the config during deployment create.", "enum": [ "success", "waiting_on_build", "no_config" ] }, "defaultAppProjectName": { "type": "string", "description": "The project name of the default app of this deployment's microfrontends group." }, "defaultRoute": { "type": "string", "description": "A path that is used to take screenshots and as the default path in preview links when a domain for this microfrontend is shown in the UI." }, "groupIds": { "type": "array", "description": "The group of microfrontends that this project belongs to. Each microfrontend project must belong to a microfrontends group that is the set of microfrontends that are used together.", "items": { "type": "string" } } } } ] }, "config": { "type": "object", "description": "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", "required": [ "functionMemoryType", "functionTimeout", "functionType", "secureComputeFallbackRegion", "secureComputePrimaryRegion" ], "properties": { "version": { "type": "number" }, "functionType": { "type": "string", "enum": [ "standard", "fluid" ] }, "functionMemoryType": { "type": "string", "enum": [ "standard", "standard_legacy", "performance" ] }, "functionTimeout": { "type": "number", "nullable": true }, "secureComputePrimaryRegion": { "type": "string", "nullable": true }, "secureComputeFallbackRegion": { "type": "string", "nullable": true }, "isUsingActiveCPU": { "type": "boolean", "enum": [ false, true ] }, "resourceConfig": { "type": "object", "description": "Build resource configuration snapshot for this deployment.", "properties": { "buildQueue": { "type": "object", "description": "Build resource configuration snapshot for this deployment.", "properties": { "configuration": { "type": "string", "description": "Build resource configuration snapshot for this deployment.", "enum": [ "SKIP_NAMESPACE_QUEUE", "WAIT_FOR_NAMESPACE_QUEUE" ] } } }, "elasticConcurrency": { "type": "string", "description": "When elastic concurrency is used for this deployment, a value is set. The value tells the reason where the setting was coming from. - TEAM_SETTING: Inherited from team settings - PROJECT_SETTING: Inherited from project settings - SKIP_QUEUE: Manually triggered by user to skip the queues", "enum": [ "TEAM_SETTING", "PROJECT_SETTING", "SKIP_QUEUE" ] }, "buildMachine": { "type": "object", "properties": { "purchaseType": { "type": "string", "description": "Machine type that was used for the build.", "enum": [ "enhanced", "turbo", "standard" ], "nullable": true } } } } } } }, "checks": { "type": "object", "required": [ "deployment-alias" ], "properties": { "deployment-alias": { "type": "object", "description": "Condensed check data. Retrieve individual check and check run data using api-checks v2 routes.", "required": [ "startedAt", "state" ], "properties": { "state": { "type": "string", "enum": [ "succeeded", "failed", "pending" ] }, "startedAt": { "type": "number" }, "completedAt": { "type": "number" } } } } }, "seatBlock": { "type": "object", "description": "NSNB Blocked metadata", "required": [ "blockCode" ], "properties": { "blockCode": { "type": "string", "description": "The NSNB decision code for the seat block. TODO: We should consolidate block types.", "enum": [ "TEAM_ACCESS_REQUIRED", "COMMIT_AUTHOR_REQUIRED" ] }, "userId": { "type": "string", "description": "The blocked vercel user ID." }, "isVerified": { "type": "boolean", "description": "Determines if the user was verified during the block. In the git integration case, the commit sender was the author.", "enum": [ false, true ] }, "gitUserId": { "oneOf": [ { "type": "string" }, { "type": "number" } ] }, "gitProvider": { "type": "string", "description": "The git provider type associated with gitUserId.", "enum": [ "gitlab", "bitbucket", "github" ] } } }, "attribution": { "type": "object", "description": "Attribution metadata for the deployment, linking commit author to git and Vercel users. Only populated when the `enable-deployment-attribution` flag is enabled.", "properties": { "commitMeta": { "type": "object", "description": "Commit metadata from the git commit author", "properties": { "email": { "type": "string", "description": "Email from git commit author" }, "name": { "type": "string", "description": "Name from git commit author" }, "isVerified": { "type": "boolean", "description": "Whether the commit was signed/verified (GitHub only, others return undefined)", "enum": [ false, true ] } } }, "gitUser": { "type": "object", "description": "Git provider user associated with the commit author email (only set if resolved)", "required": [ "id", "login" ], "properties": { "id": { "oneOf": [ { "type": "string" }, { "type": "number" } ] }, "login": { "type": "string", "description": "Git provider username/login" }, "type": { "type": "string", "description": "User type" } } }, "vercelUser": { "type": "object", "description": "Vercel user linked to the git provider account (only set if resolved)", "required": [ "id", "username" ], "properties": { "id": { "type": "string", "description": "Vercel user ID" }, "username": { "type": "string", "description": "Vercel username" }, "teamRoles": { "type": "array", "description": "Team roles at time of deployment", "items": { "type": "string" } } } } } } } } ``` ### 400: One of the provided values in the request query is invalid. ### 401: The request is not authorized. ### 403: You do not have permission to access this resource. ### 404: No description --- ## Related - [deployments endpoints](/docs/rest-api#deployments) - [REST API overview](/docs/rest-api) - [OpenAPI spec](https://openapi.vercel.sh/) (machine-readable, all endpoints) --- [View full sitemap](/docs/sitemap)