Get the history of settings objects

Latest Dynatrace
Reference
Published Oct 13, 2026

Get the revision history of Dynatrace settings objects with the Settings API, based on settings audit logs in Grail, with filtering and sorting.


GET	SaaS	`https://{your-environment-id}.apps.dynatrace.com/platform/settings/v1/history`

Overview

You use this operation to read the revision history of settings objects, based on audit logs that Dynatrace reads from Grail for the settings provider. The schema-ids, scope, and filter query parameters narrow the revisions, and you can sort the results. Typical usage is auditing who changed a setting and when.

Authentication

To execute this request, you need a platform token or OAuth access token with settings:objects:read scope. To learn how to obtain and use it, see Tokens and authentication.

Parameters

Parameter	Type	Description	In	Required
schema-ids	string	Schema IDs to which the requested revisions belong as a comma-separated list. To load the first page, when the page-key isn't set, this parameter is required.	query	Optional
scope	string	Scope to which the requested revisions belong. To load the first page, when the page-key isn't set, this parameter is required.	query	Optional
filter	string	The filter parameter, as explained here. Nesting and unary operators aren't supported. Filtering is supported on the following fields: `revision` `objectId` `schemaVersion` `modificationInfo.lastModifiedTime` `modificationInfo.lastModifiedBy` If this parameter is omitted only revisions of the last 2 weeks are returned. If modificationInfo.lastModifiedTime doesn't specify a full range, it will be completed with current time minus 1 year for the missing lower bound or the current time for the upper bound. When the admin-access is set to false, this parameter is required for schemas with enabled owner based access control and must contain objectId field with operator `==`.	query	Optional
sort	string	The sort parameter, as explained here Sorting is supported on the following fields: `modificationInfo.lastModifiedTime`	query	Optional
add-fields	string	A list of fields to be included in the response. The provided set of fields extends the default set. Specify the required top-level fields, separated by commas (for example, revision,modificationInfo). Supported fields: revision, jsonPatch, jsonBefore, jsonAfter, objectId, type, schemaVersion, modificationInfo, schemaId, schemaDisplayName, summary, appId, source, ownerBefore, ownerAfter. Default fields: revision, modificationInfo.	query	Optional
page-key	string	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 page-key query parameter. When the page-key is set to obtain subsequent pages, you must omit all other query parameters.	query	Optional
page-size	integer	The amount of settings objects in a single response payload. The maximal allowed page size is 5000. If not set, 100 is used.	query	Optional
admin-access	boolean	If set to true and user has settings:objects:admin permission, the endpoint will act as if the user is the owner of all objects	query	Optional

Response

Response codes

Code	Type	Description
200	RevisionDiffPage	Success.
404	-	-
429	-	-
503	-	-
4XX	-	-
5XX	-	-

Response body objects

The `RevisionDiffPage` object

The paged response payload for diff between revisions of settings.

Element	Type	Description
nextPageKey	string	The cursor for the next page of results. Has the value of `null` on the last page. Use it in the page-key query parameter to obtain subsequent pages of the result.
pageSize	integer	The number of entries per page.
items	RevisionDiff[]	The list of revisions changes in the current page.
totalCount	integer	The total number of entries in the result.
startTime	string	The 'from' time in ISO Date Time Format from the original request.
endTime	string	The 'to' time in ISO Date Time Format from the original request.

The `RevisionDiff` object

The diff between two revisions.

Element	Type	Description
revision	string	The revision of the change.
jsonPatch	JsonPatch[]	The JSON Patch for this value. May be null if the diff type isn't UPDATE.
jsonAfter	string	The new value of the changed settings value or null if the value has been deleted.
jsonBefore	string	The previous value of the changed settings value or null if the value has been newly created.
objectId	string	The ID of the settings object.
type	string	The type of the difference. The element can hold these values `CREATE` `DELETE` `NO_CHANGE` `REORDER` `UPDATE`
schemaId	string	Schema ID to which the revision belongs.
schemaDisplayName	string	The display name of the schema to which the revision belongs.
schemaVersion	string	The schema version the new value complies to.
summary	string	Summary of the object value corresponding to the summary pattern of the schema.
appId	string	The id of the app which changed the settings object.
modificationInfo	ModificationInfo	Modification information about the setting.
source	string	The source of the change.
ownerBefore	Identity	-
ownerAfter	Identity	-

