Execute a query

Latest Dynatrace
Reference
Published Oct 13, 2026

Start a DQL query in Dynatrace Query API and return the initial status, with results when the query finishes within the request window.


POST	SaaS	`https://{your-environment-id}.apps.dynatrace.com/platform/storage/query/v1/query:execute`

Overview

For information about the required permissions see the Bucket and table permissions in Grail documentation.

Executes a query and returns a list of records.

For details about the query language see the Dynatrace Query Language documentation.

The response format

The json response will contain the state of the started query. If the query succeeded, the result will be included. Otherwise the response will contain a request token to reference the query in future polling requests.

The result has two main sections:

The 'records' section contains the individual records, where each record consists of a set of fields and their corresponding values.
The 'types' section describes the corresponding data types that a record field has.

Every record has an implicit 'index' according to the position in the 'records' JSON array. The types section has a list of 1..N possible type 'buckets'. Each such bucket has an 'indexRange' which indicates which records will find their field types in which bucket. The index range has two values start & end and can be thought of as [startIndex, endIndex).

A field part of a record with index 'i' will find its corresponding field type by first locating the bucket that satisfies:

startIndex <= i <= endIndex

Once the bucket is found the 'mappings' object has an entry for all the fields that are part of that record with index 'i'.

Since enforcement of a particular schema is absent at ingestion time, it is possible to have records that share the same field name but their values are of a different type. This phenomenon will hence forth be named as a "collision". When a collision does occur, we will create a new type 'bucket' that will have a different index range where the new record field types will be placed. It is guaranteed that every field of every record will have a corresponding type. Clients should always take the included types into account when consuming records!

Authentication

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

storage:bizevents:read
storage:buckets:read
storage:entities:read
storage:events:read
storage:fieldsets:read
storage:logs:read
storage:metrics:read
storage:spans:read
storage:system:read

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

Parameters

Parameter	Type	Description	In	Required
dt-client-context	string	The dt-client-context header is an optional string parameter used for monitoring purposes. When included in a request, it helps retrieve information about the execution of the query. It shouldn't hold sensitive information.	header	Optional
enrich	string	If set additional data will be available in the metadata section.	query	Optional
body	ExecuteRequest	All parameters have to be passed via JSON in the POST body.	body	Required

Request body objects

The `ExecuteRequest` object

