---
title: "Get environment"
method: POST
path: "/v2/environments.getEnvironment"
tags: ["environments"]
---

# Get environment

`POST /v2/environments.getEnvironment`

Retrieve a single environment by its id.

Use this to fetch environment details after creation or to verify an environment exists before performing operations.

**Required Permissions**

Your root key must have one of the following permissions:
- `environment.*.read_environment` (to read any environment)
- `environment.<environment_id>.read_environment` (to read a specific environment)

## Request body

- V2EnvironmentsGetEnvironmentRequestBody
  - `project` string, required — Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
  - `app` string, required — Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
  - `environment` string, required — Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.

## Response `200`

Successfully retrieved the environment.

- V2EnvironmentsGetEnvironmentResponseBody
  - `meta` Meta, required — Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The `requestId` is particularly important when troubleshooting issues with the Unkey support team.
    - `requestId` string, required — A unique id for this request. Always include this ID when contacting support about a specific API request. This identifier allows Unkey's support team to trace the exact request through logs and diagnostic systems to provide faster assistance.
  - `data` Environment, required
    - `id` string, required — The unique identifier of the environment, generated by Unkey.
    - `slug` string, required — Human-readable slug of the environment, unique within its app.
    - `description` string, required — Human-readable description of this environment. Empty string if none was provided.
    - `kind` 'production' | 'preview', required — The deployment lifecycle role of an environment. - `production`: Deployments serve production traffic, support promotion and rollback, and cannot be stopped. - `preview`: Deployments can be stopped and started and are eligible for preview lifecycle automation.
    - `deleteProtection` boolean, required — Whether delete protection is enabled for this environment. When true, the environment cannot be deleted until protection is disabled.
    - `createdAt` integer, required — Unix timestamp in milliseconds when the environment was created.
    - `updatedAt` integer — Unix timestamp in milliseconds when the environment was last updated. Omitted if the environment has never been updated.
    - `runtime` EnvironmentRuntime — Runtime settings that control how the container runs. Omitted until the environment has runtime settings.
      - `port` integer, required — Port the container listens on.
      - `vCpus` number, double, required — CPU allocation in vCPUs (1 = one vCPU, 0.5 = half a vCPU).
      - `memoryMib` integer, required — Memory allocation in mebibytes.
      - `storageMib` integer, required — Ephemeral storage allocation in mebibytes.
      - `command` string[], required — Container entrypoint command override.
      - `healthcheck` EnvironmentHealthcheck
        - `method` 'GET' | 'POST', required — HTTP method used to probe the container.
        - `path` string, required — HTTP path probed on the container. Must start with a slash.
        - `intervalSeconds` integer — How often the probe runs, in seconds. Defaults to 10 when omitted.
        - `timeoutSeconds` integer — Per-probe timeout, in seconds. Defaults to 5 when omitted.
        - `failureThreshold` integer — Consecutive failures before the container is restarted. Defaults to 3 when omitted.
        - `initialDelaySeconds` integer — Delay before the first probe runs, in seconds. Defaults to 0 when omitted.
      - `shutdownSignal` 'SIGTERM' | 'SIGINT' | 'SIGQUIT' | 'SIGKILL', required — Signal sent to the container on shutdown.
      - `upstreamProtocol` 'http1' | 'h2c', required — Protocol used to reach the container.
      - `openapiSpecPath` string — Path to the OpenAPI spec served by the container, if any.
    - `build` EnvironmentBuild — Build settings that control how the app is built. Omitted until the environment has build settings.
      - `dockerfile` string — Path to the Dockerfile used to build the app, if any.
      - `rootDirectory` string, required — The directory the app is built from. "." for the repository root.
      - `buildCommand` string — Overrides the build command auto-detected by Railpack, so monorepos can scope the build to a single app. Omitted when left to auto-detection or for Dockerfile builds.
      - `watchPaths` string[], required — Paths that trigger a rebuild when changed.
      - `autoDeploy` boolean, required — Whether pushes automatically trigger a deployment.
    - `regions` EnvironmentRegion[] — Per-region deployment settings for this environment. Empty until regional settings are configured.
      - `name` string, required — Region name, such as us-east-1.
      - `replicas` Replicas, required — Min and max replica bounds for autoscaling in a region.
        - `min` integer, required — Minimum number of replicas.
        - `max` integer, required — Maximum number of replicas.

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `403` — Forbidden - Insufficient permissions (requires `environment.*.read_environment`)
- `404` — Not Found - The requested environment does not exist in your workspace
- `429` — Too Many Requests
- `500` — Internal server error

---

[API](https://skmtc.net/unkeyed/apis/unkey-api.md) · [All operations](https://skmtc.net/unkeyed/apis/unkey-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/unkeyed/unkey-api/versions/fa78aafac89c/schema)