Get Plan Environment List

10 min

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

{
  "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

{
  "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

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