Element	Type	Description	Required
defaultSamplingRatio	number	Default sampling ratio. By default no sampling is applied. No upper limit but will be normalized to a power of 10 less than or equal to 100000.	Optional
defaultScanLimitGbytes	integer	Default scan limit in gigabytes. Can be overridden in DQL. Default value is configured on application level (see documentation of FETCH command). Use -1 for no limit. Although this parameter has no explicit upper bound, other constraints such as timeouts, maxResultRecords, or maxResultBytes may still apply, as this API is not intended for large-scale data export.	Optional
defaultTimeframeEnd	string	The query timeframe 'end' timestamp in ISO-8601 or RFC3339 format. If the timeframe 'start' parameter is missing, the whole timeframe is ignored. Note that if a timeframe is specified within the query string (query) then it has precedence over this query request parameter.	Optional
defaultTimeframeStart	string	The query timeframe 'start' timestamp in ISO-8601 or RFC3339 format. If the timeframe 'end' parameter is missing, the whole timeframe is ignored. Note that if a timeframe is specified within the query string (query) then it has precedence over this query request parameter.	Optional
enablePreview	boolean	Request preview results. If a preview is available within the requestTimeoutMilliseconds, then it will be returned as part of the response.	Optional
enforceQueryConsumptionLimit	boolean	Boolean to indicate if the query consumption limit should be enforced	Optional
fetchTimeoutSeconds	integer	The time limit for fetching data. This is a soft limit as further data processing can happen after fetching. While this parameter has no explicit upper bound in the API, application-level default and maximum fetch timeout constraints still apply, and other limits such as maxResultRecords or maxResultBytes may take effect, as this API is not designed for large-scale data export.	Optional
filterSegments	FilterSegment[]	Represents a collection of filter segments.	Optional
includeContributions	boolean	Indicates whether bucket contribution information should be included in the query response metadata. When set to true, the response will contain details about how each bucket contributed to the query result.	Optional
includeTypes	boolean	Parameter to exclude the type information from the query result. In case not specified, the type information will be included.	Optional
locale	string	The query locale. If none specified, then a language/country neutral locale is chosen. The input values take the ISO-639 Language code with an optional ISO-3166 country code appended to it with an underscore. For instance, both values are valid 'en' or 'en_US'.	Optional
maxResultBytes	integer	The maximum number of bytes permitted for the serialized result. This limit applies only to records and is treated as a soft constraint - meaning that if the final record pushes the result size beyond this limit, that entire record will still be included in the response. While this parameter has no default value or explicit upper bound, other constraints such as timeouts or maxResultRecords may still take effect, as this API is not designed for large-scale data export.	Optional
maxResultRecords	integer	The maximum number of query result records to be returned. If this limit is exceeded, a warning notification will be included in the response. Although this parameter has no explicit upper bound, other constraints such as timeouts or maxResultBytes may still apply, as this API is not intended for large-scale data export.	Optional
pollingPromiseSeconds	integer	The number of seconds the client promises to send the next polling request after a response for a running query was sent. If the client does not poll within this time window, the query will be cancelled. Handling of the polling promise starts after request processing finished, so that requestTimeoutMilliseconds and pollingPromiseSeconds can be used without contradicting each other. A value of 0 means that the query will be cancelled immediately, without waiting for a poll request. No default value.	Optional
query	string	The full query string.	Required
queryOptions	QueryOptions	Query options enhance query functionality for Dynatrace internal services.	Optional
requestTimeoutMilliseconds	integer	The maximum time the response will be delayed to wait for a result. (This excludes the sending time and time spent in any services between the query-frontend and the client.) If the query finishes within the specified timeout, the query result is returned. Otherwise, the requestToken is returned, allowing polling for the result.	Optional
timezone	string	The query timezone. If none is specified, UTC is used as fallback. The list of valid input values matches that of the IANA Time Zone Database (TZDB). It accepts values in their canonical names like 'Europe/Paris', the abbreviated version like CET or the UTC offset format like '+01:00'	Optional

The `FilterSegments` object

Represents a collection of filter segments.

The `FilterSegment` object

A filter segment is identified by an ID. Each segment includes a list of variable definitions.

Element	Type	Description	Required
id	string	-	Required
variables	FilterSegmentVariableDefinition[]	-	Optional

The `FilterSegmentVariableDefinition` object

Defines a variable with a name and a list of values.

Element	Type	Description	Required
name	string	-	Required
values	string[]	-	Required

The `QueryOptions` object

Query options enhance query functionality for Dynatrace internal services.

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.

{
  "defaultSamplingRatio": 1,
  "defaultScanLimitGbytes": 100,
  "defaultTimeframeEnd": "2022-04-20T13:10:04.123Z",
  "defaultTimeframeStart": "2022-04-20T12:10:04.123Z",
  "enablePreview": true,
  "enforceQueryConsumptionLimit": true,
  "fetchTimeoutSeconds": 60,
  "filterSegments": null,
  "includeContributions": true,
  "includeTypes": true,
  "locale": "en_US",
  "maxResultBytes": 1000000,
  "maxResultRecords": 1000,
  "pollingPromiseSeconds": 1,
  "query": "fetch events \n| filter event.type == \"davis\" AND davis.status != \"CLOSED\" \n| fields timestamp, davis.title, davis.underMaintenance, davis.status \n| sort timestamp \n| limit 10",
  "queryOptions": null,
  "requestTimeoutMilliseconds": 1000,
  "timezone": "UTC"
}

Response

Response codes

