Try it free

List settings objects

  • Latest Dynatrace
  • Reference
  • Published Oct 13, 2026

List the persisted Dynatrace settings objects of a schema and scope with the Settings API; objects you lack permission for aren't returned.

GETSaaShttps://{your-environment-id}.apps.dynatrace.com/platform/settings/v1/objects

Overview

You use the schema-id and scope query parameters to list the persisted settings objects of a schema, and add-fields to include additional fields. If nothing is persisted, or none of the persisted objects are accessible with your permissions, the response contains no items. Large results are split into pages.

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

ParameterTypeDescriptionInRequired
schema-idstring

Schema ID to which the requested objects belong.

To load the first page, when the page-key isn't set, this parameter is required.

queryOptional
scopestring

Scope to which the requested objects belong.

To load the first page, when the page-key isn't set, this parameter is required.

queryOptional
add-fieldsstring

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, summary,value).

Supported fields: objectId, version, summary, searchSummary, scope, schemaId, schemaVersion, modificationInfo, resourceContext, value, owner, externalId.

Default fields: objectId, version.

queryOptional
filterstring

The filter parameter, as explained here.

Filtering is supported on the following fields:

  • objectId
  • modificationInfo.createdBy
  • modificationInfo.createdTime
  • modificationInfo.lastModifiedBy
  • modificationInfo.lastModifiedTime
  • value with properties and sub-properties separated by dot (for example, value.owningApp = 'Notebooks')
  • externalId
  • owner.type
  • owner.id

If this parameter is omitted, all settings objects will be returned. The maximum nesting depth (via parentheses) is 5. The maximum expression length is 1024 characters.

Note that only fields included to the response via add-fields can be used for filtering.

queryOptional
sortstring

The sort parameter, as explained here.

Sorting is supported on the following fields:

  • modificationInfo.createdBy
  • modificationInfo.createdTime
  • modificationInfo.lastModifiedBy
  • modificationInfo.lastModifiedTime
  • value with properties and sub-properties separated by dot (for example, value.owningApp)

Note that only fields included to the response via add-fields can be used for sorting.

queryOptional
page-keystring

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 except the optimistic-locking-version parameter.

queryOptional
page-sizeinteger

The amount of settings objects in a single response payload.

The maximal allowed page size is 500.

If not set, the response won't be paged.

queryOptional
admin-accessboolean

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

queryOptional
optimistic-locking-versionstring

The version of the objects list for optimistic locking. You can use it to detect simultaneous modifications by different users.

It's generated upon retrieval of the list of objects (GET requests). If specified and modifications were made between retrieval and the request, the request will fail.

queryOptional

Response

Response codes

CodeTypeDescription
200SettingsObjectsList

Success. Uses chunked encoding.

Even if a response returns a successful response code it's possible that the result is incomplete due to an internal error.

In this case an 'error' property with information about the problem is added. The caller may decide to work with the incomplete result or do a retry of the operation.

400--
403--
404--
409--
429--
503--
4XX--
5XX--

Response body objects

The SettingsObjectsList object

A list of settings objects.

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 page-key query parameter to obtain subsequent pages of the result.

versionstring

The version of the settings objects list for optimistic locking." You can use it to detect simultaneous modifications by different users.

It's generated upon retrieval (GET requests). If set on reorder, the update will be allowed only if there wasn't any change between the retrieval and the update. If set on a followup GET request, it fails if there was a change between these two requests.

itemsSettingsObject[]

A list of settings objects.

errorErrorIncomplete

Error object for an incomplete response

The SettingsObject object

A settings object.

ElementTypeDescription
objectIdstring

The ID of the settings object.

summarystring

A short summary of settings. This can contain Markdown and will be escaped accordingly.

searchSummarystring

A searchable summary string of the setting value. Plain text without Markdown.

versionstring

The version of the object for optimistic locking. You can use it to detect simultaneous modifications by different users.

It's generated upon retrieval (GET requests). If set on update (PUT request) or deletion, the update/deletion will be allowed only if there wasn't any change between the retrieval and the update.

schemaIdstring

The schema on which the object is based.

schemaVersionstring

The version of the schema on which the object is based.

scopestring

The scope that the object targets. For more details, see Dynatrace Documentation.

classicScopestring

The classic scope that the object targets. For more details, see Dynatrace Documentation.

modificationInfoModificationInfo

Modification information about the setting.

resourceContextResourceContext

The resource context, which contains additional permission information about the object.

valueSettingsValue

The value of the setting.

