List deployments | Vercel REST API

APIs & SDKs

List deployments

GEThttps://api.vercel.com/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.

https://api.vercel.com/v7/deployments

const response = await fetch('https://api.vercel.com/v7/deployments?app=string&from=123&limit=123&projectId=string&projectIds=[]&target=string&to=123&users=string&since=123&until=123&state=string&rollbackCandidate=true&branch=string&sha=string&teamId=string&slug=string', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
  },
});

const data = await response.json();
console.log(data);

Response

{
  "deployments": [
    {
      "aliasAssigned": "123",
      "aliasError": {
        "code": "string",
        "message": "string"
      },
      "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"
        }
      },
      "buildingAt": "1609492210000",
      "checks": {
        "deployment-alias": {
          "completedAt": "123",
          "startedAt": "123",
          "state": "failed"
        }
      },
      "checksConclusion": "canceled",
      "checksState": "completed",
      "connectBuildsEnabled": "false",
      "connectConfigurationId": "example_id",
      "created": "1609492210000",
      "createdAt": "123",
      "creator": {
        "email": "example@example.com",
        "githubLogin": "johndoe",
        "gitlabLogin": "johndoe",
        "type": "app",
        "uid": "eLrCnEgbKhsHyfbiNR7E8496",
        "username": "johndoe"
      },
      "customEnvironment": {
        "id": "icfg_1234567890",
        "slug": "string"
      },
      "defaultRoute": "/docs",
      "deleted": "1609492210000",
      "errorCode": "BUILD_FAILED",
      "errorMessage": "The Deployment has been canceled because this project was not affected",
      "expiration": "123",
      "inspectorUrl": "https://vercel.com/acme/nextjs/J1hXN00qjUeoYfpEEf7dnDtpSiVq",
      "isRollbackCandidate": "false",
      "manualProvisioning": {
        "completedAt": "123",
        "state": "COMPLETE"
      },
      "meta": "value",
      "name": "docs",
      "oomReport": "out-of-memory",
      "passiveConnectConfigurationId": "example_id",
      "platform": {
        "creator": {
          "avatar": "string",
          "name": "Example Name"
        },
        "meta": "value",
        "origin": {
          "type": "id",
          "value": "string"
        },
        "source": {
          "name": "Example Name"
        }
      },
      "prebuilt": "false",
      "projectId": "example_id",
      "projectSettings": {
        "buildCommand": "string",
        "commandForIgnoringBuildStep": "string",
        "createdAt": "123",
        "customerSupportCodeVisibility": "false",
        "devCommand": "string",
        "framework": "actix-web",
        "gitComments": {
          "onCommit": "false",
          "onPullRequest": "false"
        },
        "gitForkProtection": "false",
        "gitLFS": "false",
        "installCommand": "string",
        "nodeVersion": "10.x",
        "outputDirectory": "string",
        "rootDirectory": "string",
        "skipGitConnectDuringLink": "false",
        "sourceFilesOutsideRootDirectory": "false",
        "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"
        }
      },
      "proposedExpiration": "123",
      "ready": "1609492210000",
      "readyState": "BLOCKED",
      "readySubstate": "PROMOTED",
      "seatBlock": {
        "blockCode": "COMMIT_AUTHOR_REQUIRED",
        "gitProvider": "bitbucket",
        "gitUserId": "example_id",
        "isVerified": "false",
        "userId": "example_id"
      },
      "softDeletedByRetention": "true",
      "source": "cli",
      "state": "READY",
      "target": "production",
      "type": "LAMBDAS",
      "uid": "dpl_2euZBFqxYdDMDG1jTrHFnNZ2eUVa",
      "undeleted": "1609492210000",
      "url": "docs-9jaeg38me.vercel.app"
    }
  ],
  "pagination": {
    "count": "20",
    "next": "1540095775951",
    "prev": "1540095775951"
  }
}

Authentication

AuthorizationbearerToken

Default authentication mechanism

Query parameters

appstringOptional

Name of the deployment.

fromnumberOptionalDeprecated

Gets the deployment created after this Date timestamp. (default: current time)

limitnumberOptional

Maximum number of deployments to list from a request.

projectIdstringOptional

Filter deployments from the given ID or name.

projectIdsarrayOptional

Filter deployments from the given project IDs. Cannot be used when projectId is specified.

targetstringOptional

Filter deployments based on the environment.

tonumberOptionalDeprecated

Gets the deployment created before this Date timestamp. (default: current time)

usersstringOptional

Filter out deployments based on users who have created the deployment.

sincenumberOptional

Get Deployments created after this JavaScript timestamp.

untilnumberOptional

Get Deployments created before this JavaScript timestamp.

statestringOptional

Filter deployments based on their state (BUILDING, ERROR, INITIALIZING, QUEUED, READY, CANCELED, BLOCKED)

rollbackCandidatebooleanOptional

Filter deployments based on their rollback candidacy

branchstringOptional

Filter deployments based on the branch name

shastringOptional

Filter deployments based on the SHA

teamIdstringOptional

The Team identifier to perform the request on behalf of.

slugstringOptional

The Team slug to perform the request on behalf of.

Response

200Success

deploymentsarrayRequired

paginationobjectRequired

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.

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

422Error

