Try it free

Execute an analyzer

  • Latest Dynatrace
  • Reference
  • Published Oct 13, 2026

Execute an analyzer in Dynatrace with the Davis AI Predictive and Causal API, starting an asynchronous run and returning the final result or a request token.

POSTSaaShttps://{your-environment-id}.apps.dynatrace.com/platform/davis/analyzers/v1/analyzers/{analyzer-name}:execute

Overview

The analyzer execution is started asynchronously. If the result is not available after the specified timeout, a request token is returned to poll for the result. Otherwise, the final result is directly available and no request token is returned.

Depending on the chosen analyzer and the analyzer input, additional scopes might be required, e.g. storage:buckets:read and storage:metrics:read to enable the analyzer to read time series data from Grail™.

Authentication

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

Parameters

ParameterTypeDescriptionInRequired
analyzer-namestring

The name of the analyzer.

pathRequired
timeout-secondsinteger

The amount of seconds to wait for the response to be returned.

The timeout controls how long the client is willing to wait, while the analyzer execution continues running until it has finished or is cancelled.

queryOptional
enable-previewboolean

Indicates if analyzer results should preview already created outputs while the analyzer is still running.

Set to false if only the final result is needed.

queryOptional
bodyAnalyzerData

The map of actual data matching the input and output definition of the analyzer.

bodyRequired

Request body objects

The AnalyzerData object

The map of actual data matching the input and output definition of the analyzer.

ElementTypeDescriptionRequired
generalParametersAnalyzerGeneralParameters

Parameters that are present in all analyzer input parameter definitions.

Optional

The object

The AnalyzerGeneralParameters object

Parameters that are present in all analyzer input parameter definitions.

ElementTypeDescriptionRequired
timeframeTimeframe-Optional
resolveDimensionalQueryDataboolean-Optional
logVerbosityAnalyzerExecutionLogLevel

Determines the severity of the log.

The element can hold these values
  • TRACING
  • INFO
  • WARNING
  • SEVERE
Optional

The Timeframe object

ElementTypeDescriptionRequired
startTimestring

Specify the start time in either absolute or relative format. For absolute format, use the ISO 8601 format (yyyy-MM-ddTHH:mm:ssZ). For relative format, use 'now' for the current time or apply an offset with the available units: 's' for seconds, 'm' for minutes, 'h' for hours, and 'd' for days. For example, use 'now-2h' or '-2h' for a relative offset of 2 hours.

Required
endTimestring

Specify the end time in either absolute or relative format. For absolute format, use the ISO 8601 format (yyyy-MM-ddTHH:mm:ssZ). For relative format, use 'now' for the current time or apply an offset with the available units: 's' for seconds, 'm' for minutes, 'h' for hours, and 'd' for days. For example, use 'now-2h' or '-2h' for a relative offset of 2 hours. If not specified, defaults to now.

Optional

The AnalyzerExecutionLogLevel object

Determines the severity of the log.

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.

{
  "timeSeriesData": {
    "expression": "timeseries avg(dt.host.cpu.usage)"
  },
  "forecastHorizon": 10
}

Response

Response codes

CodeTypeDescription
200AnalyzerExecuteResult

The final analyzer result and execution status.

202AnalyzerExecuteResult

The current analyzer execution status and a request token and time-to-live (TTL) to continue polling the result with.

400AnalyzerErrorEnvelope

Invalid or malformed request.

403AnalyzerErrorEnvelope

Insufficient permissions.

404AnalyzerErrorEnvelope

No analyzer available with the requested name.

4XXAnalyzerErrorEnvelope

Client error.

5XXAnalyzerErrorEnvelope

Internal server error.

Response body objects

The AnalyzerExecuteResult object

Result of the analyzer execution.

ElementTypeDescription
requestTokenstring

The request token is returned when starting a long-running analyzer execution. It can be used to do follow-up operations like polling and cancelling.

ttlInSecondsinteger

Time-to-live until the result is not available anymore.

resultAnalyzerResult-

The AnalyzerResult object

ElementTypeDescription
resultIdstring

The uniquely identifying ID of the result. Used for logging.

