---
title: retrieve-custom-environments
product: vercel
url: /docs/rest-api/environment/retrieve-custom-environments
type: reference
prerequisites:
  []
related:
  - /docs/rest-api
summary: Learn about retrieve-custom-environments on Vercel.
install_vercel_plugin: npx plugins add vercel/vercel-plugin
---

# Retrieve custom environments

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

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

## Authentication

**bearerToken**: HTTP bearer

## Path parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `idOrName` | string | Yes | The unique project identifier or the project name |


## Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `gitBranch` | string | No | Fetch custom environments for a specific git branch |
| `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": [
    "accountLimit",
    "environments"
  ],
  "properties": {
    "accountLimit": {
      "type": "object",
      "description": "The maximum number of custom environments allowed either by the team's plan type or a custom override.",
      "required": [
        "total"
      ],
      "properties": {
        "total": {
          "type": "number"
        }
      }
    },
    "environments": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "createdAt",
          "id",
          "slug",
          "type",
          "updatedAt"
        ],
        "properties": {
          "type": {
            "type": "string",
            "description": "The type of environment (production, preview, or development)",
            "enum": [
              "production",
              "preview",
              "development"
            ]
          },
          "description": {
            "type": "string",
            "description": "Optional description of the environment's purpose"
          },
          "createdAt": {
            "type": "number",
            "description": "Timestamp when the environment was created"
          },
          "updatedAt": {
            "type": "number",
            "description": "Timestamp when the environment was last updated"
          },
          "id": {
            "type": "string",
            "description": "Unique identifier for the custom environment (format: env_*)"
          },
          "slug": {
            "type": "string",
            "description": "URL-friendly name of the environment"
          },
          "domains": {
            "type": "array",
            "description": "List of domains associated with this environment",
            "items": {
              "type": "object",
              "description": "List of domains associated with this environment",
              "required": [
                "apexName",
                "name",
                "projectId",
                "verified"
              ],
              "properties": {
                "name": {
                  "type": "string"
                },
                "apexName": {
                  "type": "string"
                },
                "projectId": {
                  "type": "string"
                },
                "redirect": {
                  "type": "string",
                  "nullable": true
                },
                "redirectStatusCode": {
                  "type": "number",
                  "enum": [
                    301,
                    302,
                    307,
                    308
                  ],
                  "nullable": true
                },
                "gitBranch": {
                  "type": "string",
                  "nullable": true
                },
                "customEnvironmentId": {
                  "type": "string",
                  "nullable": true
                },
                "updatedAt": {
                  "type": "number"
                },
                "createdAt": {
                  "type": "number"
                },
                "verified": {
                  "type": "boolean",
                  "description": "`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.",
                  "enum": [
                    false,
                    true
                  ]
                },
                "verification": {
                  "type": "array",
                  "description": "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`.",
                  "items": {
                    "type": "object",
                    "description": "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`.",
                    "required": [
                      "domain",
                      "reason",
                      "type",
                      "value"
                    ],
                    "properties": {
                      "type": {
                        "type": "string"
                      },
                      "domain": {
                        "type": "string"
                      },
                      "value": {
                        "type": "string"
                      },
                      "reason": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "branchMatcher": {
            "type": "object",
            "description": "Configuration for matching git branches to this environment",
            "required": [
              "pattern",
              "type"
            ],
            "properties": {
              "type": {
                "type": "string",
                "description": "The type of matching to perform",
                "enum": [
                  "endsWith",
                  "startsWith",
                  "equals"
                ]
              },
              "pattern": {
                "type": "string",
                "description": "The pattern to match against branch names"
              }
            }
          },
          "currentDeploymentAliases": {
            "type": "array",
            "description": "List of aliases for the current 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.

---

## Related

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

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

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

---

[View full sitemap](/docs/sitemap)