---
title: list-connectors
product: vercel
url: /docs/rest-api/connect/list-connectors
canonical_url: "https://vercel.com/docs/rest-api/connect/list-connectors"
last_updated: 2026-09-02
type: reference
prerequisites:
  []
related:
  - /docs/rest-api
summary: Learn about list-connectors on Vercel.
install_vercel_plugin: npx plugins add vercel/vercel-plugin
---

# List connectors

```http
GET /v2/connect/connectors
```

List connectors that belong to a team.

## Authentication

**bearerToken**: HTTP bearer

## Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `limit` | integer. min: 1; max: 100 | No | Maximum number of connectors to return. Defaults to 20. |
| `cursor` | string | No | Cursor from `pagination.next` on the previous response. |
| `projectId` | string | No | Return only connectors connected to this project. |
| `search` | string. maxLength: 100 | No | Search connector names, UIDs, and services. |
| `type` | string | No | Comma-separated connector types: `slack`, `discord`, `github`, `linear`, `linq`, `salesforce`, `sendblue`, `snowflake`, `snowflake-wif`, `microsoft-entra`, `api-key`, `photon`, `oauth`, or `custom`. |
| `service` | string | No | Comma-separated provider or service identifiers. |
| `sort` | string. enum: name, createdAt, updatedAt | No | Sort by name in ascending order, or by creation or update time in descending order. |
| `teamId` | string | No | The team ID that scopes the request. Do not send it with slug. If both are omitted, Vercel uses the team associated with the token or the authenticated user's default team. The request returns 401 if no team can be selected. |
| `slug` | string | No | The team slug that scopes the request. Do not send it with teamId. If both are omitted, Vercel uses the team associated with the token or the authenticated user's default team. The request returns 401 if no team can be selected. |


## Example request

### TypeScript

```typescript
const response = await fetch('https://api.vercel.com/v2/connect/connectors?limit=123&cursor=string&projectId=string&search=string&type=string&service=string&sort=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);
```

### Next.js