Cross-link map: List deployments (/docs/rest-api/deployments/list-deployments)

From the Vercel docs graph (built 2026-10-05T05:39:47.698Z), spanning vercel.com docs + KB, nextjs.org, ai-sdk.dev, and other Vercel documentation sites. Full graph as JSON: https://vercel.com/docs/graph.json

Semantically closest pages

Get deployment events — GET /v3/deployments/{idOrUrl}/events — Get the build logs of a deployment by deployment ID and build ID. It can work as
List Deployment Files — GET /v6/deployments/{id}/files — Allows to retrieve the file structure of the source code of a deployment by supplying t
List check runs for a deployment — GET /v2/deployments/{deploymentId}/check-runs — List all check runs for a deployment.
Delete a Deployment — DELETE /v13/deployments/{id} — This API allows you to delete a deployment, either by supplying its \id\\ in the URL or
Get microfrontends config for a deployment — GET /v1/microfrontends/{deploymentId}/config — Get the microfrontends config for a deployment.

This page links to (1)

Vercel REST API Reference — Interact programmatically with your Vercel account using the SDK or direct HTTP requests.

Pages that link here (3)

By site: vercel-docs (3)

Access tokens — Create and scope Vercel access tokens to your full account, a team, or a single project, then use them to authenticate A
Multi-Project Platforms Reference — API reference, error codes, troubleshooting, and FAQ for multi-project platforms on Vercel.
Vercel REST API Reference — Interact programmatically with your Vercel account using the SDK or direct HTTP requests.

https://api.vercel.com/v7/deployments

const response = await fetch('https://api.vercel.com/v7/deployments?app=string&from=123&limit=123&projectId=string&projectIds=[]&target=string&to=123&users=string&since=123&until=123&state=string&rollbackCandidate=true&branch=string&sha=string&teamId=string&slug=string', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json',
  },
});

const data = await response.json();
console.log(data);

Response

{
  "deployments": [
    {
      "aliasAssigned": "123",
      "aliasError": {
        "code": "string",
        "message": "string"
      },
      "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"
        }
      },
      "buildingAt": "1609492210000",
      "checks": {
        "deployment-alias": {
          "completedAt": "123",
          "startedAt": "123",
          "state": "failed"
        }
      },
      "checksConclusion": "canceled",
      "checksState": "completed",
      "connectBuildsEnabled": "false",
      "connectConfigurationId": "example_id",
      "created": "1609492210000",
      "createdAt": "123",
      "creator": {
        "email": "example@example.com",
        "githubLogin": "johndoe",
        "gitlabLogin": "johndoe",
        "type": "app",
        "uid": "eLrCnEgbKhsHyfbiNR7E8496",
        "username": "johndoe"
      },
      "customEnvironment": {
        "id": "icfg_1234567890",
        "slug": "string"
      },
      "defaultRoute": "/docs",
      "deleted": "1609492210000",
      "errorCode": "BUILD_FAILED",
      "errorMessage": "The Deployment has been canceled because this project was not affected",
      "expiration": "123",
      "inspectorUrl": "https://vercel.com/acme/nextjs/J1hXN00qjUeoYfpEEf7dnDtpSiVq",
      "isRollbackCandidate": "false",
      "manualProvisioning": {
        "completedAt": "123",
        "state": "COMPLETE"
      },
      "meta": "value",
      "name": "docs",
      "oomReport": "out-of-memory",
      "passiveConnectConfigurationId": "example_id",
      "platform": {
        "creator": {
          "avatar": "string",
          "name": "Example Name"
        },
        "meta": "value",
        "origin": {
          "type": "id",
          "value": "string"
        },
        "source": {
          "name": "Example Name"
        }
      },
      "prebuilt": "false",
      "projectId": "example_id",
      "projectSettings": {
        "buildCommand": "string",
        "commandForIgnoringBuildStep": "string",
        "createdAt": "123",
        "customerSupportCodeVisibility": "false",
        "devCommand": "string",
        "framework": "actix-web",
        "gitComments": {
          "onCommit": "false",
          "onPullRequest": "false"
        },
        "gitForkProtection": "false",
        "gitLFS": "false",
        "installCommand": "string",
        "nodeVersion": "10.x",
        "outputDirectory": "string",
        "rootDirectory": "string",
        "skipGitConnectDuringLink": "false",
        "sourceFilesOutsideRootDirectory": "false",
        "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"
        }
      },
      "proposedExpiration": "123",
      "ready": "1609492210000",
      "readyState": "BLOCKED",
      "readySubstate": "PROMOTED",
      "seatBlock": {
        "blockCode": "COMMIT_AUTHOR_REQUIRED",
        "gitProvider": "bitbucket",
        "gitUserId": "example_id",
        "isVerified": "false",
        "userId": "example_id"
      },
      "softDeletedByRetention": "true",
      "source": "cli",
      "state": "READY",
      "target": "production",
      "type": "LAMBDAS",
      "uid": "dpl_2euZBFqxYdDMDG1jTrHFnNZ2eUVa",
      "undeleted": "1609492210000",
      "url": "docs-9jaeg38me.vercel.app"
    }
  ],
  "pagination": {
    "count": "20",
    "next": "1540095775951",
    "prev": "1540095775951"
  }
}

OpenAPI Specification