The `JsonPatch` object

The `ModificationInfo` object

Modification information about the setting.

Element	Type	Description
createdBy	string	The unique identifier of the user who created the setting.
createdTime	string	Timestamp when the setting was created in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSS'Z')
lastModifiedBy	string	The unique identifier of the user who performed the most recent modification.
lastModifiedTime	string	Timestamp when the setting was last modified in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSS'Z')
lastModifiedReason	string	The reason for the most recent modification, if available.

The `Identity` object

Element	Type	Description
type	string	- The element can hold these values `user` `group` `all-users`
id	string	user id or user group id if type is 'user' or 'group', missing if type is 'all-users'

Response body JSON models

{
  "nextPageKey": "AQAAABQBAAAABQ==",
  "pageSize": 1,
  "items": [
    {
      "revision": "string",
      "jsonPatch": [
        {}
      ],
      "jsonAfter": "string",
      "jsonBefore": "string",
      "objectId": "string",
      "type": "CREATE",
      "schemaId": "string",
      "schemaDisplayName": "string",
      "schemaVersion": "string",
      "summary": "string",
      "appId": "string",
      "modificationInfo": {
        "createdBy": "fab17b7a-2eb2-4c95-b818-743d94be2c30",
        "createdTime": "string",
        "lastModifiedBy": "fab17b7a-2eb2-4c95-b818-743d94be2c30",
        "lastModifiedTime": "string",
        "lastModifiedReason": "string"
      },
      "source": "string",
      "ownerBefore": {
        "type": "user",
        "id": "string"
      },
      "ownerAfter": {}
    }
  ],
  "totalCount": 1,
  "startTime": "string",
  "endTime": "string"
}

GET

SaaS

https://{your-environment-id}.apps.dynatrace.com/platform/settings/v1/history

Overview

Parameters

Parameter	Type	Description	In	Required
schema-ids	string	Schema IDs to which the requested revisions belong as a comma-separated list. To load the first page, when the page-key isn't set, this parameter is required.	query	Optional
scope	string	Scope to which the requested revisions belong. To load the first page, when the page-key isn't set, this parameter is required.	query	Optional
filter	string	The filter parameter, as explained here. Nesting and unary operators aren't supported. Filtering is supported on the following fields: `revision` `objectId` `schemaVersion` `modificationInfo.lastModifiedTime` `modificationInfo.lastModifiedBy` If this parameter is omitted only revisions of the last 2 weeks are returned. If modificationInfo.lastModifiedTime doesn't specify a full range, it will be completed with current time minus 1 year for the missing lower bound or the current time for the upper bound. When the admin-access is set to false, this parameter is required for schemas with enabled owner based access control and must contain objectId field with operator `==`.	query	Optional
sort	string	The sort parameter, as explained here Sorting is supported on the following fields: `modificationInfo.lastModifiedTime`	query	Optional
add-fields	string	A list of fields to be included in the response. The provided set of fields extends the default set. Specify the required top-level fields, separated by commas (for example, revision,modificationInfo). Supported fields: revision, jsonPatch, jsonBefore, jsonAfter, objectId, type, schemaVersion, modificationInfo, schemaId, schemaDisplayName, summary, appId, source, ownerBefore, ownerAfter. Default fields: revision, modificationInfo.	query	Optional
page-key	string	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 page-key query parameter. When the page-key is set to obtain subsequent pages, you must omit all other query parameters.	query	Optional
page-size	integer	The amount of settings objects in a single response payload. The maximal allowed page size is 5000. If not set, 100 is used.	query	Optional
admin-access	boolean	If set to true and user has settings:objects:admin permission, the endpoint will act as if the user is the owner of all objects	query	Optional

Response

Response codes

Code	Type	Description
200	RevisionDiffPage	Success.
404	-	-
429	-	-
503	-	-
4XX	-	-
5XX	-	-