Code	Type	Description
200	QueryStartResponse	The final status and results of the supplied query if it finished within a supplied requestTimeoutMilliseconds.
202	QueryStartResponse	The status of the query to start.
400	-	-
401	-	-
403	-	-
404	-	-
405	-	-
409	-	-
415	-	-
429	-	-
500	-	-
503	-	-
504	-	-

Response body objects

The `QueryStartResponse` object

The response when starting a query.

Element	Type	Description
progress	integer	The progress of the query from 0 to 100.
requestToken	string	The token returned by the POST query:execute call.
result	QueryResult	The result of the DQL query.
state	QueryState	Possible state of the query. The element can hold these values `NOT_STARTED` `RUNNING` `SUCCEEDED` `RESULT_GONE` `CANCELLED` `FAILED`
ttlSeconds	integer	Time to live in seconds.

The `QueryResult` object

The result of the DQL query.

Element	Type	Description
metadata	Metadata	Collects various bits of metadata information.
records	ResultRecord[]	List of records containing the result fields data.
types	RangedFieldTypes[]	The data types for the result records.

The `Metadata` object

Collects various bits of metadata information.

Element	Type	Description
grail	GrailMetadata	Collects various bits of metadata information.
metrics	MetricMetadata[]	-

The `GrailMetadata` object

Collects various bits of metadata information.

Element	Type	Description
analysisTimeframe	Timeframe	DQL data type timeframe.
canonicalQuery	string	The canonical form of the query. It has normalized spaces and canonical constructs.
contributions	Contributions	-
dqlVersion	string	The version of DQL that was used to process the query request.
executionTimeMilliseconds	integer	The time it took to execute the query.
flags	string[]	Flags indicating specific properties of the query execution, such as CLASSIC_ENTITY_MIGRATION_ADVISED.
locale	string	Effective locale for the query.
notifications	MetadataNotification[]	Collected messages during the execution of the query.
query	string	The submitted query.
queryId	string	The id of the query
sampled	boolean	True if sampling was used for at least one segment.
scannedBytes	integer	Number of scanned bytes during the query execution.
scannedDataPoints	integer	-
scannedRecords	integer	Number of scanned records during the query execution.
timezone	string	Effective timezone for the query.

The `Timeframe` object

DQL data type timeframe.

Element	Type	Description
end	string	The end time of the timeframe.
start	string	The start time of the timeframe.

The `Contributions` object

Element	Type	Description
buckets	BucketContribution[]	-

The `BucketContribution` object

Element	Type	Description
matchedRecordsRatio	number	-
name	string	-
scannedBytes	integer	-
table	string	-

The `MetadataNotification` object

The message that provides additional information about the execution of the query.

Element	Type	Description
arguments	string[]	The arguments for the message format.
message	string	The complete message of the notification.
messageFormat	string	The message format of the notification, string.format based
messageFormatSpecifierTypes	string[]	The corresponding DQL format specifier types for each format specifier used in the error message format.
notificationType	string	The notification type, e.g. LIMIT_ADDED.
severity	string	The severity of the notification, currently: INFO, WARN, ERROR.
syntaxPosition	TokenPosition	The position of a token in a query string used for errors and notification to map the message to a specific part of the query.

The `TokenPosition` object

The position of a token in a query string used for errors and notification to map the message to a specific part of the query.

Element	Type	Description
end	PositionInfo	The exact position in the query string.
start	PositionInfo	The exact position in the query string.

The `PositionInfo` object

The exact position in the query string.

Element	Type	Description
column	integer	Query position column zero based index.
index	integer	Query position index.
line	integer	Query position line zero based index.

The `MetricMetadata` object

An object that defines additional metric metadata.

