• Home
  • Dynatrace Managed
  • Cluster API
  • Cluster API v2
  • Environments
  • List all existing environments

List all existing environments

This API call lists all existing environments.

Authentication

To execute this request, you need the Service Provider API (ServiceProviderAPI) permission assigned to your API token. Generate your API token via Cluster Management Console (CMC). To learn how to obtain and use it, see Cluster API - Authentication.

Endpoint

/api/cluster/v2/environments

Parameter

ParameterTypeDescriptionInRequired
nextPageKeystring

The cursor for the next page of results. You can find it in the nextPageKey field of the previous response.

The first page is always returned if you don't specify the nextPageKey query parameter.

When the nextPageKey is set to obtain subsequent pages, you must omit all other query parameters.

queryoptional
pageSizeinteger

The amount of environments in a single response payload.

The maximal allowed page size is 1000.

If not set, 100 is used.

queryoptional
sortstring

The sort order. Possible sorts orders are:

  • 'name' (without quotes): Sort by name ascending.
  • '-name' (without quotes): Sort by name descending.
  • 'creationDate' (without quotes): Sort by creation date ascending.
  • '-creationDate' (without quotes): Sort by name descending.
queryoptional
filterstring

Specifies the filter of the query.

You can set one or several of the following criteria:

  • Name: name(string). The name can be either a substring or the full name of an environment. Case-insensitive.
  • Trial: trial(true) or trial(false). Only includes trial environments if true is specified or only non-trial environments if false is specified.
  • State: state(ENABLED) or state(DISABLED).
  • Tag: tag(string). To filter by multiple tags by applying OR logic use tag(string1,string2). To filter by multiple tags by applying AND logic use tag(string1),tag(string2). To set several criteria, separate them with a comma (,). Only results, matching all criteria, are included into response.
queryoptional
includeConsumptionInfoboolean

If true, consumption information (limits, usage) is returned for each environment.

Returned usage is typically up to 1 hour old. To obtain fresher data, you can use includeUncachedConsumptionInfo parameter instead.

queryoptional
includeStorageInfoboolean

If true, storage information (limits, usage) is returned for each environment.

queryoptional
includeUncachedConsumptionInfoboolean

If true, uncached consumption information (limits, usage) is returned for each environment.

Up to date consumption will be calculated. Calculation may be time consuming, so it's recommended to use includeConsumptionInfo parameter instead.

If both this parameter and includeConsumptionInfo are set, includeUncachedConsumptionInfo will take priority.

queryoptional

Response

Response codes

CodeTypeDescription
200EnvironmentList

Successful operation.

Response body objects

The EnvironmentList object

A list of environments.

ElementTypeDescription
totalCountinteger

The total number of entries in the result.

pageSizeinteger

The number of entries per page.

nextPageKeystring

The cursor for the next page of results. Has the value of null on the last page.

Use it in the nextPageKey query parameter to obtain subsequent pages of the result.

environmentsEnvironment[]

The list of environments.

The Environment object

Basic configuration for an environment.

ElementTypeDescription
namestring

The display name of the environment.

idstring

The ID of the environment. Has to match [a-zA-Z0-9_-]{1,70}

trialboolean

Specifies whether the environment is a trial environment or a non-trial environment. Creating a trial environment is only possible if your license allows that. The default value is false (non-trial).

statestring

Indicates whether the environment is enabled or disabled. The default value is ENABLED.

The element can hold these values
  • DISABLED
  • ENABLED
tagsstring[]

A set of tags that are assigned to this environment. Every tag can have a maximum length of 100 characters.

creationDatestring

The creation date of the environment in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSS'Z')

quotasEnvironmentQuotas

Environment level consumption and quotas information. Only returned if includeConsumptionInfo or includeUncachedConsumptionInfo param is true. If skipped when editing via PUT method then already set quotas will remain.

storageEnvironmentStorage

Environment level storage usage and limit information. Not returned if includeStorageInfo param is not true. If skipped when editing via PUT method then already set limits will remain.

The EnvironmentQuotas object

Environment level consumption and quotas information. Only returned if includeConsumptionInfo or includeUncachedConsumptionInfo param is true. If skipped when editing via PUT method then already set quotas will remain.

ElementTypeDescription
hostUnitsHostUnitQuota

Host units consumption and quota information on environment level. If skipped when editing via PUT method then already set quota will remain.

demUnitsDemUnitsQuota

