--- title: list-deployments product: vercel url: /docs/rest-api/deployments/list-deployments type: reference prerequisites: [] related: - /docs/rest-api summary: Learn about list-deployments on Vercel. install_vercel_plugin: npx plugins add vercel/vercel-plugin --- # List deployments ```http GET /v6/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`. ## Authentication **bearerToken**: HTTP bearer ## Query parameters | Name | Type | Required | Description | |---|---|---|---| | `app` | string | No | Name of the deployment. | | `from` | number | No | Gets the deployment created after this Date timestamp. (default: current time) | | `limit` | number | No | Maximum number of deployments to list from a request. | | `projectId` | string | No | Filter deployments from the given ID or name. | | `projectIds` | array | No | Filter deployments from the given project IDs. Cannot be used when projectId is specified. | | `target` | string | No | Filter deployments based on the environment. | | `to` | number | No | Gets the deployment created before this Date timestamp. (default: current time) | | `users` | string | No | Filter out deployments based on users who have created the deployment. | | `since` | number | No | Get Deployments created after this JavaScript timestamp. | | `until` | number | No | Get Deployments created before this JavaScript timestamp. | | `state` | string | No | Filter deployments based on their state (`BUILDING`, `ERROR`, `INITIALIZING`, `QUEUED`, `READY`, `CANCELED`) | | `rollbackCandidate` | boolean | No | Filter deployments based on their rollback candidacy | | `branch` | string | No | Filter deployments based on the branch name | | `sha` | string | No | Filter deployments based on the SHA | | `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", "required": [ "deployments", "pagination" ], "properties": { "pagination": { "type": "object", "description": "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.", "required": [ "count", "next", "prev" ], "properties": { "count": { "type": "number", "description": "Amount of items in the current page." }, "next": { "type": "number", "description": "Timestamp that must be used to request the next page.", "nullable": true }, "prev": { "type": "number", "description": "Timestamp that must be used to request the previous page.", "nullable": true } } }, "deployments": { "type": "array", "items": { "type": "object", "required": [ "created", "creator", "inspectorUrl", "name", "projectId", "type", "uid", "url" ], "properties": { "uid": { "type": "string", "description": "The unique identifier of the deployment." }, "name": { "type": "string", "description": "The name of the deployment." }, "projectId": { "type": "string", "description": "The project ID of the deployment" }, "url": { "type": "string", "description": "The URL of the deployment." }, "created": { "type": "number", "description": "Timestamp of when the deployment got created." }, "defaultRoute": { "type": "string", "description": "The default route that should be used for screenshots and links if configured with microfrontends." }, "deleted": { "type": "number", "description": "Timestamp of when the deployment got deleted." }, "undeleted": { "type": "number", "description": "Timestamp of when the deployment was undeleted." }, "softDeletedByRetention": { "type": "boolean", "description": "Optional flag to indicate if the deployment was soft deleted by retention policy.", "enum": [ false, true ] }, "source": { "type": "string", "description": "The source of the deployment.", "enum": [ "api-trigger-git-deploy", "cli", "clone/repo", "git", "import", "import/repo", "redeploy", "v0-web" ] }, "state": { "type": "string", "description": "In which state is the deployment.", "enum": [ "BUILDING", "ERROR", "INITIALIZING", "QUEUED", "READY", "CANCELED", "DELETED" ] }, "readyState": { "type": "string", "description": "In which state is the deployment.", "enum": [ "BUILDING", "ERROR", "INITIALIZING", "QUEUED", "READY", "CANCELED", "DELETED" ] }, "type": { "type": "string", "description": "The type of the deployment.", "enum": [ "LAMBDAS" ] }, "creator": { "type": "object", "description": "Metadata information of the user who created the deployment.", "required": [ "uid" ], "properties": { "uid": { "type": "string", "description": "The unique identifier of the user." }, "email": { "type": "string", "description": "The email address of the user." }, "username": { "type": "string", "description": "The username of the user." }, "githubLogin": { "type": "string", "description": "The GitHub login of the user." }, "gitlabLogin": { "type": "string", "description": "The GitLab login of the user." } } }, "meta": { "type": "object", "description": "Metadata information from the Git provider.", "additionalProperties": { "type": "string", "description": "Metadata information from the Git provider." } }, "target": { "type": "string", "description": "On which environment has the deployment been deployed to.", "enum": [ "production", "staging" ], "nullable": true }, "aliasError": { "type": "object", "description": "An error object in case aliasing of the deployment failed.", "nullable": true, "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "aliasAssigned": { "nullable": true, "oneOf": [ { "type": "number" }, { "type": "boolean", "enum": [ false, true ] } ] }, "createdAt": { "type": "number", "description": "Timestamp of when the deployment got created." }, "buildingAt": { "type": "number", "description": "Timestamp of when the deployment started building at." }, "ready": { "type": "number", "description": "Timestamp of when the deployment got ready." }, "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 gradually transitioning production traffic - PROMOTED: has seen production traffic", "enum": [ "STAGED", "ROLLING", "PROMOTED" ] }, "checksState": { "type": "string", "description": "State of all registered checks", "enum": [ "registered", "running", "completed" ] }, "checksConclusion": { "type": "string", "description": "Conclusion for checks", "enum": [ "succeeded", "failed", "skipped", "canceled" ] }, "checks": { "type": "object", "description": "Detailed information about v2 deployment checks. Includes information about blocked workflows in the deployment lifecycle.", "required": [ "deployment-alias" ], "properties": { "deployment-alias": { "type": "object", "description": "Detailed information about v2 deployment checks. Includes information about blocked workflows in the deployment lifecycle.", "required": [ "startedAt", "state" ], "properties": { "state": { "type": "string", "enum": [ "succeeded", "failed", "pending" ] }, "startedAt": { "type": "number" }, "completedAt": { "type": "number" } } } } }, "inspectorUrl": { "type": "string", "description": "Vercel URL to inspect the deployment.", "nullable": true }, "errorCode": { "type": "string", "description": "Error code when the deployment is in an error state." }, "errorMessage": { "type": "string", "description": "Error message when the deployment is in an canceled or error state.", "nullable": true }, "oomReport": { "type": "string", "description": "Indicates if the deployment encountered an out-of-memory error.", "enum": [ "out-of-memory" ] }, "isRollbackCandidate": { "type": "boolean", "description": "Deployment can be used for instant rollback", "enum": [ false, true ], "nullable": true }, "prebuilt": { "type": "boolean", "enum": [ false, true ] }, "projectSettings": { "type": "object", "description": "The project settings which was used for this deployment", "properties": { "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 }, "gitForkProtection": { "type": "boolean", "enum": [ false, true ] }, "customerSupportCodeVisibility": { "type": "boolean", "enum": [ false, true ] }, "gitLFS": { "type": "boolean", "enum": [ false, true ] }, "devCommand": { "type": "string", "nullable": true }, "installCommand": { "type": "string", "nullable": true }, "buildCommand": { "type": "string", "nullable": true }, "nodeVersion": { "type": "string", "enum": [ "24.x", "22.x", "20.x", "18.x", "16.x", "14.x", "12.x", "10.x", "8.10.x" ] }, "outputDirectory": { "type": "string", "nullable": true }, "publicSource": { "type": "boolean", "enum": [ false, true ], "nullable": true }, "rootDirectory": { "type": "string", "nullable": true }, "sourceFilesOutsideRootDirectory": { "type": "boolean", "enum": [ false, true ] }, "commandForIgnoringBuildStep": { "type": "string", "nullable": true }, "createdAt": { "type": "number" }, "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 ] } } }, "skipGitConnectDuringLink": { "type": "boolean", "enum": [ false, true ] }, "gitComments": { "type": "object", "description": "Since June '23", "required": [ "onCommit", "onPullRequest" ], "properties": { "onPullRequest": { "type": "boolean", "description": "Whether the Vercel bot should comment on PRs", "enum": [ false, true ] }, "onCommit": { "type": "boolean", "description": "Whether the Vercel bot should comment on commits", "enum": [ false, true ] } } } } }, "connectBuildsEnabled": { "type": "boolean", "description": "The flag saying if Secure Compute network is used for builds", "enum": [ false, true ] }, "connectConfigurationId": { "type": "string", "description": "The ID of Secure Compute network used for this deployment" }, "passiveConnectConfigurationId": { "type": "string", "description": "The ID of Secure Compute network used for this deployment's passive functions" }, "expiration": { "type": "number", "description": "The expiration configured by the project retention policy" }, "proposedExpiration": { "type": "number", "description": "The expiration proposed to replace the existing expiration" }, "platform": { "type": "object", "description": "Metadata about the source platform that triggered the deployment.", "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": [ "url", "id" ] }, "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" } } } }, "customEnvironment": { "type": "object", "description": "The custom environment used for this deployment, if any", "required": [ "id" ], "properties": { "id": { "type": "string" }, "slug": { "type": "string" } } }, "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": [ "github", "gitlab", "bitbucket" ] } } }, "attribution": { "type": "object", "description": "Commit attribution metadata", "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 ### 422: 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)