Element	Type	Description
aggregation	string	Metadata about the aggregation type.
description	string	The description of the metadata.
displayName	string	The display name of the metadata.
fieldName	string	The name of the associated field used in the query.
metric.key	string	The metric key.
rate	string	The specified rate normalization parameter.
rollup	string	Metadata about the rollup type.
scalar	boolean	Indicates whether the scalar parameter was set to true in the timeseries aggregation function.
shifted	boolean	Indicates if the shifted parameter was used.
unit	string	The unit used.

The `ResultRecord` object

Single record that contains the result fields.

The `ResultRecordValue` object

Single result field of a record.

The `GeoPoint` object

DQL data type representing a geolocation point.

Element	Type	Description
latitude	number	The coordinate that specifies the north-south position of a point on the surface of the earth.
longitude	number	The coordinate that specifies the east-west position of a point on the surface of the earth.

The `RangedFieldTypes` object

The field type in range.

Element	Type	Description
indexRange	integer[]	The range of elements at use this type in arrays (null for records).
mappings	object	The mapping between the field name and data type.

The `FieldType` object

The possible type of a field in DQL.

Element	Type	Description
type	string	- The element can hold these values `boolean` `string` `double` `long` `timestamp` `timeframe` `duration` `binary` `ip_address` `geo_point` `array` `record` `uid` `smartscape_id` `undefined`
types	RangedFieldTypes[]	-

The `QueryState` object

Possible state of the query.

Response body JSON models

{
  "progress": 100,
  "result": {
    "metadata": {
      "grail": {
        "analysisTimeframe": {
          "end": "2023-03-10T11:02:00.705980000Z",
          "start": "2023-03-10T09:02:00.705980000Z"
        },
        "dqlVersion": "V1_0",
        "executionTimeMilliseconds": 18,
        "locale": "",
        "query": "fetch ...",
        "queryId": "92918dae-c2f9-4c98-b278-dc42adcc5954",
        "timezone": "Z"
      }
    },
    "records": [
      {
        "davis.status": "OPEN",
        "davis.title": "Http monitor global outage",
        "davis.underMaintenance": "false",
        "timestamp": "2022-03-17T08:00:01.231000000Z"
      },
      {
        "davis.status": "OPEN",
        "davis.title": "Http monitor global outage",
        "davis.underMaintenance": "false",
        "timestamp": "2022-03-17T08:00:01.231000000Z"
      },
      {
        "davis.status": "OPEN",
        "davis.title": "Http monitor global outage",
        "davis.underMaintenance": "false",
        "timestamp": "2022-03-17T08:00:01.231000000Z"
      },
      {
        "davis.status": "OPEN",
        "davis.title": "Http monitor global outage",
        "davis.underMaintenance": "false",
        "timestamp": "2022-03-17T08:00:01.231000000Z"
      }
    ],
    "types": [
      {
        "indexRange": [
          0,
          3
        ],
        "mappings": {
          "davis.status": {
            "type": "string"
          },
          "davis.title": {
            "type": "string"
          },
          "davis.underMaintenance": {
            "type": "string"
          },
          "timestamp": {
            "type": "timestamp"
          }
        }
      }
    ]
  },
  "state": "SUCCEEDED"
}

Execute a query

Latest Dynatrace
Reference
Published Oct 13, 2026

Start a DQL query in Dynatrace Query API and return the initial status, with results when the query finishes within the request window.


POST	SaaS	`https://{your-environment-id}.apps.dynatrace.com/platform/storage/query/v1/query:execute`

Overview

For information about the required permissions see the Bucket and table permissions in Grail documentation.

Executes a query and returns a list of records.

For details about the query language see the Dynatrace Query Language documentation.

The response format

The result has two main sections:

The 'records' section contains the individual records, where each record consists of a set of fields and their corresponding values.
The 'types' section describes the corresponding data types that a record field has.

A field part of a record with index 'i' will find its corresponding field type by first locating the bucket that satisfies:

startIndex <= i <= endIndex

Once the bucket is found the 'mappings' object has an entry for all the fields that are part of that record with index 'i'.

Authentication

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