DEM units consumption and quota information on environment level. Not set (and not editable) if DEM units is not enabled. If skipped when editing via PUT method then already set quotas will remain.

userSessionsUserSessionsQuota

User sessions consumption and quota information on environment level. If skipped when editing via PUT method then already set quotas will remain.

sessionPropertiesSessionPropertiesQuota

User session properties consumption information on environment level.

syntheticMonitorsSyntheticQuota

Synthetic monitors consumption and quota information on environment level. Not set (and not editable) if neither Synthetic nor DEM units is enabled. If skipped when editing via PUT method then already set quotas will remain.

customMetricsCustomMetricsQuota

Custom metrics consumption and quota information on environment level. Not set (and not editable) if Custom metrics is not enabled. Not set (and not editable) if Davis data units is enabled. If skipped when editing via PUT method then already set quota will remain.

davisDataUnitsDavisDataUnitsQuota

Davis data units consumption and quota information on environment level. Not set (and not editable) if Davis data units is not enabled. If skipped when editing via PUT method then already set quotas will remain.

logMonitoringLogMonitoringQuota

Log monitoring consumption and quota information on environment level. Not set (and not editable) if Log monitoring is not enabled. Not set (and not editable) if Log monitoring is migrated to Davis data on license level. If skipped when editing via PUT method then already set quotas will remain.

The HostUnitQuota object

Host units consumption and quota information on environment level. If skipped when editing via PUT method then already set quota will remain.

ElementTypeDescription
currentUsagenumber

Current environment usage.

maxLimitinteger

Concurrent environment quota. Not set if unlimited. When updating via PUT method, skipping this field will set quota unlimited.

The DemUnitsQuota object

DEM units consumption and quota information on environment level. Not set (and not editable) if DEM units is not enabled. If skipped when editing via PUT method then already set quotas will remain.

ElementTypeDescription
consumedThisMonthnumber

Monthly environment consumption. Resets each calendar month.

consumedThisYearnumber

Yearly environment consumption. Resets each year on license creation date anniversary.

monthlyLimitinteger

Monthly environment quota. Not set if unlimited. When updating via PUT method, skipping this field will set quota unlimited.

annualLimitinteger

Annual environment quota. Not set if unlimited. When updating via PUT method, skipping this field will set quota unlimited.

The UserSessionsQuota object

User sessions consumption and quota information on environment level. If skipped when editing via PUT method then already set quotas will remain.

ElementTypeDescription
consumedUserSessionsWithMobileSessionReplayThisYearnumber

Yearly Mobile user sessions with replay environment consumption. Resets each year on license creation date anniversary.

consumedUserSessionsWithWebSessionReplayThisMonthnumber

Monthly Web user sessions with replay environment consumption. Resets each calendar month.

consumedUserSessionsWithMobileSessionReplayThisMonthnumber

Monthly Mobile user sessions with replay environment consumption. Resets each calendar month.

totalAnnualLimitinteger

Annual total User sessions environment quota. Not set if unlimited. When updating via PUT method, skipping this field will set quota unlimited.

totalConsumedThisMonthnumber

Monthly total User sessions environment consumption. Resets each calendar month.

totalConsumedThisYearnumber

Yearly total User sessions environment consumption. Resets each year on license creation date anniversary.

totalMonthlyLimitinteger

Monthly total User sessions environment quota. Not set if unlimited. When updating via PUT method, skipping this field will set quota unlimited.

consumedUserSessionsWithWebSessionReplayThisYearnumber

Yearly Web user sessions with replay environment consumption. Resets each year on license creation date anniversary.

consumedMobileSessionsThisMonthnumber

Monthly Mobile user sessions environment consumption. Resets each calendar month.

consumedMobileSessionsThisYearnumber

Yearly Mobile user sessions environment consumption. Resets each year on license creation date anniversary.

The SessionPropertiesQuota object

User session properties consumption information on environment level.

ElementTypeDescription
consumedThisMonthnumber

Monthly environment consumption. Resets each calendar month.

consumedThisYearnumber

Yearly environment consumption. Resets each year on license creation date anniversary.

The SyntheticQuota object

Synthetic monitors consumption and quota information on environment level. Not set (and not editable) if neither Synthetic nor DEM units is enabled. If skipped when editing via PUT method then already set quotas will remain.

ElementTypeDescription
consumedThisMonthnumber

Monthly environment consumption. Resets each calendar month.

consumedThisYearnumber

Yearly environment consumption. Resets each year on license creation date anniversary.

