Try it free

Create a filter segment

  • Latest Dynatrace
  • Reference
  • Published Oct 13, 2026

Create a filter segment in Dynatrace with the Grail Filter Segments API by providing its name, visibility, includes, variables, and optional description.

POSTSaaShttps://{your-environment-id}.apps.dynatrace.com/v1/filter-segments

Overview

Create a new segment and define data.

New Filter-Segment

Provide a name and an optional description for the filter-segment.

Variables

Create variables to apply in your filter-segment data filters

Includes (Segment data)

Include all data that should be accessible when applying the filter-segment

IsPublic (Visibility)

  • false: The filter-segment is private and only visible to the owner
  • true: The filter-segment is visible to everyone in the environment

Authentication

To execute this request, you need a platform token or OAuth access token with all of the following scopes:

  • storage:filter-segments:write
  • storage:filter-segments:share if isPublic is set to true

To learn how to obtain and use it, see Tokens and authentication.

Parameters

ParameterTypeDescriptionInRequired
bodyNewFilterSegment-bodyRequired

Request body objects

The NewFilterSegment object

ElementTypeDescriptionRequired
descriptionstring

Description of the filter-segment.

Optional
externalIdstring

Optional unique identifier of the filter-segment. Used for Dynatrace Configuration as Code

Optional
includesNewInclude[]

List of includes of the filter-segment.

Optional
isPublicboolean

Indicates if the filter-segment is publicly accessible within the tenant.

Required
namestring

Name of the filter-segment.

Required
variablesFilterSegmentVariables

Variables of the filter-segment.

Optional

The NewInclude object

List of includes of the filter-segment.

ElementTypeDescriptionRequired
applyTostring[]

[Experimental] The tables that the entity-filter will be applied to.

Optional
dataObjectstring

The data object that the filter will be applied to. Use '_all_data_object' to apply it to all dataObjects.

Required
filterstring

Data will be filtered by this value. Field names must only contain letters, numbers and underscores, otherwise they need to be escaped using quotes(`).

Required
relationshipNewRelationship

[Experimental] The relationship of an include which has to be be specified when the data object is an entity view.

Optional

The NewRelationship object

[Experimental] The relationship of an include which has to be be specified when the data object is an entity view.

ElementTypeDescriptionRequired
namestring

Name of the relationship.

Required
targetstring

Target of the relationship.

Required

The FilterSegmentVariables object

Variables of the filter-segment.

ElementTypeDescriptionRequired
typestring

Type of the variable.

Required
valuestring

Value of the variable.

Required

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": "dev_environment",
  "description": "only includes data of the dev environment",
  "variables": {
    "type": "query",
    "value": "fetch logs | limit 1"
  },
  "isPublic": false,
  "includes": [
    {
      "filter": "{\"type\":\"Group\",\"range\":{\"from\":0,\"to\":19},\"logicalOperator\":\"AND\",\"explicit\":false,\"children\":[{\"type\":\"Statement\",\"range\":{\"from\":0,\"to\":19},\"key\":{\"type\":\"Key\",\"textValue\":\"content\",\"value\":\"content\",\"range\":{\"from\":0,\"to\":7}},\"operator\":{\"type\":\"ComparisonOperator\",\"textValue\":\"=\",\"value\":\"=\",\"range\":{\"from\":8,\"to\":9}},\"value\":{\"type\":\"String\",\"textValue\":\"\\\"[debug]\\\"\",\"value\":\"[debug]\",\"range\":{\"from\":10,\"to\":19},\"isEscaped\":true}}]}",
      "dataObject": "logs"
    },
    {
      "filter": "{\"type\":\"Group\",\"range\":{\"from\":0,\"to\":18},\"logicalOperator\":\"AND\",\"explicit\":false,\"children\":[{\"type\":\"Statement\",\"range\":{\"from\":0,\"to\":18},\"key\":{\"type\":\"Key\",\"textValue\":\"content\",\"value\":\"content\",\"range\":{\"from\":0,\"to\":7}},\"operator\":{\"type\":\"ComparisonOperator\",\"textValue\":\"=\",\"value\":\"=\",\"range\":{\"from\":8,\"to\":9}},\"value\":{\"type\":\"String\",\"textValue\":\"\\\"[info]\\\"\",\"value\":\"[info]\",\"range\":{\"from\":10,\"to\":18},\"isEscaped\":true}}]}",
      "dataObject": "events"
    }
  ]
}

Response

Response codes

CodeTypeDescription
201DetailedFilterSegment

Filter-segment successfully created.

400ErrorEnvelope

Filter-segment Bad Request.

401ErrorEnvelope

unauthorized

403ErrorEnvelope

missing permissions

Response body objects

The DetailedFilterSegment object

ElementTypeDescription
allowedOperationsstring[]

Defines the allowed operations of the current user.

The element can hold these values
  • READ
  • WRITE
  • DELETE
  • SHARE
descriptionstring

Description of the filter-segment.

externalIdstring

Optional unique identifier of the filter-segment. Used for Dynatrace Configuration as Code

includesInclude[]

List of includes of the filter-segment.

isPublicboolean

Indicates if the filter-segment is publicly accessible within the tenant.

isReadyMadeboolean

Indicates if the segment is ready-made.

namestring

Name of the filter-segment.

ownerstring

Defines the owner of the filter-segment.

uidstring

Unique identifier of the filter-segment.

variablesFilterSegmentVariables

Variables of the filter-segment.

versioninteger

Used for optimistic locking. Update requests define with this on which version the data updated is based on. This must match with the version stored, otherwise the update will fail due to concurrent modification.

The Include object

List of includes of the filter-segment.

ElementTypeDescription
applyTostring[]

[Experimental] The tables that the entity-filter will be applied to.

dataObjectstring

The data object that the filter will be applied to. Use '_all_data_object' to apply it to all dataObjects.

filterstring

Data will be filtered by this value. Field names must only contain letters, numbers and underscores, otherwise they need to be escaped using quotes(`).

