---
title: "Retrieve custom environments"
method: GET
path: "/v9/projects/{idOrName}/custom-environments"
tags: ["environment"]
---

# Retrieve custom environments

`GET /v9/projects/{idOrName}/custom-environments`

Retrieve custom environments for the project. Must not be named 'Production' or 'Preview'.

## Path parameters

- `idOrName` string, required — The unique project identifier or the project name

## Query parameters

- `gitBranch` string — Fetch custom environments for a specific git branch
- `teamId` string
- `slug` string

## Response `200`

- object
  - `accountLimit` object, required — The maximum number of custom environments allowed either by the team's plan type or a custom override.
    - `total` number, required
  - `environments` object[], required
    - `type` 'development' | 'preview' | 'production', required — The type of environment (production, preview, or development)
    - `description` string — Optional description of the environment's purpose
    - `createdAt` number, required — Timestamp when the environment was created
    - `updatedAt` number, required — Timestamp when the environment was last updated
    - `slug` string, required — URL-friendly name of the environment
    - `id` string, required — Unique identifier for the custom environment (format: env_*)
    - `domains` object[] — List of domains associated with this environment
      - `name` string, required
      - `apexName` string, required
      - `projectId` string, required
      - `redirect` string, nullable
      - `redirectStatusCode` 301 | 302 | 307 | 308 | null, nullable
      - `gitBranch` string, nullable
      - `customEnvironmentId` string, nullable
      - `updatedAt` number
      - `createdAt` number
      - `verified` false | true, required — `true` if the domain is verified for use with the project. If `false` it will not be used as an alias on this project until the challenge in `verification` is completed.
      - `verification` object[] — A list of verification challenges, one of which must be completed to verify the domain for use on the project. After the challenge is complete `POST /projects/:idOrName/domains/:domain/verify` to verify the domain. Possible challenges: - If `verification.type = TXT` the `verification.domain` will be checked for a TXT record matching `verification.value`.
        - `type` string, required
        - `domain` string, required
        - `value` string, required
        - `reason` string, required
    - `branchMatcher` object — Configuration for matching git branches to this environment
      - `type` 'endsWith' | 'equals' | 'startsWith', required — The type of matching to perform
      - `pattern` string, required — The pattern to match against branch names
    - `currentDeploymentAliases` string[] — List of aliases for the current 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.
- `410`

---

[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/b4d86a3e3479/schema)