monthlyLimitinteger

Monthly environment quota. Not set if unlimited. When updating via PUT method, skipping this field will set quota unlimited.

annualLimitinteger

Annual environment quota. Not set if unlimited. When updating via PUT method, skipping this field will set quota unlimited.

The CustomMetricsQuota object

Custom metrics consumption and quota information on environment level. Not set (and not editable) if Custom metrics is not enabled. Not set (and not editable) if Davis data units is enabled. If skipped when editing via PUT method then already set quota will remain.

ElementTypeDescription
currentUsagenumber

Current environment usage.

maxLimitinteger

Concurrent environment quota. Not set if unlimited. When updating via PUT method, skipping this field will set quota unlimited.

The DavisDataUnitsQuota object

Davis data units consumption and quota information on environment level. Not set (and not editable) if Davis data units is not enabled. If skipped when editing via PUT method then already set quotas will remain.

ElementTypeDescription
consumedThisMonthnumber

Monthly environment consumption. Resets each calendar month.

consumedThisYearnumber

Yearly environment consumption. Resets each year on license creation date anniversary.

monthlyLimitinteger

Monthly environment quota. Not set if unlimited. When updating via PUT method, skipping this field will set quota unlimited.

annualLimitinteger

Annual environment quota. Not set if unlimited. When updating via PUT method, skipping this field will set quota unlimited.

The LogMonitoringQuota object

Log monitoring consumption and quota information on environment level. Not set (and not editable) if Log monitoring is not enabled. Not set (and not editable) if Log monitoring is migrated to Davis data on license level. If skipped when editing via PUT method then already set quotas will remain.

ElementTypeDescription
consumedThisMonthnumber

Monthly environment consumption. Resets each calendar month.

consumedThisYearnumber

Yearly environment consumption. Resets each year on license creation date anniversary.

monthlyLimitinteger

Monthly environment quota. Not set if unlimited. When updating via PUT method, skipping this field will set quota unlimited.

annualLimitinteger

Annual environment quota. Not set if unlimited. When updating via PUT method, skipping this field will set quota unlimited.

The EnvironmentStorage object

Environment level storage usage and limit information. Not returned if includeStorageInfo param is not true. If skipped when editing via PUT method then already set limits will remain.

ElementTypeDescription
transactionStorageTransactionStorage

Transaction storage usage and limit information on environment level. If skipped when editing via PUT method then already set limit will remain.

sessionReplayStorageSessionReplayStorage

Session replay storage usage and limit information on environment level. If skipped when editing via PUT method then already set limit will remain.

symbolFilesFromMobileAppsSymbolFilesFromMobileApps

Symbol files from mobile apps storage usage and limit information on environment level. If skipped when editing via PUT method then already set limit will remain.

logMonitoringStorageLogMonitoringStorage

Log monitoring storage usage and limit information on environment level. Not editable when Log monitoring is not allowed by license or not configured on cluster level. If skipped when editing via PUT method then already set limit will remain.

serviceRequestLevelRetentionServiceRequestLevelRetention

Service request level retention settings on environment level. Service code level retention time can't be greater than service request level retention time and both can't exceed one year.If skipped when editing via PUT method then already set limit will remain.

serviceCodeLevelRetentionServiceCodeLevelRetention

Service code level retention settings on environment level. Service code level retention time can't be greater than service request level retention time and both can't exceed one year.If skipped when editing via PUT method then already set limit will remain.

realUserMonitoringRetentionRealUserMonitoringRetention

Real user monitoring retention settings on environment level. Can be set to any value from 1 to 35 days. If skipped when editing via PUT method then already set limit will remain.

syntheticMonitoringRetentionSyntheticMonitoringRetention

Synthetic monitoring retention settings on environment level. Can be set to any value from 1 to 35 days. If skipped when editing via PUT method then already set limit will remain.

sessionReplayRetentionSessionReplayRetention

Session replay retention settings on environment level. Can be set to any value from 1 to 35 days. If skipped when editing via PUT method then already set limit will remain.

logMonitoringRetentionLogMonitoringRetention

Log monitoring retention settings on environment level. Not editable when Log monitoring is not allowed by license or not configured on cluster level. Can be set to any value from 5 to 90 days. If skipped when editing via PUT method then already set limit will remain.

userActionsPerMinuteUserActionsPerMinute

Maximum number of user actions generated per minute on environment level. Can be set to any value from 1 to 2147483646 or left unlimited. If skipped when editing via PUT method then already set limit will remain.