relationshipRelationship

[Experimental] The relationship of an include which has to be be specified when the data object is an entity view.

The Relationship object

[Experimental] The relationship of an include which has to be be specified when the data object is an entity view.

ElementTypeDescription
namestring

Name of the relationship.

targetstring

Target of the relationship.

The FilterSegmentVariables object

Variables of the filter-segment.

ElementTypeDescription
typestring

Type of the variable.

valuestring

Value of the variable.

The ErrorEnvelope object

ElementTypeDescription
errorExceptionalReturn-

The ExceptionalReturn object

ElementTypeDescription
codeinteger-
errorDetails(CustomValidationErrorInfo | InvalidAuditEventsErrorInfo | MediaTypeErrorInfo | ParameterErrorInfo | ProxyErrorInfo | QueryFrontendRawErrorInfo | RequestBodyErrorInfo)[]-
messagestring-

The CustomValidationErrorInfo object

The ErrorInfo object

ElementTypeDescription
messagestring-

The InvalidAuditEventsErrorInfo object

The MediaTypeErrorInfo object

The ParameterErrorInfo object

The ProxyErrorInfo object

The QueryFrontendRawErrorInfo object

The RequestBodyErrorInfo object

Response body JSON models

{
  "uid": "D82a1jdA23a",
  "name": "dev_environment",
  "description": "only includes data of the dev environment",
  "variables": {
    "type": "query",
    "value": "fetch logs | limit 1"
  },
  "isPublic": false,
  "owner": "john.doe",
  "includes": [
    {
      "filter": "here goes the filter",
      "dataObject": "logs"
    },
    {
      "filter": "here goes another filter",
      "dataObject": "events"
    }
  ],
  "version": 1
}
{
  "error": {
    "code": 400,
    "message": "Missing request header",
    "errorDetails": [
      {
        "type": "parameter",
        "parameterDescriptor": "Dt-Tenant",
        "message": "is required"
      }
    ]
  }
}
Related tags
Platform APIDynatrace Platform