---
title: Get Plan Environment List
slug: suite-documentation/awPC-get-plan-environment-list
docTags: 
createdAt: 2026-08-26T08:40:52.325Z
---

This endpoint returns the environment list assigned to a test plan.

For Appium2 plans, the endpoint returns active DevicePark-style plan environments. Inactive environments are filtered out and are not included in the response.

***

### Endpoint Information

- **URL**: `{gateway-url}/plan-environment/plan/{planId}`
- **Method**: `GET`
- **Authentication**: Required (`Bearer Token`)

### Request Headers

| Header          | Required | Description                                                                 |
| --------------- | -------- | --------------------------------------------------------------------------- |
| `Authorization` | Yes      | Bearer token used for authentication. Example: `Bearer <your_access_token>` |
| `X-Company-Id`  | Yes      | The company ID used by the gateway to authorize and route the request.      |
| `Accept`        | No       | Recommended value: `application/json`.                                      |

### Path Variables

| Parameter | Type | Required | Description              |
| --------- | ---- | -------- | ------------------------ |
| `planId`  | Long | Yes      | The ID of the test plan. |

### Request Body

This endpoint does not require a request body.

### Response Body

```json
{
  "data": [
    {
      "id": 753,
      "platform": "iOS",
      "platformName": null,
      "platformVersion": "18.6.2",
      "model": "iPhone13,2",
      "modelName": null,
      "manufacturer": "Apple",
      "marketName": "iPhone 12",
      "testFrameworkType": "APPIUM2",
      "udid": null,
      "licenceId": null,
      "enabled": null,
      "privateDevice": false
    }
  ]
}
```

### Response Fields

| Field                      | Type             | Description                                                                                            |
| -------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------ |
| `data`                     | Array of objects | List of environments assigned to the plan.                                                             |
| `data[].id`                | Long             | Unique identifier of the plan environment record.                                                      |
| `data[].platform`          | String           | Operating system of the device. Example: `iOS`, `Android`.                                             |
| `data[].platformName`      | String           | Display name of the platform, if available.                                                            |
| `data[].platformVersion`   | String           | Operating system version of the device.                                                                |
| `data[].model`             | String           | Device model identifier. Example: `iPhone13,2`, `SM-A305F`.                                            |
| `data[].modelName`         | String           | Display name of the model, if available.                                                               |
| `data[].manufacturer`      | String           | Device manufacturer. Example: `Apple`, `Samsung`.                                                      |
| `data[].marketName`        | String           | Commercial or user-friendly device name. Example: `iPhone 12`.                                         |
| `data[].testFrameworkType` | String           | Framework type of the plan environment. For Appium2 plans, this value is `APPIUM2`.                    |
| `data[].udid`              | String           | Device UDID, if available. Sensitive values should be masked in public documentation.                  |
| `data[].licenceId`         | Long             | Related licence ID, if available.                                                                      |
| `data[].enabled`           | Boolean          | Environment active status when populated. For Appium2 environments, inactive records are filtered out. |
| `data[].privateDevice`     | Boolean          | Indicates whether the environment belongs to a private device pool.                                    |

### Important Notes

- For Appium2 and Selenium4 plans, this endpoint returns DevicePark-style plan environments.
- For Appium2 plans, only active plan environment records are returned.
- If the plan exists but has no active environments, `data` is returned as an empty array.
- The response does not include `result.code` or `result.message`.

### Error Response Format

```json
{
  "instance": "/plan-environment/plan/999999",
  "status": 404,
  "title": "Not Found",
  "type": "https://errors.testinium.com/exception",
  "timestamp": "2026-08-18T12:08:41.165927056Z",
  "errorType": "EXCEPTION",
  "errors": {
    "code": 10003,
    "message": "Plan with id 999999 not found!"
  }
}
```

### HTTP Error Codes

| HTTP Code | Error Message           | Description                                                                                |
| --------- | ----------------------- | ------------------------------------------------------------------------------------------ |
| `400`     | `Bad Request`           | Path variable is invalid or request could not be processed.                                |
| `401`     | `Unauthorized`          | Authentication is missing or invalid.                                                      |
| `403`     | `Forbidden`             | User does not have permission for this operation or company.                               |
| `404`     | `Not Found`             | Plan was not found, deleted, disabled, or not accessible within the current company scope. |
| `405`     | `Method Not Allowed`    | The endpoint was called with an unsupported HTTP method.                                   |
| `500`     | `Internal Server Error` | An unexpected error occurred on the server side.                                           |
| `503`     | `Service Unavailable`   | Environment service, project service, or another downstream service is unavailable.        |

### Application Error Codes

| Code    | HTTP Status | Source            | Description                                                       |
| ------- | ----------- | ----------------- | ----------------------------------------------------------------- |
| `10003` | `404`       | Project           | Test plan not found.                                              |
| `10001` | `401`       | Gateway           | Authentication is required.                                       |
| `10002` | `401`       | Gateway           | Token is invalid or cannot be verified.                           |
| `10003` | `403`       | Gateway           | Authorization failed for the requested resource.                  |
| `10004` | `400`       | Gateway           | A required header, such as `X-Company-Id`, is missing or invalid. |
| `10008` | `503`       | Gateway           | Routed service is unavailable.                                    |
| `10007` | `503`       | Common            | Downstream service is unavailable.                                |
| `20008` | `400`       | Common Validation | Path variable type is invalid.                                    |
| `20009` | `405`       | Common Validation | HTTP method is not supported.                                     |

### Example Request

```bash
curl --location '{gateway-url}/plan-environment/plan/{planId}' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'X-Company-Id: <company_id>'
```