storage:bizevents:read
storage:buckets:read
storage:entities:read
storage:events:read
storage:fieldsets:read
storage:logs:read
storage:metrics:read
storage:spans:read
storage:system:read

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

Parameters

Parameter	Type	Description	In	Required
dt-client-context	string	The dt-client-context header is an optional string parameter used for monitoring purposes. When included in a request, it helps retrieve information about the execution of the query. It shouldn't hold sensitive information.	header	Optional
enrich	string	If set additional data will be available in the metadata section.	query	Optional
body	ExecuteRequest	All parameters have to be passed via JSON in the POST body.	body	Required

Request body objects

The `ExecuteRequest` object

Element	Type	Description	Required
defaultSamplingRatio	number	Default sampling ratio. By default no sampling is applied. No upper limit but will be normalized to a power of 10 less than or equal to 100000.	Optional
defaultScanLimitGbytes	integer	Default scan limit in gigabytes. Can be overridden in DQL. Default value is configured on application level (see documentation of FETCH command). Use -1 for no limit. Although this parameter has no explicit upper bound, other constraints such as timeouts, maxResultRecords, or maxResultBytes may still apply, as this API is not intended for large-scale data export.	Optional
defaultTimeframeEnd	string	The query timeframe 'end' timestamp in ISO-8601 or RFC3339 format. If the timeframe 'start' parameter is missing, the whole timeframe is ignored. Note that if a timeframe is specified within the query string (query) then it has precedence over this query request parameter.	Optional
defaultTimeframeStart	string	The query timeframe 'start' timestamp in ISO-8601 or RFC3339 format. If the timeframe 'end' parameter is missing, the whole timeframe is ignored. Note that if a timeframe is specified within the query string (query) then it has precedence over this query request parameter.	Optional
enablePreview	boolean	Request preview results. If a preview is available within the requestTimeoutMilliseconds, then it will be returned as part of the response.	Optional
enforceQueryConsumptionLimit	boolean	Boolean to indicate if the query consumption limit should be enforced	Optional
fetchTimeoutSeconds	integer	The time limit for fetching data. This is a soft limit as further data processing can happen after fetching. While this parameter has no explicit upper bound in the API, application-level default and maximum fetch timeout constraints still apply, and other limits such as maxResultRecords or maxResultBytes may take effect, as this API is not designed for large-scale data export.	Optional
filterSegments	FilterSegment[]	Represents a collection of filter segments.	Optional
includeContributions	boolean	Indicates whether bucket contribution information should be included in the query response metadata. When set to true, the response will contain details about how each bucket contributed to the query result.	Optional
includeTypes	boolean	Parameter to exclude the type information from the query result. In case not specified, the type information will be included.	Optional
locale	string	The query locale. If none specified, then a language/country neutral locale is chosen. The input values take the ISO-639 Language code with an optional ISO-3166 country code appended to it with an underscore. For instance, both values are valid 'en' or 'en_US'.	Optional
maxResultBytes	integer	The maximum number of bytes permitted for the serialized result. This limit applies only to records and is treated as a soft constraint - meaning that if the final record pushes the result size beyond this limit, that entire record will still be included in the response. While this parameter has no default value or explicit upper bound, other constraints such as timeouts or maxResultRecords may still take effect, as this API is not designed for large-scale data export.	Optional
maxResultRecords	integer	The maximum number of query result records to be returned. If this limit is exceeded, a warning notification will be included in the response. Although this parameter has no explicit upper bound, other constraints such as timeouts or maxResultBytes may still apply, as this API is not intended for large-scale data export.	Optional
pollingPromiseSeconds	integer	The number of seconds the client promises to send the next polling request after a response for a running query was sent. If the client does not poll within this time window, the query will be cancelled. Handling of the polling promise starts after request processing finished, so that requestTimeoutMilliseconds and pollingPromiseSeconds can be used without contradicting each other. A value of 0 means that the query will be cancelled immediately, without waiting for a poll request. No default value.	Optional
query	string	The full query string.	Required
queryOptions	QueryOptions	Query options enhance query functionality for Dynatrace internal services.	Optional
requestTimeoutMilliseconds	integer	The maximum time the response will be delayed to wait for a result. (This excludes the sending time and time spent in any services between the query-frontend and the client.) If the query finishes within the specified timeout, the query result is returned. Otherwise, the requestToken is returned, allowing polling for the result.	Optional
timezone	string	The query timezone. If none is specified, UTC is used as fallback. The list of valid input values matches that of the IANA Time Zone Database (TZDB). It accepts values in their canonical names like 'Europe/Paris', the abbreviated version like CET or the UTC offset format like '+01:00'	Optional