transactionTrafficQuotaTransactionTrafficQuota

Maximum number of newly monitored entry point PurePaths captured per process/minute on environment level. Can be set to any value from 100 to 100000. If skipped when editing via PUT method then already set limit will remain.

The TransactionStorage object

Transaction storage usage and limit information on environment level. If skipped when editing via PUT method then already set limit will remain.

ElementTypeDescription
retentionReductionPercentagestring

Percentage of truncation for new data.

retentionReductionReasonstring

Reason of truncation.

maxLimitinteger

Maximum storage limit [bytes]

currentlyUsedinteger

Currently used storage [bytes]

The SessionReplayStorage object

Session replay storage usage and limit information on environment level. If skipped when editing via PUT method then already set limit will remain.

ElementTypeDescription
retentionReductionPercentagestring

Percentage of truncation for new data.

retentionReductionReasonstring

Reason of truncation.

maxLimitinteger

Maximum storage limit [bytes]

currentlyUsedinteger

Currently used storage [bytes]

The SymbolFilesFromMobileApps object

Symbol files from mobile apps storage usage and limit information on environment level. If skipped when editing via PUT method then already set limit will remain.

ElementTypeDescription
maxLimitinteger

Maximum storage limit [bytes]

currentlyUsedinteger

Currently used storage [bytes]

The LogMonitoringStorage object

Log monitoring storage usage and limit information on environment level. Not editable when Log monitoring is not allowed by license or not configured on cluster level. If skipped when editing via PUT method then already set limit will remain.

ElementTypeDescription
maxLimitinteger

Maximum storage limit [bytes]

currentlyUsedinteger

Currently used storage [bytes]

The ServiceRequestLevelRetention object

Service request level retention settings on environment level. Service code level retention time can't be greater than service request level retention time and both can't exceed one year.If skipped when editing via PUT method then already set limit will remain.

ElementTypeDescription
maxLimitInDaysinteger

Maximum retention limit [days]

currentlyUsedInMillisinteger

Current data age [milliseconds]

currentlyUsedInDaysinteger

Current data age [days]

The ServiceCodeLevelRetention object

Service code level retention settings on environment level. Service code level retention time can't be greater than service request level retention time and both can't exceed one year.If skipped when editing via PUT method then already set limit will remain.

ElementTypeDescription
maxLimitInDaysinteger

Maximum retention limit [days]

currentlyUsedInMillisinteger

Current data age [milliseconds]

currentlyUsedInDaysinteger

Current data age [days]

The RealUserMonitoringRetention object

Real user monitoring retention settings on environment level. Can be set to any value from 1 to 35 days. If skipped when editing via PUT method then already set limit will remain.

ElementTypeDescription
maxLimitInDaysinteger

Maximum retention limit [days]

currentlyUsedInMillisinteger

Current data age [milliseconds]

currentlyUsedInDaysinteger

Current data age [days]

The SyntheticMonitoringRetention object

Synthetic monitoring retention settings on environment level. Can be set to any value from 1 to 35 days. If skipped when editing via PUT method then already set limit will remain.

ElementTypeDescription
maxLimitInDaysinteger

Maximum retention limit [days]

currentlyUsedInMillisinteger

Current data age [milliseconds]

currentlyUsedInDaysinteger

Current data age [days]

The SessionReplayRetention object

Session replay retention settings on environment level. Can be set to any value from 1 to 35 days. If skipped when editing via PUT method then already set limit will remain.

ElementTypeDescription
maxLimitInDaysinteger

Maximum retention limit [days]

currentlyUsedInMillisinteger

Current data age [milliseconds]

currentlyUsedInDaysinteger

Current data age [days]

The LogMonitoringRetention object

Log monitoring retention settings on environment level. Not editable when Log monitoring is not allowed by license or not configured on cluster level. Can be set to any value from 5 to 90 days. If skipped when editing via PUT method then already set limit will remain.

ElementTypeDescription
maxLimitInDaysinteger

Maximum retention limit [days]

currentlyUsedInMillisinteger

Current data age [milliseconds]

currentlyUsedInDaysinteger

Current data age [days]

The UserActionsPerMinute object

Maximum number of user actions generated per minute on environment level. Can be set to any value from 1 to 2147483646 or left unlimited. If skipped when editing via PUT method then already set limit will remain.

ElementTypeDescription
maxLimitinteger

