Create a new environment
This API call creates a new environment.
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
Parameter | Type | Description | In | Required |
---|---|---|---|---|
createToken | boolean | If true, a token management token with the scopes 'apiTokens.read' and 'apiTokens.write' (for usage with token API v2) and 'TenantTokenManagement' (for usage with token API v1) is created when creating a new environment. This token is then returned in the response body. It can be used within the newly created environment to create other tokens for configuring this environment. | query | optional |
body | Environment | The JSON body of the request. The body must not provide an ID as it will be automatically assigned by the Dynatrace server. | body | required |
Request body objects
The Environment
object
Basic configuration for an environment.
Element | Type | Description |
---|---|---|
name | string | The display name of the environment. |
id | string | The ID of the environment. Has to match [a-zA-Z0-9_-]{1,70} Can be |
trial | boolean | 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). Can be |
state | string | Indicates whether the environment is enabled or disabled. The default value is ENABLED. Can be |
tags | string[] | A set of tags that are assigned to this environment. Every tag can have a maximum length of 100 characters. Can be |
creationDate | string | The creation date of the environment in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSS'Z') Can be |
quotas | Environment | 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. Can be |
storage | Environment | 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. Can be |
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.
Element | Type | Description |
---|---|---|
hostUnits | Host | Host units consumption and quota information on environment level. If skipped when editing via PUT method then already set quota will remain. Can be |
demUnits | Dem | 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. Can be |
userSessions | User | User sessions consumption and quota information on environment level. If skipped when editing via PUT method then already set quotas will remain. Can be |
sessionProperties | Session | User session properties consumption information on environment level. Can be |
syntheticMonitors | Synthetic | 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. Can be |
customMetrics | Custom | 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. Can be |
davisDataUnits | Davis | 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. Can be |
logMonitoring | Log | 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. Can be |
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.
Element | Type | Description |
---|---|---|
currentUsage | number | Current environment usage. Can be |
maxLimit | integer | Concurrent environment quota. Not set if unlimited. When updating via PUT method, skipping this field will set quota unlimited. Can be |
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.
Element | Type | Description |
---|---|---|
consumedThisMonth | number | Monthly environment consumption. Resets each calendar month. Can be |
consumedThisYear | number | Yearly environment consumption. Resets each year on license creation date anniversary. Can be |
monthlyLimit | integer | Monthly environment quota. Not set if unlimited. When updating via PUT method, skipping this field will set quota unlimited. Can be |
annualLimit | integer | Annual environment quota. Not set if unlimited. When updating via PUT method, skipping this field will set quota unlimited. Can be |
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.
Element | Type | Description |
---|---|---|
consumedUserSessionsWithMobileSessionReplayThisYear | number | Yearly Mobile user sessions with replay environment consumption. Resets each year on license creation date anniversary. Can be |
consumedUserSessionsWithWebSessionReplayThisMonth | number | Monthly Web user sessions with replay environment consumption. Resets each calendar month. Can be |
consumedUserSessionsWithMobileSessionReplayThisMonth | number | Monthly Mobile user sessions with replay environment consumption. Resets each calendar month. Can be |
totalAnnualLimit | integer | Annual total User sessions environment quota. Not set if unlimited. When updating via PUT method, skipping this field will set quota unlimited. Can be |
totalConsumedThisMonth | number | Monthly total User sessions environment consumption. Resets each calendar month. Can be |
totalConsumedThisYear | number | Yearly total User sessions environment consumption. Resets each year on license creation date anniversary. Can be |
totalMonthlyLimit | integer | Monthly total User sessions environment quota. Not set if unlimited. When updating via PUT method, skipping this field will set quota unlimited. Can be |
consumedUserSessionsWithWebSessionReplayThisYear | number | Yearly Web user sessions with replay environment consumption. Resets each year on license creation date anniversary. Can be |
consumedMobileSessionsThisMonth | number | Monthly Mobile user sessions environment consumption. Resets each calendar month. Can be |
consumedMobileSessionsThisYear | number | Yearly Mobile user sessions environment consumption. Resets each year on license creation date anniversary. Can be |
The SessionPropertiesQuota
object
User session properties consumption information on environment level.
Element | Type | Description |
---|---|---|
consumedThisMonth | number | Monthly environment consumption. Resets each calendar month. Can be |
consumedThisYear | number | Yearly environment consumption. Resets each year on license creation date anniversary. Can be |
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.
Element | Type | Description |
---|---|---|
consumedThisMonth | number | Monthly environment consumption. Resets each calendar month. Can be |
consumedThisYear | number | Yearly environment consumption. Resets each year on license creation date anniversary. Can be |
monthlyLimit | integer | Monthly environment quota. Not set if unlimited. When updating via PUT method, skipping this field will set quota unlimited. Can be |
annualLimit | integer | Annual environment quota. Not set if unlimited. When updating via PUT method, skipping this field will set quota unlimited. Can be |
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.
Element | Type | Description |
---|---|---|
currentUsage | number | Current environment usage. Can be |
maxLimit | integer | Concurrent environment quota. Not set if unlimited. When updating via PUT method, skipping this field will set quota unlimited. Can be |
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.
Element | Type | Description |
---|---|---|
consumedThisMonth | number | Monthly environment consumption. Resets each calendar month. Can be |
consumedThisYear | number | Yearly environment consumption. Resets each year on license creation date anniversary. Can be |
monthlyLimit | integer | Monthly environment quota. Not set if unlimited. When updating via PUT method, skipping this field will set quota unlimited. Can be |
annualLimit | integer | Annual environment quota. Not set if unlimited. When updating via PUT method, skipping this field will set quota unlimited. Can be |
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.
Element | Type | Description |
---|---|---|
consumedThisMonth | number | Monthly environment consumption. Resets each calendar month. Can be |
consumedThisYear | number | Yearly environment consumption. Resets each year on license creation date anniversary. Can be |
monthlyLimit | integer | Monthly environment quota. Not set if unlimited. When updating via PUT method, skipping this field will set quota unlimited. Can be |
annualLimit | integer | Annual environment quota. Not set if unlimited. When updating via PUT method, skipping this field will set quota unlimited. Can be |
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.
Element | Type | Description |
---|---|---|
transactionStorage | Transaction | Transaction storage usage and limit information on environment level. If skipped when editing via PUT method then already set limit will remain. Can be |
sessionReplayStorage | Session | Session replay storage usage and limit information on environment level. If skipped when editing via PUT method then already set limit will remain. Can be |
symbolFilesFromMobileApps | Symbol | 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. Can be |
logMonitoringStorage | Log | 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. Can be |
serviceRequestLevelRetention | Service | 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. Can be |
serviceCodeLevelRetention | Service | 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. Can be |
realUserMonitoringRetention | Real | 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. Can be |
syntheticMonitoringRetention | Synthetic | 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. Can be |
sessionReplayRetention | Session | 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. Can be |
logMonitoringRetention | Log | 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. Can be |
userActionsPerMinute | User | 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. Can be |
transactionTrafficQuota | Transaction | 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. Can be |
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.
Element | Type | Description |
---|---|---|
retentionReductionPercentage | string | Percentage of truncation for new data. Can be |
retentionReductionReason | string | Reason of truncation. Can be |
maxLimit | integer | Maximum storage limit [bytes] Can be |
currentlyUsed | integer | Currently used storage [bytes] Can be |
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.
Element | Type | Description |
---|---|---|
retentionReductionPercentage | string | Percentage of truncation for new data. Can be |
retentionReductionReason | string | Reason of truncation. Can be |
maxLimit | integer | Maximum storage limit [bytes] Can be |
currentlyUsed | integer | Currently used storage [bytes] Can be |
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.
Element | Type | Description |
---|---|---|
maxLimit | integer | Maximum storage limit [bytes] Can be |
currentlyUsed | integer | Currently used storage [bytes] Can be |
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.
Element | Type | Description |
---|---|---|
maxLimit | integer | Maximum storage limit [bytes] Can be |
currentlyUsed | integer | Currently used storage [bytes] Can be |
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.
Element | Type | Description |
---|---|---|
maxLimitInDays | integer | Maximum retention limit [days] Can be |
currentlyUsedInMillis | integer | Current data age [milliseconds] Can be |
currentlyUsedInDays | integer | Current data age [days] Can be |
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.
Element | Type | Description |
---|---|---|
maxLimitInDays | integer | Maximum retention limit [days] Can be |
currentlyUsedInMillis | integer | Current data age [milliseconds] Can be |
currentlyUsedInDays | integer | Current data age [days] Can be |
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.
Element | Type | Description |
---|---|---|
maxLimitInDays | integer | Maximum retention limit [days] Can be |
currentlyUsedInMillis | integer | Current data age [milliseconds] Can be |
currentlyUsedInDays | integer | Current data age [days] Can be |
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.
Element | Type | Description |
---|---|---|
maxLimitInDays | integer | Maximum retention limit [days] Can be |
currentlyUsedInMillis | integer | Current data age [milliseconds] Can be |
currentlyUsedInDays | integer | Current data age [days] Can be |
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.
Element | Type | Description |
---|---|---|
maxLimitInDays | integer | Maximum retention limit [days] Can be |
currentlyUsedInMillis | integer | Current data age [milliseconds] Can be |
currentlyUsedInDays | integer | Current data age [days] Can be |
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.
Element | Type | Description |
---|---|---|
maxLimitInDays | integer | Maximum retention limit [days] Can be |
currentlyUsedInMillis | integer | Current data age [milliseconds] Can be |
currentlyUsedInDays | integer | Current data age [days] Can be |
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.
Element | Type | Description |
---|---|---|
maxLimit | integer | Maximum traffic [units per minute] Can be |
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.
Element | Type | Description |
---|---|---|
maxLimit | integer | Maximum traffic [units per minute] Can be |
Request body JSON model
This is a model of the request body, showing the possible elements. It has to be adjusted for usage in an actual request.
{
"name": "example environment",
"state": "ENABLED",
"tags": [
"tag1",
"tag2"
],
"trial": false
}
Response
Response codes
Code | Type | Description |
---|---|---|
201 | Environment | Success. The environment has been created and started. The response body contains the generated ID of the environment and a token with the scopes 'apiTokens.read' and 'apiTokens.write' (for usage with token API v2) and 'TenantTokenManagement'. The location header contains the generated ID as well. |
400 | - | Failed. The input is invalid. |
Response body objects
The EnvironmentShortRepresentation
object
The short representation of an environment.
Element | Type | Description |
---|---|---|
id | string | The ID of the Dynatrace entity. |
name | string | The name of the Dynatrace entity. Can be |
description | string | A short description of the Dynatrace entity. Can be |
tokenManagementToken | string | A token with the 'Token management' permission. Can be used to within the newly created environment to create other tokens for configuring this environment. This value is only set if an environment was created with the query parameter 'createToken=true'. Can be |
Response body JSON model
{
"id": "string",
"name": "string",
"description": "string",
"tokenManagementToken": "string"
}
Example
Creates an environment called MyNewTeam
specifying details on license quota, storage limits and data retention.
Curl
curl -X POST "https://myManaged.cluster.com/api/cluster/v2/environments?createToken=true" -H "accept: application/json; charset=utf-8" -H "Authorization: Api-Token dt0c01.abc123.abcdefjhij1234567890" -H "Content-Type: application/json; charset=utf-8" -d
"{\"name\":\"MyNewTeam\",\"state\":\"ENABLED\",\"tags\":[\"owner:john.wicked@dynatrace.com\",\"department:finance\"],\"trial\":false}, \"quotas\":{\"hostUnits\":{\"maxLimit\":1},\"demUnits\":{\"monthlyLimit\":1,\"annualLimit\":1},\"userSessions\":{\"totalMonthlyLimit\":1,\"totalAnnualLimit\":2},\"syntheticMonitors\":{\"monthlyLimit\":1,\"annualLimit\":1},\"davisDataUnits\":{\"monthlyLimit\":1,\"annualLimit\":2}},\"storage\":{\"transactionStorage\":{\"maxLimit\":1024},\"sessionReplayStorage\":{\"maxLimit\":2048},\"symbolFilesFromMobileApps\":{\"maxLimit\":5050},\"serviceRequestLevelRetention\":{\"maxLimitInDays\":35},\"serviceCodeLevelRetention\":{\"maxLimitInDays\":10},\"realUserMonitoringRetention\":{\"maxLimitInDays\":35},\"syntheticMonitoringRetention\":{\"maxLimitInDays\":35},\"sessionReplayRetention\":{\"maxLimitInDays\":35},\"userActionsPerMinute\":{\"maxLimit\":3500},\"transactionTrafficQuota\":{\"maxLimit\":1000}}}"
Request URL
https://myManaged.cluster.com/api/cluster/v2/environments?createToken=true
Request body
{
"name": "MyNewTeam",
"state": "ENABLED",
"tags": [
"owner:john.wicked@dynatrace.com",
"department:finance"
],
"trial": false,
"quotas": {
"hostUnits": {
"maxLimit": 1
},
"demUnits": {
"monthlyLimit": 1,
"annualLimit": 1
},
"userSessions": {
"totalMonthlyLimit": 1,
"totalAnnualLimit": 2
},
"syntheticMonitors": {
"monthlyLimit": 1,
"annualLimit": 1
},
"davisDataUnits": {
"monthlyLimit": 1,
"annualLimit": 2
}
},
"storage": {
"transactionStorage": {
"maxLimit": 1024
},
"sessionReplayStorage": {
"maxLimit": 2048
},
"symbolFilesFromMobileApps": {
"maxLimit": 5050
},
"serviceRequestLevelRetention": {
"maxLimitInDays": 35
},
"serviceCodeLevelRetention": {
"maxLimitInDays": 10
},
"realUserMonitoringRetention": {
"maxLimitInDays": 35
},
"syntheticMonitoringRetention": {
"maxLimitInDays": 35
},
"sessionReplayRetention": {
"maxLimitInDays": 35
},
"userActionsPerMinute": {
"maxLimit": 3500
},
"transactionTrafficQuota": {
"maxLimit": 1000
}
}
}
Response body
Success. The environment has been created and started. The response body contains the generated ID of the environment and a token with the Token management
permission. The location header contains the generated ID as well.
{
"id": "11a113a1-a11b-1234-123a-4df674c8eb8e",
"name": "MyNewTeam",
"tokenManagementToken":
"dt0c01.LJMAHMWOKCL5IPH3E2ORNHTR.<token-value>"
}
Response code
201