resultStatusstring-
The element can hold these values
  • SUCCESSFUL
  • SUCCESSFUL_WITH_WARNINGS
  • FAILED
executionStatusstring-
The element can hold these values
  • RUNNING
  • ABORTED
  • COMPLETED
inputAnalyzerData

The map of actual data matching the input and output definition of the analyzer.

logsAnalyzerExecutionLog[]-
outputAnalyzerOutput[]-
dataAnalyzerDimensionalData[]-
metadataAnalyzerMetadata

Metadata about the analyzer execution.

The AnalyzerInput object

The input is specific to an analyzer. Get the definition of the analyzer to retrieve the required input structure.

The AnalyzerData object

The map of actual data matching the input and output definition of the analyzer.

The object

The AnalyzerGeneralParameters object

Parameters that are present in all analyzer input parameter definitions.

ElementTypeDescription
timeframeTimeframe-
resolveDimensionalQueryDataboolean-
logVerbosityAnalyzerExecutionLogLevel

Determines the severity of the log.

The element can hold these values
  • TRACING
  • INFO
  • WARNING
  • SEVERE

The Timeframe object

ElementTypeDescription
startTimestring

Specify the start time in either absolute or relative format. For absolute format, use the ISO 8601 format (yyyy-MM-ddTHH:mm:ssZ). For relative format, use 'now' for the current time or apply an offset with the available units: 's' for seconds, 'm' for minutes, 'h' for hours, and 'd' for days. For example, use 'now-2h' or '-2h' for a relative offset of 2 hours.

endTimestring

Specify the end time in either absolute or relative format. For absolute format, use the ISO 8601 format (yyyy-MM-ddTHH:mm:ssZ). For relative format, use 'now' for the current time or apply an offset with the available units: 's' for seconds, 'm' for minutes, 'h' for hours, and 'd' for days. For example, use 'now-2h' or '-2h' for a relative offset of 2 hours. If not specified, defaults to now.

The AnalyzerExecutionLogLevel object

Determines the severity of the log.

The AnalyzerExecutionLog object

ElementTypeDescription
levelAnalyzerExecutionLogLevel

Determines the severity of the log.

The element can hold these values
  • TRACING
  • INFO
  • WARNING
  • SEVERE
messagestring-
pathstring

A path pointing to the source of the error in the input. The format of the path follows the JSON path specification.

The AnalyzerOutput object

The output is specific to an analyzer. Get the definition of the analyzer to retrieve the required output structure.

The AnalyzerOutputSystemParameters object

Parameters that are present in all analyzer output parameter definitions.

ElementTypeDescription
logsAnalyzerOutputLog[]-

The AnalyzerOutputLog object

ElementTypeDescription
levelAnalyzerOutputLogLevel-
The element can hold these values
  • TRACING
  • INFO
  • WARNING
messagestring-

The AnalyzerOutputLogLevel object

The AnalyzerDimensionalData object

A list of resolved dimensional data.

ElementTypeDescription
queryDimensionQuery

A query for dimensional data such as timeseries, entities, or logs.

valueobject

The resolved value of the dimensional query.

typestring

The type of the dimensional query.

The element can hold these values
  • entityId
  • timeseriesArray

The DimensionQuery object

A query for dimensional data such as timeseries, entities, or logs.

The object

The AnalyzerMetadata object

Metadata about the analyzer execution.

ElementTypeDescription
grailAnalyzerMetadataGrail

Grail-specific metadata about the analyzer execution.

The AnalyzerMetadataGrail object

Grail-specific metadata about the analyzer execution.

ElementTypeDescription
scannedBytesinteger

The total number of bytes scanned in all Grail queries that were run as part of the analyzer execution.

The AnalyzerErrorEnvelope object

ElementTypeDescription
errorAnalyzerError

The error that is returned for unsuccessful responses.

The AnalyzerError object

The error that is returned for unsuccessful responses.

ElementTypeDescription
codeinteger

The HTTP status code of the error.

messagestring-
detailsAnalyzerErrorDetails-

The AnalyzerErrorDetails object

ElementTypeDescription
constraintViolationsConstraintViolation[]-