Maximum traffic [units per minute]

The TransactionTrafficQuota object

Maximum number of newly monitored entry point PurePaths captured per process/minute on environment level. Can be set to any value from 100 to 100000. If skipped when editing via PUT method then already set limit will remain.

ElementTypeDescription
maxLimitinteger

Maximum traffic [units per minute]

Response body JSON model

json
{ "totalCount": 1, "pageSize": 1, "nextPageKey": "AQAAABQBAAAABQ==", "environments": [ { "name": "example environment", "state": "ENABLED", "tags": [ "tag1", "tag2" ], "trial": false } ] }

Example

Lists the two newest enabled environments with their license consumption, sorted by name.

Curl

bash
curl -X GET "https://myManaged.cluster.com/api/cluster/v2/environments?pageSize=2&sort=-creationDate&filter=state%28ENABLED%29&includeConsumptionInfo=true" -H "accept: application/json; charset=utf-8" -H "Authorization: Api-Token dt0c01.abc123.abcdefjhij1234567890"

Request URL

plaintext
https://myManaged.cluster.com/api/cluster/v2/environments?pageSize=2&sort=-creationDate&filter=state%28ENABLED%29&includeConsumptionInfo=true

Response body

json
{ "totalCount": 78, "pageSize": 2, "nextPageKey": "AAAAAQAAAAIBnldfkgldsjoeriKIDFL2AAABd3uuvIMBAA5zdGF0ZShFTkFCTEVEKQEADS1jcmVhdGlvbkRhdGU=", "environments": [ { "name": "AndroidApps", "id": "be22c776-1414-00e0-a00a-00b0dcf56443321", "trial": false, "state": "ENABLED", "tags": [], "creationDate": "2021-02-09T11:03:17.732Z", "quotas": { "hostUnits": { "maxLimit": 10, "currentUsage": 0 }, "demUnits": { "monthlyLimit": 50001, "annualLimit": null, "consumedThisMonth": 0, "consumedThisYear": 0 }, "userSessions": { "totalMonthlyLimit": null, "totalAnnualLimit": null, "totalConsumedThisMonth": 0, "totalConsumedThisYear": 0, "consumedMobileSessionsThisMonth": 0, "consumedMobileSessionsThisYear": 0, "consumedUserSessionsWithWebSessionReplayThisMonth": 0, "consumedUserSessionsWithWebSessionReplayThisYear": 0, "consumedUserSessionsWithMobileSessionReplayThisMonth": 0, "consumedUserSessionsWithMobileSessionReplayThisYear": 0 }, "sessionProperties": { "consumedThisMonth": 0, "consumedThisYear": 0 }, "syntheticMonitors": { "monthlyLimit": null, "annualLimit": null, "consumedThisMonth": 0, "consumedThisYear": 0 }, "customMetrics": null, "davisDataUnits": { "monthlyLimit": 18162, "annualLimit": null, "consumedThisMonth": 0, "consumedThisYear": 0 }, "logMonitoring": null } }, { "name": "Service Team", "id": "881c4134-0000-0a00-aa0a-5b03ab7a34ed", "trial": false, "state": "ENABLED", "tags": [], "creationDate": "2021-02-07T08:49:45.091Z", "quotas": { "hostUnits": { "maxLimit": null, "currentUsage": 0 }, "demUnits": { "monthlyLimit": null, "annualLimit": null, "consumedThisMonth": 0, "consumedThisYear": 62 }, "userSessions": { "totalMonthlyLimit": null, "totalAnnualLimit": null, "totalConsumedThisMonth": 0, "totalConsumedThisYear": 0, "consumedMobileSessionsThisMonth": 0, "consumedMobileSessionsThisYear": 0, "consumedUserSessionsWithWebSessionReplayThisMonth": 0, "consumedUserSessionsWithWebSessionReplayThisYear": 0, "consumedUserSessionsWithMobileSessionReplayThisMonth": 0, "consumedUserSessionsWithMobileSessionReplayThisYear": 0 }, "sessionProperties": { "consumedThisMonth": 0, "consumedThisYear": 0 }, "syntheticMonitors": { "monthlyLimit": null, "annualLimit": null, "consumedThisMonth": 0, "consumedThisYear": 62 }, "customMetrics": null, "davisDataUnits": { "monthlyLimit": null, "annualLimit": null, "consumedThisMonth": 0, "consumedThisYear": 0 }, "logMonitoring": null } } ] }

Response code

200