---
title: "Vercel Deployments"
canonical_url: "https://docs.getdx.com/connectors/vercel-deployments/"
md_url: "https://docs.getdx.com/connectors/vercel-deployments.md"
last_updated: "2026-08-19"
---
# Vercel Deployments
By enabling the Vercel Deployments connector, you can import production deployment events from Vercel and track **Deploy frequency**. In combination with your source control connectors, this enables reports about the relationship between deployments and opened or merged pull requests. See the API documentation below and the [schema explorer](https://docs.getdx.com/schema/) for the data DX imports. DX does not read or access your source code.
Use this connector when Vercel is the system of record for your production releases. **For custom workflows, monorepos, or deployment systems outside Vercel, use [`deployments.create`](https://docs.getdx.com/datacloudapi/methods/deployments.create/) instead.**
Vercel Deployments creates catalog services from the git repository each Vercel project deploys. If several Vercel projects deploy the same repository, or repositories with the same name exist across git organizations, review your catalog after the first import to confirm services were created as expected.
## Prerequisites
To connect Vercel to DX, you need:
- a Vercel account token scoped to the account and teams whose deployments you want DX to import
- membership in at least one Vercel team; the connector syncs teams, so a token with no readable teams cannot be verified
- Vercel projects linked to a git repository, since DX attributes deployments to services using the linked repository
## What DX imports
- **Teams:** every team the token can read. Teams that stop being returned by the API are marked inaccessible rather than deleted.
- **Projects:** every project in those teams, including the linked git repository, git provider, production branch, and detected framework.
- **Deployments:** deployments that target the Vercel **production** environment. Preview deployments are not imported.
DX promotes a Vercel deployment into a unified `deployments` record when all of the following are true:
- the deployment targeted the production environment
- the deployment reached Vercel's `READY` state
- the deployment has a commit SHA, which means CLI deploys without git metadata are imported but not promoted
- the project it belongs to is linked to a git repository
Deployments that are still building when an import runs are re-checked on later imports until they reach a terminal state. If a deployment no longer exists in Vercel, DX marks its state as `abandoned`.
## Setup instructions
Follow the steps below to connect Vercel to DX.
#### Step 1
In Vercel, create an account token:
- Browse to [https://vercel.com/account/tokens](https://vercel.com/account/tokens).
- Under **Create Token**, enter a **Token Name**. We recommend **DX - Deployments** so it is easy to identify later.
- Set **Scope** to cover the account and every Vercel team whose deployments you want DX to import. DX only imports deployments for teams the token can read, so any team left out of the scope produces no deployment data.
- Choose an **Expiration**. DX connections stop importing when the token expires, so prefer the longest expiration your policies allow and plan to rotate the token before that date.
- Click **Create** and copy the token. Vercel only shows it once.
{class="max-w-xl mx-auto"}
#### Step 2
- Navigate to the connections page in DX and select **+ Connection** in the top right.
- Select **Vercel** and paste your API token.
#### Step 3
Optionally, add more credentials to the connection to spread imports across multiple Vercel tokens and reduce rate limiting. Every credential on the connection must be able to read the same number of Vercel teams; DX rejects a credential whose team access does not match the existing credentials.
## API reference
The table below lists the specific API endpoints that are used by DX.
| Endpoint | Documentation |
|----------|---------------|
| `/v2/teams` | [List all teams](https://vercel.com/docs/rest-api/reference/endpoints/teams/list-all-teams) |
| `/v10/projects` | [Retrieve a list of projects](https://vercel.com/docs/rest-api/reference/endpoints/projects/retrieve-a-list-of-projects) |
| `/v7/deployments` | [List deployments](https://vercel.com/docs/rest-api/reference/endpoints/deployments/list-deployments) |
| `/v13/deployments/{idOrUrl}` | [Get a deployment by ID or URL](https://vercel.com/docs/rest-api/reference/endpoints/deployments/get-a-deployment-by-id-or-url) |
## Errors
The table below lists potential error codes when adding a connection in DX.
| Error | Description |
|----------------------|------------------------------------------------------------------------------------------------------------------|
| `invalid_credentials` | Your API token is not valid or has expired. Create a new token on Vercel's [Account Tokens](https://vercel.com/account/tokens) page. |
| `invalid_permissions` | Your API token cannot list its teams, read projects, or read deployments. Confirm the token's scope includes the teams you want DX to import. |
| `no_resources` | Your API token has access to no readable teams, or the teams it can read contain no projects. |
## Curl commands
#### When connection verification fails
DX verifies a Vercel connection in three steps: listing teams, reading projects for the first team, and reading recent production deployments for that team. If your connection is failing, run the commands below with `YOUR_API_TOKEN` replaced to see which step Vercel rejects.
#### Step 1: List teams
An empty `teams` array means the token belongs to no readable teams, which DX reports as `no_resources`. A `403` means the token's scope does not allow it to list teams.
#### Step 2: List projects for a team
Use a team ID returned in Step 1:
A `403` or `404` here means the token can read the team's projects but not its deployments.
## Data Cloud API
Once the initial connection is created successfully, Vercel credentials can be managed via the Data Cloud API.
- [credentials.create](https://docs.getdx.com/datacloudapi/methods/credentials.create/)
- [credentials.update](https://docs.getdx.com/datacloudapi/methods/credentials.update/)
- [credentials.info](https://docs.getdx.com/datacloudapi/methods/credentials.info/)
- [credentials.list](https://docs.getdx.com/datacloudapi/methods/credentials.list/)
- [credentials.delete](https://docs.getdx.com/datacloudapi/methods/credentials.delete/)
### Credential fields
| Field | Type | Description |
| ----- | ---- | ----------- |
| `secrets.api_token` | `String` | A Vercel account token scoped to the teams whose deployments DX should import. |
```json
{
"id": 456,
"secrets": {
"api_token": "your_vercel_api_token"
}
}
```
---
## Sitemap
[Overview of all docs pages](/llms.txt)