--- title: "List deployments" method: GET path: "/v7/deployments" tags: ["deployments"] --- # List deployments `GET /v7/deployments` ## Request - Base URL: `https://api.vercel.com` - URL: `https://api.vercel.com/v7/deployments` - Auth: HTTP bearer List deployments under the authenticated user or team. If a deployment hasn't finished uploading (is incomplete), the `url` property will have a value of `null`. ## Query parameters - `app` string: Name of the deployment. - `from` number: Gets the deployment created after this Date timestamp. (default: current time) - `limit` number: Maximum number of deployments to list from a request. - `projectId` string: Filter deployments from the given ID or name. - `projectIds` string[]: Filter deployments from the given project IDs. Cannot be used when projectId is specified. - `target` string: Filter deployments based on the environment. - `to` number: Gets the deployment created before this Date timestamp. (default: current time) - `users` string: Filter out deployments based on users who have created the deployment. - `since` number: Get Deployments created after this JavaScript timestamp. - `until` number: Get Deployments created before this JavaScript timestamp. - `state` string: Filter deployments based on their state (`BUILDING`, `ERROR`, `INITIALIZING`, `QUEUED`, `READY`, `CANCELED`, `BLOCKED`) - `rollbackCandidate` boolean: Filter deployments based on their rollback candidacy - `branch` string: Filter deployments based on the branch name - `sha` string: Filter deployments based on the SHA - `teamId` string - `slug` string ## Response `200` - object - `deployments` object[], required - `aliasAssigned` union - number - false | true - `aliasError` object, nullable: An error object in case aliasing of the deployment failed. - `code` string, required - `message` string, required - `attribution` object: Commit attribution metadata - `commitMeta` object: Commit metadata from the git commit author - `email` string: Email from git commit author - `isVerified` false | true: Whether the commit was signed/verified (GitHub only, others return undefined) - `name` string: Name from git commit author - `gitUser` object: Git provider user associated with the commit author email (only set if resolved) - `id` union, required - string - number - `login` string, required: Git provider username/login - `provider` string: The git provider (github, gitlab, bitbucket) - `type` string: User type - `vercelUser` object: Vercel user linked to the git provider account (only set if resolved) - `id` string, required: Vercel user ID - `teamRoles` string[]: Team roles at time of deployment - `username` string, required: Vercel username - `buildingAt` number: Timestamp of when the deployment started building at. - `checks` object: Detailed information about v2 deployment checks. Includes information about blocked workflows in the deployment lifecycle. - `deployment-alias` object, required - `completedAt` number - `startedAt` number, required - `state` 'failed' | 'pending' | 'succeeded', required - `checksConclusion` 'canceled' | 'failed' | 'skipped' | 'succeeded': Conclusion for checks - `checksState` 'completed' | 'registered' | 'running': State of all registered checks - `connectBuildsEnabled` false | true: The flag saying if Secure Compute network is used for builds - `connectConfigurationId` string: The ID of Secure Compute network used for this deployment - `created` number, required: Timestamp of when the deployment got created. - `createdAt` number, required - `creator` object, required: Metadata information of the deployment creator. - `email` string: The email address of the user. - `githubLogin` string: The GitHub login of the user. - `gitlabLogin` string: The GitLab login of the user. - `type` 'app' | 'integration' | 'project' | 'system' | 'user': Principal type of the deployment creator. Defaults to `"user"` if absent (legacy deployments created before principal attribution was recorded). - `uid` string, required: Stable creator id across principal types. This may be a user ID, an app ID, an integration configuration ID, or `system`. - `username` string: The username of the user. - `customEnvironment` object: The custom environment used for this deployment, if any - `id` string, required - `slug` string - `defaultRoute` string: The default route that should be used for screenshots and links if configured with microfrontends. - `deleted` number: Timestamp of when the deployment got deleted. - `errorCode` string: Error code when the deployment is in an error state. - `errorMessage` string, nullable: Error message when the deployment is in an canceled or error state. - `expiration` number: The expiration configured by the project retention policy - `inspectorUrl` string, nullable, required: Vercel URL to inspect the deployment. - `isRollbackCandidate` false | true | null, nullable: Deployment can be used for instant rollback - `manualProvisioning` object - `completedAt` number: Timestamp when manual provisioning completed - `state` 'COMPLETE' | 'PENDING' | 'TIMEOUT', required: Current provisioning state - `meta` object: Metadata information from the Git provider. - `name` string, required: The name of the deployment. - `oomReport` 'out-of-memory': Indicates if the deployment encountered an out-of-memory error. - `passiveConnectConfigurationId` string: The ID of Secure Compute network used for this deployment's passive functions - `platform` object: Metadata about the source platform that triggered the deployment. - `creator` object, required: The user on the external platform who triggered the deployment. - `avatar` string: URL of the platform user's avatar image. - `name` string, required: Display name of the platform user. - `meta` object: Arbitrary key-value metadata provided by the platform. - `origin` object, required: Reference back to the entity on the platform that initiated the deployment. - `type` 'id' | 'url', required: Whether the value is an opaque identifier or a URL. - `value` string, required: The identifier or URL pointing to the originating entity. - `source` object, required: The external platform that created the deployment (e.g. its display name). - `name` string, required: Display name of the platform. - `prebuilt` false | true - `projectId` string, required: The project ID of the deployment - `projectSettings` object: The project settings which was used for this deployment - `buildCommand` string, nullable - `commandForIgnoringBuildStep` string, nullable - `createdAt` number - `customerSupportCodeVisibility` false | true - `devCommand` string, nullable - `framework` 'actix-web' | 'angular' | 'ash' | 'astro' | 'axum' | 'blitzjs' | 'brunch' | 'bun' | 'container' | 'create-react-app' | 'django' | 'docusaurus' | 'docusaurus-2' | 'dojo' | 'eleventy' | 'elysia' | 'ember' | 'eve' | 'express' | 'factory-eve' | 'fastapi' | 'fasthtml' | 'fastify' | 'flask' | 'gatsby' | 'go' | 'gridsome' | 'h3' | 'hexo' | 'hono' | 'hugo' | 'hydrogen' | 'ionic-angular' | 'ionic-react' | 'jekyll' | 'koa' | 'mastra' | 'middleman' | 'nestjs' | 'nextjs' | 'nitro' | 'node' | 'nuxtjs' | 'parcel' | 'polymer' | 'preact' | 'python' | 'react-router' | 'redwoodjs' | 'remix' | 'ruby' | 'rust' | 'saber' | 'sanity' | 'sanity-v2' | 'sapper' | 'scully' | 'services' | 'solidstart' | 'solidstart-1' | 'stencil' | 'storybook' | 'svelte' | 'sveltekit' | 'sveltekit-1' | 'tanstack-start' | 'tanstack-start-lovable' | 'umijs' | 'vite' | 'vitepress' | 'vue' | 'vuepress' | 'xmcp' | 'zola' | 'null', nullable - `gitComments` object: Since June '23 - `onCommit` false | true, required: Whether the Vercel bot should comment on commits - `onPullRequest` false | true, required: Whether the Vercel bot should comment on PRs - `gitForkProtection` false | true - `gitLFS` false | true - `installCommand` string, nullable - `nodeVersion` '10.x' | '12.x' | '14.x' | '16.x' | '18.x' | '20.x' | '22.x' | '24.x' | '26.x' | '8.10.x' - `outputDirectory` string, nullable - `rootDirectory` string, nullable - `skipGitConnectDuringLink` false | true - `sourceFilesOutsideRootDirectory` false | true - `speedInsights` object - `canceledAt` number - `dataReceivedAt` number: When the first free (not Speed Insights Plus) production data point was observed, in ms. Set once by subscriber-analytics-events; projects that already had data before this field shipped get it backfilled on their next batch, so it reads "first free data point observed", not necessarily "first ever". - `disabledAt` number - `enabledAt` number - `hasData` false | true - `id` string, required - `paidAt` number - `vercelFlags` object: Vercel Flags activation metadata copied from the project at deployment creation. - `enabledAt` number - `webAnalytics` object - `canceledAt` number - `disabledAt` number - `enabledAt` number - `hasData` true - `id` string, required - `proposedExpiration` number: The expiration proposed to replace the existing expiration - `ready` number: Timestamp of when the deployment got ready. - `readyState` 'BLOCKED' | 'BUILDING' | 'CANCELED' | 'DELETED' | 'ERROR' | 'INITIALIZING' | 'QUEUED' | 'READY', required - `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 gradually transitioning production traffic - PROMOTED: has seen production traffic - `seatBlock` object: NSNB Blocked metadata - `blockCode` 'COMMIT_AUTHOR_REQUIRED' | 'TEAM_ACCESS_REQUIRED', required: The NSNB decision code for the seat block. TODO: We should consolidate block types. - `gitProvider` 'bitbucket' | 'github' | 'gitlab': The git provider type associated with gitUserId. - `gitUserId` union - string - number - `isVerified` false | true: Determines if the user was verified during the block. In the git integration case, the commit sender was the author. - `userId` string: The blocked vercel user ID. - `softDeletedByRetention` false | true: Optional flag to indicate if the deployment was soft deleted by retention policy. - `source` 'api-trigger-git-deploy' | 'cli' | 'clone/repo' | 'drop' | 'git' | 'git-deploy-hook' | 'import' | 'import/repo' | 'redeploy' | 'v0-web': The source of the deployment. - `state` 'BLOCKED' | 'BUILDING' | 'CANCELED' | 'DELETED' | 'ERROR' | 'INITIALIZING' | 'QUEUED' | 'READY': In which state is the deployment. - `target` 'production' | 'staging' | 'null', nullable: On which environment has the deployment been deployed to. - `type` 'LAMBDAS', required: The type of the deployment. - `uid` string, required: The unique identifier of the deployment. - `undeleted` number: Timestamp of when the deployment was undeleted. - `url` string, required: The URL of the deployment. - `pagination` Pagination, required: This object contains information related to the pagination of the current request, including the necessary parameters to get the next or previous page of data. - `count` number, required: Amount of items in the current page. - `next` number, nullable, required: Timestamp that must be used to request the next page. - `prev` number, nullable, required: Timestamp that must be used to request the previous page. ## Other responses - `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` - `410` - `422` ## Changes - **2026-10-26** `b1c16fd8828a`: 1 info - added the optional property `deployments/items/projectSettings/vercelFlags` to the response with the `200` status - **2026-10-23** `2060b55dc517`: 1 warning - added the new `project` enum value to the `deployments/items/creator/type` response property for the response status `200` - **2026-10-16** `bdab3c0b548a`: 1 warning - added the new `26.x` enum value to the `deployments/items/projectSettings/nodeVersion` response property for the response status `200` - **2026-09-03** `7c947faac0ef`: 1 warning - added the new `factory-eve` enum value to the `deployments/items/projectSettings/framework` response property for the response status `200` - **2026-08-20** `b4b4b597ab64`: 1 info - added the optional property `deployments/items/projectSettings/speedInsights/dataReceivedAt` to the response with the `200` status [Operation history](https://skmtc.dev/vercel/apis/vercel-api/changes/v7/deployments/get.md) --- [API](https://skmtc.dev/vercel/apis/vercel-api.md) - [All operations](https://skmtc.dev/vercel/apis/vercel-api/llms.txt) - [OpenAPI document](https://skmtc.dev/vercel/apis/vercel-api/revisions/60686c0e1f6a?raw)