```typescript
'use server';

export async function callEndpoint() {
  const response = await fetch('https://api.vercel.com/v2/connect/connectors?limit=123&cursor=string&projectId=string&search=string&type=string&service=string&sort=string&teamId=string&slug=string', {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${process.env.VERCEL_ACCESS_TOKEN}`,
      'Content-Type': 'application/json',
    },
    next: { revalidate: 3600 }
  });

  if (!response.ok) {
    throw new Error('Request failed');
  }

  return response.json();
}
```

### cURL

```bash
curl -X GET 'https://api.vercel.com/v2/connect/connectors?limit=123&cursor=string&projectId=string&search=string&type=string&service=string&sort=string&teamId=string&slug=string' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json'
```

## Example response

```json
{
  "connectors": [
    {
      "id": "icfg_1234567890",
      "uid": "example_id",
      "defaultInstallationId": "example_id",
      "createdAt": "123",
      "updatedAt": "123",
      "reinstallAt": "123",
      "createdBy": {
        "type": "user",
        "id": "icfg_1234567890"
      },
      "updatedBy": {
        "type": "user",
        "id": "icfg_1234567890"
      },
      "creationMode": "managed",
      "managed": {
        "sync": "false"
      },
      "type": "api-key",
      "service": "string",
      "connectionMethod": "string",
      "target": "string",
      "name": "Example Name",
      "displayName": "Example Name",
      "clientUrl": "https://example.com",
      "redirectUri": "https://example.com",
      "typeName": "Example Name",
      "typeIcon": "string",
      "website": "string",
      "devsite": "string",
      "docsite": "string",
      "icon": "string",
      "backgroundColor": "string",
      "accentColor": "string",
      "supportedSubjectTypes": [],
      "appTokens": {
        "crossInstallation": "false",
        "supportsRefinement": "false",
        "requiresReinstallation": "false",
        "scopes": [],
        "supportedAuthorizationDetails": [],
        "permissionsUrl": "https://example.com"
      },
      "userTokens": {
        "crossInstallation": "false",
        "supportsRefinement": "false",
        "scopes": [],
        "supportedAuthorizationDetails": [],
        "manualCredentialInput": "false"
      },
      "supportsInstallation": "false",
      "supportsRevocation": "false",
      "supportsTriggers": "false",
      "supportsIcon": "false",
      "triggers": {
        "enabled": "false"
      },
      "events": [],
      "triggerDestinations": [
        {
          "projectId": "example_id",
          "customEnvironmentId": "example_id",
          "branch": "string",
          "path": "string"
        }
      ]
    }
  ],
  "pagination": {
    "next": "string"
  }
}
```

## Responses

### 200: A page of connectors.

Content-Type: `application/json`

```json
{
  "type": "object",
  "description": "Page of connectors.",
  "required": [
    "connectors",
    "pagination"
  ],
  "properties": {
    "connectors": {
      "type": "array",
      "description": "Connectors in this page.",
      "items": {
        "type": "object",
        "description": "A connector that defines how Vercel accesses an external service.",
        "required": [
          "createdAt",
          "displayName",
          "id",
          "name",
          "service",
          "supportedSubjectTypes",
          "supportsIcon",
          "supportsInstallation",
          "supportsRevocation",
          "supportsTriggers",
          "type",
          "typeName",
          "uid",
          "updatedAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Stable `scl_` connector ID. Use this value directly in `{connector}`."
          },
          "uid": {
            "type": "string",
            "description": "Team-scoped UID. URL-encode this value before using it in `{connector}`."
          },
          "defaultInstallationId": {
            "type": "string",
            "description": "Installation used when a token request does not specify an installation."
          },
          "createdAt": {
            "type": "number",
            "description": "Creation time in epoch milliseconds."
          },
          "updatedAt": {
            "type": "number",
            "description": "Last update time in epoch milliseconds."
          },
          "reinstallAt": {
            "type": "number",
            "description": "Time when this connector started requiring reinstallation because an installation-affecting app-token grant changed."
          },
          "createdBy": {
            "description": "Principal that created the connector."
          },
          "updatedBy": {
            "description": "Principal that most recently updated the connector."
          },
          "creationMode": {
            "type": "string",
            "description": "How the connector row was originally created. New create paths stamp this explicitly; older rows may omit it.",
            "enum": [
              "managed",
              "manual"
            ]
          },
          "managed": {
            "type": "object",
            "description": "Managed connector metadata exposed without leaking the manager connector or installation identifiers."
          },
          "type": {
            "type": "string",
            "description": "Connector implementation type.",
            "enum": [
              "api-key",
              "custom",
              "discord",
              "github",
              "linear",
              "linq",
              "microsoft-entra",
              "microsoft-teams",
              "oauth",
              "photon",
              "salesforce",
              "sendblue",
              "slack",
              "snowflake",
              "snowflake-wif"
            ]
          },
          "service": {
            "type": "string",
            "description": "Best-effort identifier of the third-party service this connector represents, independent of `type`. Examples: `'slack'`, `'mcp.linear.app'`, and `'auth.example.com'`. Always present in API responses."
          },
          "connectionMethod": {
            "type": "string",
            "description": "The connection method this connector was created from, when the create request named one."
          },
          "target": {
            "type": "string",
            "description": "Which of the service's products/surfaces this connector points at."
          },
          "name": {
            "type": "string",
            "description": "Connector name within the owning team."
          },
          "displayName": {
            "type": "string",
            "description": "Human-readable connector name."
          },
          "clientUrl": {
            "type": "string",
            "description": "Provider-side URL for viewing or managing the resource represented by the connector. The destination can be an app, account, phone line, or service instance, depending on the connector type.",
            "nullable": true
          },
          "redirectUri": {
            "type": "string",
            "description": "Redirect URI registered with the third-party service for this connector, if any. Used by `startAuthorization`/`startInstallation` to replay the exact URI back to the provider's token endpoint. Absent on connectors created before this field was introduced; those callers fall back to the `https://connect.vercel.com/callback` default."
          },
          "typeName": {
            "type": "string",
            "description": "Human-readable name of the connector type."
          },
          "typeIcon": {
            "type": "string",
            "description": "Icon identifier supplied by the connector type."
          },
          "website": {
            "type": "string",
            "description": "Public website for the connected service."
          },
          "devsite": {
            "type": "string",
            "description": "Developer website for the connected service."
          },
          "docsite": {
            "type": "string",
            "description": "Developer documentation for the connected service."
          },
          "icon": {
            "type": "string",
            "description": "Connector branding icon. SHA-1 hash that resolves to the uploaded icon through the Vercel avatar service. Consumers render this with `https://vercel.com/api/www/avatar/{icon}`."
          },
          "backgroundColor": {
            "type": "string",
            "description": "Hex background color (e.g., `#000000`) for branding."
          },
          "accentColor": {
            "type": "string",
            "description": "Hex accent color (e.g., `#000000`) for branding."
          },
          "supportedSubjectTypes": {
            "type": "array",
            "description": "Token subject types supported by the connector."
          },
          "appTokens": {
            "type": "object",
            "description": "App-token capabilities and known grants for the connector.",
            "required": [
              "crossInstallation",
              "supportsRefinement"
            ]
          },
          "userTokens": {
            "type": "object",
            "description": "User-token capabilities and known grants for the connector.",
            "required": [
              "crossInstallation",
              "supportsRefinement"
            ]
          },
          "supportsInstallation": {
            "type": "boolean",
            "description": "Whether the connector supports an installation flow.",
            "enum": [
              false,
              true
            ]
          },
          "supportsRevocation": {
            "type": "boolean",
            "description": "Whether Connect can revoke tokens for this connector.",
            "enum": [
              false,
              true
            ]
          },
          "supportsTriggers": {
            "type": "boolean",
            "description": "Whether this connector type supports trigger webhooks. Derived from the type definition; indicates that `triggers` and `triggerDestinations` may be meaningful for this connector.",
            "enum": [
              false,
              true
            ]
          },
          "supportsIcon": {
            "description": "Whether the connector icon can propagate to the provider.",
            "enum": [
              false,
              "maybe",
              true
            ]
          },
          "triggers": {
            "type": "object",
            "description": "Incoming trigger configuration. Only present when enabled.",
            "required": [
              "enabled"
            ]
          },
          "events": {
            "type": "array",
            "description": "Known events this connector subscribes to (e.g. Slack bot events, GitHub webhook events). Names are type-specific and validated by the managed-create flow when forwarded to the third-party service."
          },
          "triggerDestinations": {
            "type": "array",
            "description": "Destinations that incoming triggers should be forwarded to. Limited to 3 entries. Set the initial destination with `triggerDestination` during creation. Replace the complete set with `PATCH /v1/connect/connectors/{connector}/trigger-destinations`."
          }
        }
      }
    },
    "pagination": {
      "type": "object",
      "description": "Cursor for the next page.",
      "required": [
        "next"
      ],
      "properties": {
        "next": {
          "type": "string",
          "description": "Opaque value to pass as `cursor` on the next request.",
          "nullable": true
        }
      }
    }
  }
}
```

### 400: One of the provided values in the request query is invalid.

Content-Type: `application/json`

```json
{
  "type": "object",
  "description": "Error response returned by a Connect API operation.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "object",
      "description": "Error details.",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string",
          "description": "Stable machine-readable error code."
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message."
        }
      },
      "additionalProperties": true
    }
  }
}
```

### 401: The request is not authorized.

Content-Type: `application/json`

```json
{
  "type": "object",
  "description": "Error response returned by a Connect API operation.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "object",
      "description": "Error details.",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string",
          "description": "Stable machine-readable error code."
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message."
        }
      },
      "additionalProperties": true
    }
  }
}
```

### 403: You do not have permission to access this resource.

Content-Type: `application/json`

```json
{
  "type": "object",
  "description": "Error response returned by a Connect API operation.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "object",
      "description": "Error details.",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string",
          "description": "Stable machine-readable error code."
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message."
        }
      },
      "additionalProperties": true
    }
  }
}
```

### 410: The requested resource is no longer available.

Content-Type: `application/json`

```json
{
  "type": "object",
  "description": "Error response returned by a Connect API operation.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "object",
      "description": "Error details.",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string",
          "description": "Stable machine-readable error code."
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message."
        }
      },
      "additionalProperties": true
    }
  }
}
```

### 422: The request cannot be completed in the current state.

Content-Type: `application/json`

```json
{
  "type": "object",
  "description": "Error response returned by a Connect API operation.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "object",
      "description": "Error details.",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string",
          "description": "Stable machine-readable error code."
        },
        "message": {
          "type": "string",
          "description": "Human-readable error message."
        }
      },
      "additionalProperties": true
    }
  }
}
```

---

## Related

- [connect endpoints](/docs/rest-api#connect)

- [REST API overview](/docs/rest-api)

- [OpenAPI spec](https://openapi.vercel.sh/) (machine-readable, all endpoints)

---

[View full sitemap](/docs/sitemap)