• Home
  • Dynatrace API
  • Environment
  • Monitored entities
  • Entity selector

Environment API v2 - Entity selector

The entity selector is a powerful instrument for specifying which entities you want to include to the scope of your Environment v2 API calls. It is used in several APIs, so you only have to learn the syntax once and then reuse it for multiple use cases.

You must specify one of following criteria:

  • Entity type
  • Entity ID

Additionally you can provide the following criteria in any combination:

  • Entity name
  • Entity attribute
  • Tag
  • Management zone ID
  • Management zone name
  • Health state

If you provide several criteria, only results matching all criteria are included in the response.

Limitations

The total length of the entitySelector string is limited to 10,000 characters.

You can select only one type of entity per query.

Entity type

The type of the entity you want to query.

You can fetch the list of available entity types with the GET all entity types call.

Syntaxtype("value")
Multiple values
Value operatorEQUALS
Case-sensitive value

Dynatrace entity ID

The Dynatrace entity ID of the requested entity.

To specify several IDs, separate them by a comma (,). All requested entities must be of the same type.

You can fetch the list of available entities with the GET entities list call.

SyntaxentityId("id-1","id-2")
Multiple values
Value operatorEQUALS
Case-sensitive value

Entity name

The name of the requested entity.

You can fetch the list of available entities with the GET entities list call.

SyntaxentityName("name")
Multiple values
Value operatorCONTAINS
Case-sensitive value

Starts with modification

Changes the value operator of the entity name criterion to BEGINS WITH.

SyntaxentityName.startsWith("name")
Multiple values
Value operatorBEGINS WITH
Case-sensitive value

Equals modification

Changes the value operator of the entity name criterion to EQUALS.

SyntaxentityName.equals("name")
Multiple values
Value operatorEQUALS
Case-sensitive value

One of values modification

Enables you to provide multiple values for the entity name criterion.

SyntaxentityName.in("name1","name2")
Multiple values
Value operatorEQUALS
Case-sensitive value

Case sensitive modification

By default entity names evaluation disregards the case. You can make the criterion stricter by using the caseSensitive modification. It takes any entity name criterion as an argument (including those already modified with .startsWith or .equals modifiers) and evaluates values as case-sensitive.

SyntaxcaseSensitive(<entity name criterion>)
Multiple arguments

Entity attribute

The attribute name—attribute value pair that the requested entity should have.

To specify several attribute values, separate them with commas (,).

To fetch the list of available attributes, execute the GET entity type call and check the properties field. You can use attributes with values that can be represented by a string.

Syntax<attribute name>("attribute value")
Multiple values
Value operatorEQUALS
Case-sensitive attribute name
Case-sensitive attribute value

Exists modification

Changes the operator of the entity attribute criterion to EXISTS. In this case, the condition selects the entities that have the attribute, regardless of the attribute's value.

Syntax<attribute name>.exists()
OperatorEXISTS

Tag

The tag of the requested entities. Tags in [context]key:value, key:value, and value formats are detected and parsed automatically. If a value-only tag has a colon (:) in it, you must escape the colon with a backslash(\). Otherwise, the tag will be parsed as a key:value tag.

To specify several tags, separate them by a comma (,). An entity with any of the specified tags is included to the response.

You can fetch the list of available tags with the GET custom tags and the GET auto-tags calls.

Syntaxtag("[context]key1:value-1","key2:value-2","value-3")
Multiple values
Value operatorEQUALS
Case-sensitive value

Management zone ID

The ID of the management zone to which the requested entities belong.

To specify several IDs, separate them by a comma (,).

You can fetch the list of available management zones with the GET all management zones call.

SyntaxmzId("123456789","987654321")
Multiple values
Value operatorEQUALS
Case-sensitive valuen/a

Management zone name

The name of the management zone to which the requested entities belong.

To specify several names, separate them by a comma (,).

You can fetch the list of available management zones with the GET all management zones call.

SyntaxmzName("name-1","name-2")
Multiple values
Value operatorEQUALS
Case-sensitive value

Health state

The health state of the requested entities. Possible values are HEALTHY and UNHEALTHY.

SyntaxhealthState("HEALTHY")
Multiple values
Value operatorEQUALS
Case-sensitive value

First seen

The timestamp (UTC milliseconds) when the entity was seen for the first time.

Syntax

firstSeenTms.<operator>(timestamp)

Multiple values

Value operator

  • lte: earlier than or at the specified time
  • lt: earlier than the specified time
  • gte: later than or at the specified time
  • gt: later than the specified time

Case-sensitive value

n/a

Relationships

Relationships that the requested entity should have.

To fetch the list of available relationships, issue the GET entity type call and check the fromRelationships and toRelationships fields.

Syntax

  • fromRelationships.<relationship>(<entitySelector>)
  • toRelationships.<relationship>(<entitySelector>)

Multiple arguments

Note

Takes an entity selector as an attribute.

Negate criterion

You can use the not modification to invert any criterion except for type. It takes a criterion as an argument and inverts the condition. For example, the not(tag("Infrastructure:Linux")) criterion selects entities that do not have the Infrastructure:Linux tag.

You can use the negated criteria as part of complicated selectors, just like any other criteria.

Syntaxnot (<criterion>)
Multiple arguments
NoteDoesn't support type criteria.
Related topics
  • Custom tags API

    Manage custom tags of the monitored entities via the Dynatrace API.

  • Metrics API v2

    Retrieve metric information via Metrics v2 API.

  • Monitored entities API

    Learn about the Dynatrace Monitored entities API.

  • Problems API v2

    Find out what the Dynatrace Problems v2 API offers.