The `FilterSegments` object

Represents a collection of filter segments.

The `FilterSegment` object

A filter segment is identified by an ID. Each segment includes a list of variable definitions.

Element	Type	Description	Required
id	string	-	Required
variables	FilterSegmentVariableDefinition[]	-	Optional

The `FilterSegmentVariableDefinition` object

Defines a variable with a name and a list of values.

Element	Type	Description	Required
name	string	-	Required
values	string[]	-	Required

The `QueryOptions` object

Query options enhance query functionality for Dynatrace internal services.

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.

{
  "defaultSamplingRatio": 1,
  "defaultScanLimitGbytes": 100,
  "defaultTimeframeEnd": "2022-04-20T13:10:04.123Z",
  "defaultTimeframeStart": "2022-04-20T12:10:04.123Z",
  "enablePreview": true,
  "enforceQueryConsumptionLimit": true,
  "fetchTimeoutSeconds": 60,
  "filterSegments": null,
  "includeContributions": true,
  "includeTypes": true,
  "locale": "en_US",
  "maxResultBytes": 1000000,
  "maxResultRecords": 1000,
  "pollingPromiseSeconds": 1,
  "query": "fetch events \n| filter event.type == \"davis\" AND davis.status != \"CLOSED\" \n| fields timestamp, davis.title, davis.underMaintenance, davis.status \n| sort timestamp \n| limit 10",
  "queryOptions": null,
  "requestTimeoutMilliseconds": 1000,
  "timezone": "UTC"
}

Response

Response codes

Code	Type	Description
200	QueryStartResponse	The final status and results of the supplied query if it finished within a supplied requestTimeoutMilliseconds.
202	QueryStartResponse	The status of the query to start.
400	-	-
401	-	-
403	-	-
404	-	-
405	-	-
409	-	-
415	-	-
429	-	-
500	-	-
503	-	-
504	-	-

Response body objects

The `QueryStartResponse` object

The response when starting a query.

Element	Type	Description
progress	integer	The progress of the query from 0 to 100.
requestToken	string	The token returned by the POST query:execute call.
result	QueryResult	The result of the DQL query.
state	QueryState	Possible state of the query. The element can hold these values `NOT_STARTED` `RUNNING` `SUCCEEDED` `RESULT_GONE` `CANCELLED` `FAILED`
ttlSeconds	integer	Time to live in seconds.

The `QueryResult` object

The result of the DQL query.

Element	Type	Description
metadata	Metadata	Collects various bits of metadata information.
records	ResultRecord[]	List of records containing the result fields data.
types	RangedFieldTypes[]	The data types for the result records.

The `Metadata` object

Collects various bits of metadata information.

Element	Type	Description
grail	GrailMetadata	Collects various bits of metadata information.
metrics	MetricMetadata[]	-

The `GrailMetadata` object

Collects various bits of metadata information.

