---
title: get-an-alias
product: vercel
url: /docs/rest-api/aliases/get-an-alias
type: reference
prerequisites:
  []
related:
  - /docs/rest-api
summary: Learn about get-an-alias on Vercel.
install_vercel_plugin: npx plugins add vercel/vercel-plugin
---

# Get an Alias

```http
GET /v4/aliases/{idOrAlias}
```

Retrieves an Alias for the given host name or alias ID.

## Authentication

**bearerToken**: HTTP bearer

## Path parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `idOrAlias` | string | Yes | The alias or alias ID to be retrieved |


## Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `from` | number | No | Get the alias only if it was created after the provided timestamp |
| `projectId` | string | No | Get the alias only if it is assigned to the provided project ID |
| `since` | number | No | Get the alias only if it was created after this JavaScript timestamp |
| `until` | number | No | Get the alias only if it was created before this JavaScript timestamp |
| `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: The alias information

Content-Type: `application/json`

```json
{
  "type": "object",
  "required": [
    "alias",
    "created",
    "deploymentId",
    "projectId",
    "uid"
  ],
  "properties": {
    "alias": {
      "type": "string",
      "description": "The alias name, it could be a `.vercel.app` subdomain or a custom domain"
    },
    "created": {
      "type": "string",
      "description": "The date when the alias was created",
      "format": "date-time"
    },
    "createdAt": {
      "type": "number",
      "description": "The date when the alias was created in milliseconds since the UNIX epoch",
      "nullable": true
    },
    "creator": {
      "type": "object",
      "description": "Information of the user who created the alias",
      "required": [
        "email",
        "uid",
        "username"
      ],
      "properties": {
        "uid": {
          "type": "string",
          "description": "ID of the user who created the alias"
        },
        "email": {
          "type": "string",
          "description": "Email of the user who created the alias"
        },
        "username": {
          "type": "string",
          "description": "Username of the user who created the alias"
        }
      }
    },
    "deletedAt": {
      "type": "number",
      "description": "The date when the alias was deleted in milliseconds since the UNIX epoch",
      "nullable": true
    },
    "deployment": {
      "type": "object",
      "description": "A map with the deployment ID, URL and metadata",
      "required": [
        "id",
        "url"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "The deployment unique identifier"
        },
        "url": {
          "type": "string",
          "description": "The deployment unique URL"
        },
        "meta": {
          "type": "string",
          "description": "The deployment metadata"
        }
      }
    },
    "deploymentId": {
      "type": "string",
      "description": "The deployment ID",
      "nullable": true
    },
    "projectId": {
      "type": "string",
      "description": "The unique identifier of the project",
      "nullable": true
    },
    "redirect": {
      "type": "string",
      "description": "Target destination domain for redirect when the alias is a redirect",
      "nullable": true
    },
    "redirectStatusCode": {
      "type": "number",
      "description": "Status code to be used on redirect",
      "enum": [
        301,
        302,
        307,
        308
      ],
      "nullable": true
    },
    "uid": {
      "type": "string",
      "description": "The unique identifier of the alias"
    },
    "updatedAt": {
      "type": "number",
      "description": "The date when the alias was updated in milliseconds since the UNIX epoch",
      "nullable": true
    },
    "protectionBypass": {
      "type": "object",
      "description": "The protection bypass for the alias",
      "additionalProperties": {
        "oneOf": [
          {
            "type": "object",
            "description": "The protection bypass for the alias",
            "required": [
              "createdAt",
              "createdBy",
              "scope"
            ],
            "properties": {
              "createdAt": {
                "type": "number"
              },
              "createdBy": {
                "type": "string"
              },
              "scope": {
                "type": "string",
                "enum": [
                  "shareable-link"
                ]
              },
              "expires": {
                "type": "number"
              }
            }
          },
          {
            "type": "object",
            "description": "The protection bypass for the alias",
            "required": [
              "access",
              "createdAt",
              "lastUpdatedAt",
              "lastUpdatedBy",
              "scope"
            ],
            "properties": {
              "createdAt": {
                "type": "number"
              },
              "lastUpdatedAt": {
                "type": "number"
              },
              "lastUpdatedBy": {
                "type": "string"
              },
              "access": {
                "type": "string",
                "enum": [
                  "requested",
                  "granted"
                ]
              },
              "scope": {
                "type": "string",
                "enum": [
                  "user"
                ]
              }
            }
          },
          {
            "type": "object",
            "description": "The protection bypass for the alias",
            "required": [
              "createdAt",
              "createdBy",
              "scope"
            ],
            "properties": {
              "createdAt": {
                "type": "number"
              },
              "createdBy": {
                "type": "string"
              },
              "scope": {
                "type": "string",
                "enum": [
                  "alias-protection-override"
                ]
              }
            }
          },
          {
            "type": "object",
            "description": "The protection bypass for the alias",
            "required": [
              "createdAt",
              "lastUpdatedAt",
              "lastUpdatedBy",
              "scope"
            ],
            "properties": {
              "createdAt": {
                "type": "number"
              },
              "lastUpdatedAt": {
                "type": "number"
              },
              "lastUpdatedBy": {
                "type": "string"
              },
              "scope": {
                "type": "string",
                "enum": [
                  "email_invite"
                ]
              }
            }
          }
        ]
      }
    },
    "microfrontends": {
      "type": "object",
      "description": "The microfrontends for the alias including the routing configuration",
      "required": [
        "applications",
        "defaultApp"
      ],
      "properties": {
        "defaultApp": {
          "type": "object",
          "required": [
            "projectId"
          ],
          "properties": {
            "projectId": {
              "type": "string"
            }
          }
        },
        "applications": {
          "oneOf": [
            {
              "type": "array",
              "description": "A list of the deployment routing information for each project.",
              "items": {
                "type": "object",
                "description": "A list of the deployment routing information for each project.",
                "required": [
                  "fallbackHost",
                  "projectId"
                ],
                "properties": {
                  "fallbackHost": {
                    "type": "string",
                    "description": "This is always set. In production it is used as a pointer to each apps production deployment. For pre-production, it's used as the fallback if there is no deployment for the branch."
                  },
                  "projectId": {
                    "type": "string",
                    "description": "The project ID of the microfrontends application."
                  }
                }
              }
            },
            {
              "type": "array",
              "description": "A list of the deployment routing information for each project.",
              "items": {
                "type": "object",
                "description": "A list of the deployment routing information for each project.",
                "required": [
                  "branchAlias",
                  "fallbackHost",
                  "projectId"
                ],
                "properties": {
                  "fallbackHost": {
                    "type": "string",
                    "description": "This is always set. For branch aliases, it's used as the fallback if there is no deployment for the branch."
                  },
                  "branchAlias": {
                    "type": "string",
                    "description": "Could point to a branch without a deployment if the project was never deployed. The proxy will fallback to the fallbackHost if there is no deployment."
                  },
                  "projectId": {
                    "type": "string",
                    "description": "The project ID of the microfrontends application."
                  }
                }
              }
            },
            {
              "type": "array",
              "description": "A list of the deployment routing information for each project.",
              "items": {
                "type": "object",
                "description": "A list of the deployment routing information for each project.",
                "required": [
                  "projectId"
                ],
                "properties": {
                  "deploymentId": {
                    "type": "string",
                    "description": "This is the deployment for the same commit, it could be a cancelled deployment. The proxy will fallback to the branchDeploymentId and then the fallbackDeploymentId."
                  },
                  "branchDeploymentId": {
                    "type": "string",
                    "description": "This is the latest non-cancelled deployment of the branch alias at the time the commit alias was created. It is possible there is no deployment for the branch, or this was set before the deployment was canceled, in which case this will point to a cancelled deployment, in either case the proxy will fallback to the fallbackDeploymentId."
                  },
                  "fallbackDeploymentId": {
                    "type": "string",
                    "description": "This is the deployment of the fallback host at the time the commit alias was created. It is possible for this to be a deleted deployment, in which case the proxy will show that the deployment is deleted. It will not use the fallbackHost, as a future deployment on the fallback host could be invalid for this deployment, and it could lead to confusion / incorrect behavior for the commit alias."
                  },
                  "fallbackHost": {
                    "type": "string",
                    "description": "Temporary for backwards compatibility. Can remove when metadata change is released"
                  },
                  "branchAlias": {
                    "type": "string"
                  },
                  "projectId": {
                    "type": "string",
                    "description": "The project ID of the microfrontends application."
                  }
                }
              }
            }
          ]
        }
      }
    }
  }
}
```

### 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.

### 404: The alias was not found

---

## Related

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

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

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

---

[View full sitemap](/docs/sitemap)