---
title: "List deployments"
method: GET
path: "/v7/deployments"
tags: ["deployments"]
---

# List deployments

`GET /v7/deployments`

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
  - `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.
  - `deployments` object[], required
    - `createdAt` number, required
    - `readyState` 'BLOCKED' | 'BUILDING' | 'CANCELED' | 'DELETED' | 'ERROR' | 'INITIALIZING' | 'QUEUED' | 'READY', required
    - `uid` string, required — The unique identifier of the deployment.
    - `name` string, required — The name of the deployment.
    - `projectId` string, required — The project ID of the deployment
    - `url` string, required — The URL of the deployment.
    - `created` number, required — Timestamp of when the deployment got created.
    - `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.
    - `undeleted` number — Timestamp of when the deployment was undeleted.
    - `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.
    - `type` 'LAMBDAS', required — The type of the deployment.
    - `creator` object, required — Metadata information of the user who created the deployment.
      - `uid` string, required — The unique identifier of the user.
      - `email` string — The email address of the user.
      - `username` string — The username of the user.
      - `githubLogin` string — The GitHub login of the user.
      - `gitlabLogin` string — The GitLab login of the user.
    - `meta` object — Metadata information from the Git provider.
    - `target` 'production' | 'staging' | 'null', nullable — On which environment has the deployment been deployed to.
    - `aliasError` object, nullable — An error object in case aliasing of the deployment failed.
      - `code` string, required
      - `message` string, required
    - `aliasAssigned` union
      - number
      - false | true
    - `buildingAt` number — Timestamp of when the deployment started building at.
    - `ready` number — Timestamp of when the deployment got ready.
    - `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
    - `checksState` 'completed' | 'registered' | 'running' — State of all registered checks
    - `checksConclusion` 'canceled' | 'failed' | 'skipped' | 'succeeded' — Conclusion for checks
    - `checks` object — Detailed information about v2 deployment checks. Includes information about blocked workflows in the deployment lifecycle.
      - `deployment-alias` object, required — Detailed information about v2 deployment checks. Includes information about blocked workflows in the deployment lifecycle.
        - `state` 'failed' | 'pending' | 'succeeded', required
        - `startedAt` number, required
        - `completedAt` number
    - `inspectorUrl` string, nullable, required — Vercel URL to inspect the deployment.
    - `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.
    - `oomReport` 'out-of-memory' — Indicates if the deployment encountered an out-of-memory error.
    - `isRollbackCandidate` false | true | null, nullable — Deployment can be used for instant rollback
    - `prebuilt` false | true
    - `manualProvisioning` object
      - `state` 'COMPLETE' | 'PENDING' | 'TIMEOUT', required — Current provisioning state
      - `completedAt` number — Timestamp when manual provisioning completed
    - `projectSettings` object — The project settings which was used for this deployment
      - `framework` 'actix-web' | 'angular' | 'ash' | 'astro' | 'axum' | 'blitzjs' | 'brunch' | 'bun' | 'container' | 'create-react-app' | 'django' | 'docusaurus' | 'docusaurus-2' | 'dojo' | 'eleventy' | 'elysia' | 'ember' | 'eve' | 'express' | '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
      - `gitForkProtection` false | true
      - `customerSupportCodeVisibility` false | true
      - `gitLFS` false | true
      - `devCommand` string, nullable
      - `installCommand` string, nullable
      - `buildCommand` string, nullable
      - `nodeVersion` '10.x' | '12.x' | '14.x' | '16.x' | '18.x' | '20.x' | '22.x' | '24.x' | '8.10.x'
      - `outputDirectory` string, nullable
      - `rootDirectory` string, nullable
      - `sourceFilesOutsideRootDirectory` false | true
      - `commandForIgnoringBuildStep` string, nullable
      - `createdAt` number
      - `speedInsights` object
        - `id` string, required
        - `enabledAt` number
        - `disabledAt` number
        - `canceledAt` number
        - `hasData` false | true
        - `paidAt` number
      - `webAnalytics` object
        - `id` string, required
        - `disabledAt` number
        - `canceledAt` number
        - `enabledAt` number
        - `hasData` true
      - `skipGitConnectDuringLink` false | true
      - `gitComments` object — Since June '23
        - `onPullRequest` false | true, required — Whether the Vercel bot should comment on PRs
        - `onCommit` false | true, required — Whether the Vercel bot should comment on commits
    - `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
    - `passiveConnectConfigurationId` string — The ID of Secure Compute network used for this deployment's passive functions
    - `expiration` number — The expiration configured by the project retention policy
    - `proposedExpiration` number — The expiration proposed to replace the existing expiration
    - `platform` object — Metadata about the source platform that triggered the deployment.
      - `source` object, required — The external platform that created the deployment (e.g. its display name).
        - `name` string, required — Display name of 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.
      - `creator` object, required — The user on the external platform who triggered the deployment.
        - `name` string, required — Display name of the platform user.
        - `avatar` string — URL of the platform user's avatar image.
      - `meta` object — Arbitrary key-value metadata provided by the platform.
    - `customEnvironment` object — The custom environment used for this deployment, if any
      - `id` string, required
      - `slug` string
    - `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.
      - `userId` string — The blocked vercel user ID.
      - `isVerified` false | true — Determines if the user was verified during the block. In the git integration case, the commit sender was the author.
      - `gitUserId` union
        - string
        - number
      - `gitProvider` 'bitbucket' | 'github' | 'gitlab' — The git provider type associated with gitUserId.
    - `attribution` object — Commit attribution metadata
      - `commitMeta` object — Commit metadata from the git commit author
        - `email` string — Email from git commit author
        - `name` string — Name from git commit author
        - `isVerified` false | true — Whether the commit was signed/verified (GitHub only, others return undefined)
      - `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
        - `type` string — User type
        - `provider` string — The git provider (github, gitlab, bitbucket)
      - `vercelUser` object — Vercel user linked to the git provider account (only set if resolved)
        - `id` string, required — Vercel user ID
        - `username` string, required — Vercel username
        - `teamRoles` string[] — Team roles at time of deployment

## 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`

---

[API](https://skmtc.net/vercel/apis/api.md) · [All operations](https://skmtc.net/vercel/apis/api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/vercel/api/versions/61d1ba3f6dac/schema)