Response body objects

The `RevisionDiffPage` object

The paged response payload for diff between revisions of settings.

Element	Type	Description
nextPageKey	string	The cursor for the next page of results. Has the value of `null` on the last page. Use it in the page-key query parameter to obtain subsequent pages of the result.
pageSize	integer	The number of entries per page.
items	RevisionDiff[]	The list of revisions changes in the current page.
totalCount	integer	The total number of entries in the result.
startTime	string	The 'from' time in ISO Date Time Format from the original request.
endTime	string	The 'to' time in ISO Date Time Format from the original request.

The `RevisionDiff` object

The diff between two revisions.

Element	Type	Description
revision	string	The revision of the change.
jsonPatch	JsonPatch[]	The JSON Patch for this value. May be null if the diff type isn't UPDATE.
jsonAfter	string	The new value of the changed settings value or null if the value has been deleted.
jsonBefore	string	The previous value of the changed settings value or null if the value has been newly created.
objectId	string	The ID of the settings object.
type	string	The type of the difference. The element can hold these values `CREATE` `DELETE` `NO_CHANGE` `REORDER` `UPDATE`
schemaId	string	Schema ID to which the revision belongs.
schemaDisplayName	string	The display name of the schema to which the revision belongs.
schemaVersion	string	The schema version the new value complies to.
summary	string	Summary of the object value corresponding to the summary pattern of the schema.
appId	string	The id of the app which changed the settings object.
modificationInfo	ModificationInfo	Modification information about the setting.
source	string	The source of the change.
ownerBefore	Identity	-
ownerAfter	Identity	-

The `JsonPatch` object

The `ModificationInfo` object

Modification information about the setting.

Element	Type	Description
createdBy	string	The unique identifier of the user who created the setting.
createdTime	string	Timestamp when the setting was created in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSS'Z')
lastModifiedBy	string	The unique identifier of the user who performed the most recent modification.
lastModifiedTime	string	Timestamp when the setting was last modified in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSS'Z')
lastModifiedReason	string	The reason for the most recent modification, if available.

The `Identity` object

Element	Type	Description
type	string	- The element can hold these values `user` `group` `all-users`
id	string	user id or user group id if type is 'user' or 'group', missing if type is 'all-users'

Response body JSON models

{
  "nextPageKey": "AQAAABQBAAAABQ==",
  "pageSize": 1,
  "items": [
    {
      "revision": "string",
      "jsonPatch": [
        {}
      ],
      "jsonAfter": "string",
      "jsonBefore": "string",
      "objectId": "string",
      "type": "CREATE",
      "schemaId": "string",
      "schemaDisplayName": "string",
      "schemaVersion": "string",
      "summary": "string",
      "appId": "string",
      "modificationInfo": {
        "createdBy": "fab17b7a-2eb2-4c95-b818-743d94be2c30",
        "createdTime": "string",
        "lastModifiedBy": "fab17b7a-2eb2-4c95-b818-743d94be2c30",
        "lastModifiedTime": "string",
        "lastModifiedReason": "string"
      },
      "source": "string",
      "ownerBefore": {
        "type": "user",
        "id": "string"
      },
      "ownerAfter": {}
    }
  ],
  "totalCount": 1,
  "startTime": "string",
  "endTime": "string"
}

Get the history of settings objects

Overview

Authentication

Parameters

Response

Response codes

Response body objects

The RevisionDiffPage object

The RevisionDiff object

The JsonPatch object

The ModificationInfo object

The Identity object

Response body JSON models

Get the history of settings objects

Overview

Authentication

Parameters

Response

Response codes

Response body objects

The RevisionDiffPage object

The RevisionDiff object

The JsonPatch object

The ModificationInfo object

The Identity object

Response body JSON models

The `RevisionDiffPage` object

The `RevisionDiff` object

The `JsonPatch` object

The `ModificationInfo` object

The `Identity` object

The `RevisionDiffPage` object

The `RevisionDiff` object

The `JsonPatch` object

The `ModificationInfo` object

The `Identity` object