Element	Type	Description
analysisTimeframe	Timeframe	DQL data type timeframe.
canonicalQuery	string	The canonical form of the query. It has normalized spaces and canonical constructs.
contributions	Contributions	-
dqlVersion	string	The version of DQL that was used to process the query request.
executionTimeMilliseconds	integer	The time it took to execute the query.
flags	string[]	Flags indicating specific properties of the query execution, such as CLASSIC_ENTITY_MIGRATION_ADVISED.
locale	string	Effective locale for the query.
notifications	MetadataNotification[]	Collected messages during the execution of the query.
query	string	The submitted query.
queryId	string	The id of the query
sampled	boolean	True if sampling was used for at least one segment.
scannedBytes	integer	Number of scanned bytes during the query execution.
scannedDataPoints	integer	-
scannedRecords	integer	Number of scanned records during the query execution.
timezone	string	Effective timezone for the query.

The `Timeframe` object

DQL data type timeframe.

Element	Type	Description
end	string	The end time of the timeframe.
start	string	The start time of the timeframe.

The `Contributions` object

Element	Type	Description
buckets	BucketContribution[]	-

The `BucketContribution` object

Element	Type	Description
matchedRecordsRatio	number	-
name	string	-
scannedBytes	integer	-
table	string	-

The `MetadataNotification` object

The message that provides additional information about the execution of the query.

Element	Type	Description
arguments	string[]	The arguments for the message format.
message	string	The complete message of the notification.
messageFormat	string	The message format of the notification, string.format based
messageFormatSpecifierTypes	string[]	The corresponding DQL format specifier types for each format specifier used in the error message format.
notificationType	string	The notification type, e.g. LIMIT_ADDED.
severity	string	The severity of the notification, currently: INFO, WARN, ERROR.
syntaxPosition	TokenPosition	The position of a token in a query string used for errors and notification to map the message to a specific part of the query.

The `TokenPosition` object

The position of a token in a query string used for errors and notification to map the message to a specific part of the query.

Element	Type	Description
end	PositionInfo	The exact position in the query string.
start	PositionInfo	The exact position in the query string.

The `PositionInfo` object

The exact position in the query string.

Element	Type	Description
column	integer	Query position column zero based index.
index	integer	Query position index.
line	integer	Query position line zero based index.

The `MetricMetadata` object

An object that defines additional metric metadata.

Element	Type	Description
aggregation	string	Metadata about the aggregation type.
description	string	The description of the metadata.
displayName	string	The display name of the metadata.
fieldName	string	The name of the associated field used in the query.
metric.key	string	The metric key.
rate	string	The specified rate normalization parameter.
rollup	string	Metadata about the rollup type.
scalar	boolean	Indicates whether the scalar parameter was set to true in the timeseries aggregation function.
shifted	boolean	Indicates if the shifted parameter was used.
unit	string	The unit used.

The `ResultRecord` object

Single record that contains the result fields.

The `ResultRecordValue` object

Single result field of a record.

The `GeoPoint` object

DQL data type representing a geolocation point.

Element	Type	Description
latitude	number	The coordinate that specifies the north-south position of a point on the surface of the earth.
longitude	number	The coordinate that specifies the east-west position of a point on the surface of the earth.

The `RangedFieldTypes` object

The field type in range.

Element	Type	Description
indexRange	integer[]	The range of elements at use this type in arrays (null for records).
mappings	object	The mapping between the field name and data type.

The `FieldType` object

The possible type of a field in DQL.

Element	Type	Description
type	string	- The element can hold these values `boolean` `string` `double` `long` `timestamp` `timeframe` `duration` `binary` `ip_address` `geo_point` `array` `record` `uid` `smartscape_id` `undefined`
types	RangedFieldTypes[]	-

The `QueryState` object

Possible state of the query.

Response body JSON models