The ConstraintViolation object

A constraint violation indicating why an error has occurred.

The AnalyzerExecutionLog object

ElementTypeDescription
levelAnalyzerExecutionLogLevel

Determines the severity of the log.

The element can hold these values
  • TRACING
  • INFO
  • WARNING
  • SEVERE
messagestring-
pathstring

A path pointing to the source of the error in the input. The format of the path follows the JSON path specification.

The AnalyzerExecutionLogLevel object

Determines the severity of the log.

Response body JSON models

{
  "result": {
    "resultId": "e4fd114dba084fd9",
    "resultStatus": "SUCCESSFUL",
    "executionStatus": "COMPLETED",
    "input": {
      "generalParameters": {
        "timeframe": null,
        "logVerbosity": "WARNING",
        "resolveDimensionalQueryData": false
      },
      "forecastHorizon": 10,
      "timeSeriesData": {
        "expression": "timeseries avg(dt.host.cpu.usage)"
      },
      "coverageProbability": 0.9,
      "nPaths": 200
    },
    "output": [
      {
        "timeSeriesDataWithPredictions": {
          "records": [
            {
              "dt.davis.forecast:lower": [
                30.06526744477648,
                30.469005693579895,
                30.641933747981863,
                31.266633573314543,
                31.018440163566783,
                30.832801407033784,
                30.127440957160143,
                31.63919313816315,
                30.835958661995043,
                29.933730613970294
              ],
              "dt.davis.forecast:upper": [
                44.250848540072205,
                45.32430402865753,
                45.124536344034915,
                44.62291543678966,
                44.48090669793653,
                43.913223381905276,
                42.98826349674527,
                43.88073356829243,
                44.52412625492842,
                42.32966344989203
              ],
              "dt.davis.forecast:point": [
                37.06917039490001,
                38.068881128336955,
                37.47658985279556,
                37.24624051130464,
                37.24271470069583,
                37.658750126351876,
                37.20201557131627,
                38.2574100893675,
                36.96177127701703,
                37.83834653098133
              ],
              "interval": "60000000000",
              "timeframe": {
                "end": "2023-03-22T12:19Z",
                "start": "2023-03-22T12:09Z"
              },
              "dt.davis.meta.dataName": "avg(dt.host.cpu.usage)"
            }
          ],
          "types": [
            {
              "indexRange": [
                0,
                0
              ],
              "mappings": {
                "dt.davis.forecast:lower": {
                  "type": "array",
                  "types": [
                    {
                      "indexRange": [
                        0,
                        9
                      ],
                      "mappings": {
                        "element": {
                          "type": "double"
                        }
                      }
                    }
                  ]
                },
                "timeframe": {
                  "type": "timeframe"
                },
                "dt.davis.meta.dataName": {
                  "type": "string"
                },
                "dt.davis.forecast:upper": {
                  "type": "array",
                  "types": [
                    {
                      "indexRange": [
                        0,
                        9
                      ],
                      "mappings": {
                        "element": {
                          "type": "double"
                        }
                      }
                    }
                  ]
                },
                "dt.davis.forecast:point": {
                  "type": "array",
                  "types": [
                    {
                      "indexRange": [
                        0,
                        9
                      ],
                      "mappings": {
                        "element": {
                          "type": "double"
                        }
                      }
                    }
                  ]
                },
                "interval": {
                  "type": "duration"
                }
              }
            }
          ]
        },
        "forecastQualityAssessment": "valid",
        "analysisStatus": "OK",
        "analyzedTimeSeriesQuery": {
          "expression": "timeseries avg(dt.host.cpu.usage) | ",
          "timeframe": {
            "startTime": "2023-03-22T10:08:48.997Z",
            "endTime": "2023-03-22T12:08:48.997Z"
          }
        }
      }
    ]
  }
}
{
  "error": {
    "code": 400,
    "message": "string",
    "details": {
      "constraintViolations": [
        {
          "level": "TRACING",
          "message": "string",
          "path": "string"
        }
      ]
    }
  }
}
Related tags
Platform APIDynatrace PlatformAI Observability