It defines the actual values of settings' parameters.

The actual content depends on the object's schema.

ownerIdentity-
externalIdstring

The externalId of the object.

The ModificationInfo object

Modification information about the setting.

ElementTypeDescription
createdBystring

The unique identifier of the user who created the setting.

createdTimestring

Timestamp when the setting was created in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSS'Z')

lastModifiedBystring

The unique identifier of the user who performed the most recent modification.

lastModifiedTimestring

Timestamp when the setting was last modified in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSS'Z')

lastModifiedReasonstring

The reason for the most recent modification, if available.

The ResourceContext object

The resource context, which contains additional permission information about the object.

ElementTypeDescription
operationsstring[]

The allowed operations on this settings object.

The element can hold these values
  • read
  • write
  • delete
modificationsModifications

The additional modification details for this settings object.

The Modifications object

The additional modification details for this settings object.

ElementTypeDescription
firstboolean

If non-moveable settings object is in the first group of non-moveable settings, or in the last (start or end of list).

modifiablePathsstring[]

Property paths which are modifiable, regardless if the write operation is allowed.

movableboolean

If settings object can be moved/reordered. Only applicable for ordered list schema.

nonModifiablePathsstring[]

Property paths which aren't modifiable, even if the write operation is allowed.

The SettingsValue object

The value of the setting.

It defines the actual values of settings' parameters.

The actual content depends on the object's schema.

The Identity object

ElementTypeDescription
typestring-
The element can hold these values
  • user
  • group
  • all-users
idstring

user id or user group id if type is 'user' or 'group', missing if type is 'all-users'

The ErrorIncomplete object

Error object for an incomplete response

ElementTypeDescription
codeinteger

The error code (HTTP response)

messagestring

The error message

retryAfterSecondsinteger

Number of seconds a request can be retried after a 'too many requests' error response.

detailsErrorDetails

Optional details of the error

The ErrorDetails object

Optional details of the error

ElementTypeDescription
errorRefstring

reference to the error occurrence in the internal self-monitoring, logging, etc.

constraintViolationsConstraintViolation[]

A list of constraint violations of input parameters (path, query, request body)

missingScopesstring[]

In case of a 403 - Forbidden response, a list of missing scopes necessary to successfully execute the request

The ConstraintViolation object

Contains information about a constraint violation caused by invalid input.

ElementTypeDescription
pathstring

The path of the parameter that caused the constraint violation

messagestring

The constraint violation description message

parameterLocationstring

Describes the general location of the violating parameter

The element can hold these values
  • PATH
  • QUERY
  • HEADER
  • PAYLOAD_BODY

Response body JSON models

{
  "totalCount": 1,
  "pageSize": 1,
  "nextPageKey": "AQAAABQBAAAABQ==",
  "version": "string",
  "items": [
    {
      "objectId": "Y2ktaGdyb3VwLTEyMythZjhjOThlOS0wN2I0LTMyMGEtOTQzNi02NTEyMmVlNWY4NGQ=",
      "summary": "string",
      "searchSummary": "string",
      "version": "Y2ktaGdyb3VwLTEyMythZjhjOThlOS0wN2I0LTMyMGEtOTQzNi02NTEyMmVlNWY4NGQ=",
      "schemaId": "jira-connection",
      "schemaVersion": "1.0.0",
      "scope": "string",
      "classicScope": "string",
      "modificationInfo": {
        "createdBy": "fab17b7a-2eb2-4c95-b818-743d94be2c30",
        "createdTime": "string",
        "lastModifiedBy": "fab17b7a-2eb2-4c95-b818-743d94be2c30",
        "lastModifiedTime": "string",
        "lastModifiedReason": "string"
      },
      "resourceContext": {
        "operations": [
          "read"
        ],
        "modifications": {
          "first": true,
          "modifiablePaths": [
            "string"
          ],
          "movable": true,
          "nonModifiablePaths": [
            "string"
          ]
        }
      },
      "value": {
        "autoMonitoring": true
      },
      "owner": {
        "type": "user",
        "id": "string"
      },
      "externalId": "myExternalId"
    }
  ],
  "error": {
    "code": 1,
    "message": "string",
    "retryAfterSeconds": 1,
    "details": {
      "errorRef": "string",
      "constraintViolations": [
        {
          "path": "string",
          "message": "string",
          "parameterLocation": "PATH"
        }
      ],
      "missingScopes": [
        "string"
      ]
    }
  }
}
Related tags
Platform APIDynatrace Platform