{
  "progress": 100,
  "result": {
    "metadata": {
      "grail": {
        "analysisTimeframe": {
          "end": "2023-03-10T11:02:00.705980000Z",
          "start": "2023-03-10T09:02:00.705980000Z"
        },
        "dqlVersion": "V1_0",
        "executionTimeMilliseconds": 18,
        "locale": "",
        "query": "fetch ...",
        "queryId": "92918dae-c2f9-4c98-b278-dc42adcc5954",
        "timezone": "Z"
      }
    },
    "records": [
      {
        "davis.status": "OPEN",
        "davis.title": "Http monitor global outage",
        "davis.underMaintenance": "false",
        "timestamp": "2022-03-17T08:00:01.231000000Z"
      },
      {
        "davis.status": "OPEN",
        "davis.title": "Http monitor global outage",
        "davis.underMaintenance": "false",
        "timestamp": "2022-03-17T08:00:01.231000000Z"
      },
      {
        "davis.status": "OPEN",
        "davis.title": "Http monitor global outage",
        "davis.underMaintenance": "false",
        "timestamp": "2022-03-17T08:00:01.231000000Z"
      },
      {
        "davis.status": "OPEN",
        "davis.title": "Http monitor global outage",
        "davis.underMaintenance": "false",
        "timestamp": "2022-03-17T08:00:01.231000000Z"
      }
    ],
    "types": [
      {
        "indexRange": [
          0,
          3
        ],
        "mappings": {
          "davis.status": {
            "type": "string"
          },
          "davis.title": {
            "type": "string"
          },
          "davis.underMaintenance": {
            "type": "string"
          },
          "timestamp": {
            "type": "timestamp"
          }
        }
      }
    ]
  },
  "state": "SUCCEEDED"
}

Execute a query

Overview

The response format

Authentication

Parameters

Request body objects

The ExecuteRequest object

The FilterSegments object

The FilterSegment object

The FilterSegmentVariableDefinition object

The QueryOptions object

Request body JSON model

Response

Response codes

Response body objects

The QueryStartResponse object

The QueryResult object

The Metadata object

The GrailMetadata object

The Timeframe object

The Contributions object

The BucketContribution object

The MetadataNotification object

The TokenPosition object

The PositionInfo object

The MetricMetadata object

The ResultRecord object

The ResultRecordValue object

The GeoPoint object

The RangedFieldTypes object

The FieldType object

The QueryState object

Response body JSON models

Execute a query

Overview

The response format

Authentication

Parameters

Request body objects

The ExecuteRequest object

The FilterSegments object

The FilterSegment object

The FilterSegmentVariableDefinition object

The QueryOptions object

Request body JSON model

Response

Response codes

Response body objects

The QueryStartResponse object

The QueryResult object

The Metadata object

The GrailMetadata object

The Timeframe object

The Contributions object

The BucketContribution object

The MetadataNotification object

The TokenPosition object

The PositionInfo object

The MetricMetadata object

The ResultRecord object

The ResultRecordValue object

The GeoPoint object

The RangedFieldTypes object

The FieldType object

The QueryState object

Response body JSON models

The `ExecuteRequest` object

The `FilterSegments` object

The `FilterSegment` object

The `FilterSegmentVariableDefinition` object

The `QueryOptions` object

The `QueryStartResponse` object

The `QueryResult` object

The `Metadata` object

The `GrailMetadata` object

The `Timeframe` object

The `Contributions` object

The `BucketContribution` object

The `MetadataNotification` object

The `TokenPosition` object

The `PositionInfo` object

The `MetricMetadata` object

The `ResultRecord` object

The `ResultRecordValue` object

The `GeoPoint` object

The `RangedFieldTypes` object

The `FieldType` object

The `QueryState` object

The `ExecuteRequest` object

The `FilterSegments` object

The `FilterSegment` object

The `FilterSegmentVariableDefinition` object

The `QueryOptions` object

The `QueryStartResponse` object

The `QueryResult` object

The `Metadata` object

The `GrailMetadata` object

The `Timeframe` object

The `Contributions` object

The `BucketContribution` object

The `MetadataNotification` object

The `TokenPosition` object

The `PositionInfo` object

The `MetricMetadata` object

The `ResultRecord` object

The `ResultRecordValue` object

The `GeoPoint` object

The `RangedFieldTypes` object

The `FieldType` object

The `QueryState` object