--- title: Investigate a timeseries anomaly description: Datadog, the leading service for cloud-scale monitoring. breadcrumbs: Docs > API Reference > Timeseries Anomaly Investigations --- > For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt). # Investigate a timeseries anomaly{% #investigate-a-timeseries-anomaly %} Copy pageCopied {% tab title="v2" %} **Note**: This endpoint is in preview and is subject to change. If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help/). | Datadog site | API endpoint | | ----------------- | --------------------------------------------------------------------------- | | ap1.datadoghq.com | POST https://api.ap1.datadoghq.com/api/v2/timeseries-anomaly-investigations | | ap2.datadoghq.com | POST https://api.ap2.datadoghq.com/api/v2/timeseries-anomaly-investigations | | app.datadoghq.eu | POST https://api.datadoghq.eu/api/v2/timeseries-anomaly-investigations | | app.ddog-gov.com | POST https://api.ddog-gov.com/api/v2/timeseries-anomaly-investigations | | us2.ddog-gov.com | POST https://api.us2.ddog-gov.com/api/v2/timeseries-anomaly-investigations | | uk1.datadoghq.com | POST https://api.uk1.datadoghq.com/api/v2/timeseries-anomaly-investigations | | app.datadoghq.com | POST https://api.datadoghq.com/api/v2/timeseries-anomaly-investigations | | us3.datadoghq.com | POST https://api.us3.datadoghq.com/api/v2/timeseries-anomaly-investigations | | us5.datadoghq.com | POST https://api.us5.datadoghq.com/api/v2/timeseries-anomaly-investigations | ### Overview Investigates a metrics timeseries request for its most significant anomaly and returns deterministic findings. Metrics queries with or without grouping are supported. This API version accepts exactly one request and returns at most one anomaly. This endpoint requires all of the following permissions: `timeseries_query``metrics_read` OAuth apps require the `timeseries_query, metrics_read` authorization [scope](https://docs.datadoghq.com/api/latest/scopes.md#timeseries-anomaly-investigations) to access this endpoint. ### Request #### Body Data (required) Metrics timeseries request to investigate. The request body must not exceed 2 MiB. {% tab title="Model" %} | Parent field | Field | Type | Description | | ------------ | ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | data [*required*] | object | JSON:API resource containing an anomaly investigation request. | | data | attributes [*required*] | object | Attributes of an anomaly investigation request. | | attributes | requests [*required*] | [object] | Timeseries requests to investigate. This API version accepts exactly one request. | | requests | formulas [*required*] | [object] | Formulas to evaluate. Each formula may contain an explicit `anomalies()` call or a supported metrics expression. | | formulas | formula [*required*] | string | Formula expression referencing one or more named queries. | | formulas | limit | object | Optional formula limit accepted for compatibility with Timeseries API requests. Formula limits have no effect on timeseries queries. | | limit | count | int64 | Requested result limit. This field has no effect on a timeseries anomaly investigation. | | limit | order | enum | Sort order used when applying a formula series limit. Allowed enum values: `asc,desc` | | requests | from [*required*] | int64 | Start of the investigation time window in milliseconds since the Unix epoch. | | requests | interval | int64 | Optional requested aggregation interval in milliseconds. | | requests | queries [*required*] | [object] | Metrics queries referenced by the formulas. | | queries | aggregator | string | Optional scalar aggregator accepted for request compatibility. This field is ignored for timeseries queries. | | queries | cross_org_uuids | [string] | Optional organization UUID used for a cross-organization query. Each query accepts at most one UUID; use separate queries for separate organizations. Influential-tag analysis is currently unsupported for cross-organization queries, but anomaly detection still runs. | | queries | data_source [*required*] | enum | Data source for an anomaly investigation query. Allowed enum values: `metrics` | | queries | name [*required*] | string | Name used to reference this query from formulas. | | queries | query [*required*] | string | Datadog metrics query expression. | | requests | to [*required*] | int64 | End of the investigation time window in milliseconds since the Unix epoch. Must be later than `from`. | | data | type [*required*] | enum | Resource type for a timeseries anomaly investigation. Allowed enum values: `timeseries_anomaly_investigation` | {% /tab %} {% tab title="Example" %} ```json { "data": { "attributes": { "requests": [ { "formulas": [ { "formula": "anomalies(query1, 'agile', 3)", "limit": { "count": 10, "order": "desc" } } ], "from": 1754406000000, "interval": 60000, "queries": [ { "aggregator": "avg", "cross_org_uuids": [ "00000000-0000-0000-0000-000000000000" ], "data_source": "metrics", "name": "query1", "query": "avg:system.cpu.user{env:prod} by {service}" } ], "to": 1754423940000 } ] }, "type": "timeseries_anomaly_investigation" } } ``` {% /tab %} ### Response {% tab title="200" %} OK {% tab title="Model" %} Response containing the anomaly investigation results and timeseries metadata. | Parent field | Field | Type | Description | | ---------------------- | -------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | data [*required*] | object | JSON:API resource containing anomaly investigation results. | | data | attributes [*required*] | object | Attributes of an anomaly investigation response. | | attributes | results [*required*] | [object] | Results returned in the same order as the submitted requests. This API version returns exactly one result. | | results | anomalies [*required*] | [object] | Detected anomalies. This API version returns at most one anomaly. | | anomalies | anomaly_detection [*required*] | object | Anomaly detection configuration used for the result. | | anomaly_detection | configuration_source [*required*] | enum | Source of the anomaly detection configuration. Allowed enum values: `request_formula,watchdog_explains_default` | | anomaly_detection | profile [*required*] | string | Applied Watchdog Explains profile, or null when the request supplied an explicit `anomalies()` formula. The current Watchdog profile is `watchdog_explains_v1`. | | anomalies | detected_interval [*required*] | object | Inclusive time interval in milliseconds since the Unix epoch. | | detected_interval | end [*required*] | int64 | Timestamp of the final point in the interval. | | detected_interval | start [*required*] | int64 | Inclusive start of the interval. | | anomalies | display_interval [*required*] | object | Inclusive time interval in milliseconds since the Unix epoch. | | display_interval | end [*required*] | int64 | Timestamp of the final point in the interval. | | display_interval | start [*required*] | int64 | Inclusive start of the interval. | | anomalies | findings [*required*] | [ ] | Deterministic explanations for the anomaly, ordered by importance. | | findings | | object | Finding that attributes an anomaly to an influential tag. | | | description [*required*] | string | Deterministic explanation of the finding. | | | headline [*required*] | string | Concise, deterministic finding title. | | | tag [*required*] | object | Structured tag evidence for an influential-tag finding. | | tag | influence_type [*required*] | enum | Kind of influence a tag has on a series. Allowed enum values: `shape,value` | | tag | key [*required*] | string | Influential tag key. | | tag | rating [*required*] | double | Influence rating from 1 through 5. | | tag | synonyms [*required*] | [object] | Tags grouped with this tag by Variation of Influence synonym analysis. | | synonyms | key [*required*] | string | Synonymous tag key. | | synonyms | values [*required*] | [string] | Values associated with the synonymous tag. | | tag | values [*required*] | [string] | Influential values for the tag key. | | | type [*required*] | enum | Finding category for an influential tag. Allowed enum values: `influential_tag` | | findings | | object | Finding that describes the anomaly when completed analysis produces no displayable influential tags. | | | description [*required*] | string | Deterministic explanation of the finding. | | | headline [*required*] | string | Concise, deterministic finding title. | | | type [*required*] | enum | Finding category for an anomaly without a displayable influential tag. Allowed enum values: `anomaly` | | anomalies | maximum_deviation [*required*] | object | Most anomalous point within the detected interval. | | maximum_deviation | delta_from_boundary [*required*] | double | Absolute distance between the observed value and the nearest anomaly boundary. | | maximum_deviation | timestamp [*required*] | int64 | Point timestamp in milliseconds since the Unix epoch. | | maximum_deviation | value [*required*] | double | Observed value at the point. | | anomalies | series [*required*] | object | Logical series on which the anomaly was detected. | | series | group_tags [*required*] | [string] | Tags identifying the selected group. Empty for a query without grouping. | | series | label [*required*] | string | Display label for the selected series. | | series | query_index [*required*] | int64 | Zero-based index of the caller's formula that produced the series. | | anomalies | tag_analysis [*required*] | object | Summary of optional influential-tag enrichment. Count and key fields are present only when analysis completes; enrichment availability does not affect completion of the investigation result. | | tag_analysis | analyzed_tag_keys | [string] | Tag keys analyzed. Present only when analysis completes. | | tag_analysis | status [*required*] | enum | Outcome of optional influential-tag enrichment. Allowed enum values: `complete,unsupported,failed` | | tag_analysis | tag_keys_analyzed | int64 | Number of tag keys analyzed. Present only when analysis completes. | | tag_analysis | tag_values_analyzed | int64 | Number of tag values analyzed. Present only when analysis completes. | | anomalies | type [*required*] | enum | Direction of an anomaly relative to its expected range. Allowed enum values: `spike,dip` | | results | status [*required*] | enum | Status value indicating successful completion. Allowed enum values: `complete` | | data | id [*required*] | enum | Stable identifier for an anomaly investigation response resource. Allowed enum values: `0` | | data | type [*required*] | enum | Resource type for a timeseries anomaly investigation. Allowed enum values: `timeseries_anomaly_investigation` | | | meta [*required*] | object | Timeseries execution metadata for the single request accepted by this API version. | | meta | from_date [*required*] | int64 | Effective start of the timeseries query in milliseconds since the Unix epoch. | | meta | interval [*required*] | int64 | Effective timeseries interval in milliseconds. | | meta | queries [*required*] | [object] | Execution status for the request's queries. | | queries | name [*required*] | string | Query name from the request. | | queries | status [*required*] | enum | Current execution status for a named query. Allowed enum values: `running,done` | | meta | res_type [*required*] | enum | Response metadata type for a timeseries anomaly investigation. Allowed enum values: `timeseries_anomaly_investigation` | | meta | results_warnings [*required*] | [object] | Non-fatal warnings produced while executing the investigation. | | results_warnings | message [*required*] | string | Human-readable warning message. | | results_warnings | name [*required*] | string | Machine-readable warning name. | | meta | to_date [*required*] | int64 | Effective end of the timeseries query in milliseconds since the Unix epoch. | {% /tab %} {% tab title="Example" %} ```json { "data": { "attributes": { "results": [ { "anomalies": [ { "anomaly_detection": { "configuration_source": "request_formula", "profile": null }, "detected_interval": { "end": 1754406120000, "start": 1754406060000 }, "display_interval": { "end": 1754406120000, "start": 1754406060000 }, "findings": [ [] ], "maximum_deviation": { "delta_from_boundary": 7, "timestamp": 1754406090000, "value": 42 }, "series": { "group_tags": [ "service:api" ], "label": "api", "query_index": 0 }, "tag_analysis": { "analyzed_tag_keys": [ "service", "env" ], "status": "complete", "tag_keys_analyzed": 2, "tag_values_analyzed": 4 }, "type": "spike" } ], "status": "complete" } ] }, "id": "0", "type": "timeseries_anomaly_investigation" }, "meta": { "from_date": 1754406000000, "interval": 60000, "queries": [ { "name": "query1", "status": "done" } ], "res_type": "timeseries_anomaly_investigation", "results_warnings": [ { "message": "Influential tag analysis failed for at least one detected anomaly.", "name": "tag_analysis_failed" } ], "to_date": 1754423940000 } } ``` {% /tab %} {% /tab %} {% tab title="400" %} Bad Request {% tab title="Model" %} API error response. | Parent field | Field | Type | Description | | ------------ | ------------------------ | -------- | ------------------------------------------------------------------------------- | | | errors [*required*] | [object] | A list of errors. | | errors | detail | string | A human-readable explanation specific to this occurrence of the error. | | errors | meta | object | Non-standard meta-information about the error | | errors | source | object | References to the source of the error. | | source | header | string | A string indicating the name of a single request header which caused the error. | | source | parameter | string | A string indicating which URI query parameter caused the error. | | source | pointer | string | A JSON pointer to the value in the request document that caused the error. | | errors | status | string | Status code of the response. | | errors | title | string | Short human-readable summary of the error. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ { "detail": "Missing required attribute in body", "meta": {}, "source": { "header": "Authorization", "parameter": "limit", "pointer": "/data/attributes/title" }, "status": "400", "title": "Bad Request" } ] } ``` {% /tab %} {% /tab %} {% tab title="401" %} Unauthorized {% tab title="Model" %} API error response. | Parent field | Field | Type | Description | | ------------ | ------------------------ | -------- | ------------------------------------------------------------------------------- | | | errors [*required*] | [object] | A list of errors. | | errors | detail | string | A human-readable explanation specific to this occurrence of the error. | | errors | meta | object | Non-standard meta-information about the error | | errors | source | object | References to the source of the error. | | source | header | string | A string indicating the name of a single request header which caused the error. | | source | parameter | string | A string indicating which URI query parameter caused the error. | | source | pointer | string | A JSON pointer to the value in the request document that caused the error. | | errors | status | string | Status code of the response. | | errors | title | string | Short human-readable summary of the error. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ { "detail": "Missing required attribute in body", "meta": {}, "source": { "header": "Authorization", "parameter": "limit", "pointer": "/data/attributes/title" }, "status": "400", "title": "Bad Request" } ] } ``` {% /tab %} {% /tab %} {% tab title="403" %} Forbidden {% tab title="Model" %} API error response. | Parent field | Field | Type | Description | | ------------ | ------------------------ | -------- | ------------------------------------------------------------------------------- | | | errors [*required*] | [object] | A list of errors. | | errors | detail | string | A human-readable explanation specific to this occurrence of the error. | | errors | meta | object | Non-standard meta-information about the error | | errors | source | object | References to the source of the error. | | source | header | string | A string indicating the name of a single request header which caused the error. | | source | parameter | string | A string indicating which URI query parameter caused the error. | | source | pointer | string | A JSON pointer to the value in the request document that caused the error. | | errors | status | string | Status code of the response. | | errors | title | string | Short human-readable summary of the error. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ { "detail": "Missing required attribute in body", "meta": {}, "source": { "header": "Authorization", "parameter": "limit", "pointer": "/data/attributes/title" }, "status": "400", "title": "Bad Request" } ] } ``` {% /tab %} {% /tab %} {% tab title="413" %} Payload Too Large {% tab title="Model" %} API error response. | Parent field | Field | Type | Description | | ------------ | ------------------------ | -------- | ------------------------------------------------------------------------------- | | | errors [*required*] | [object] | A list of errors. | | errors | detail | string | A human-readable explanation specific to this occurrence of the error. | | errors | meta | object | Non-standard meta-information about the error | | errors | source | object | References to the source of the error. | | source | header | string | A string indicating the name of a single request header which caused the error. | | source | parameter | string | A string indicating which URI query parameter caused the error. | | source | pointer | string | A JSON pointer to the value in the request document that caused the error. | | errors | status | string | Status code of the response. | | errors | title | string | Short human-readable summary of the error. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ { "detail": "Missing required attribute in body", "meta": {}, "source": { "header": "Authorization", "parameter": "limit", "pointer": "/data/attributes/title" }, "status": "400", "title": "Bad Request" } ] } ``` {% /tab %} {% /tab %} {% tab title="422" %} Unprocessable Entity {% tab title="Model" %} API error response. | Parent field | Field | Type | Description | | ------------ | ------------------------ | -------- | ------------------------------------------------------------------------------- | | | errors [*required*] | [object] | A list of errors. | | errors | detail | string | A human-readable explanation specific to this occurrence of the error. | | errors | meta | object | Non-standard meta-information about the error | | errors | source | object | References to the source of the error. | | source | header | string | A string indicating the name of a single request header which caused the error. | | source | parameter | string | A string indicating which URI query parameter caused the error. | | source | pointer | string | A JSON pointer to the value in the request document that caused the error. | | errors | status | string | Status code of the response. | | errors | title | string | Short human-readable summary of the error. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ { "detail": "Missing required attribute in body", "meta": {}, "source": { "header": "Authorization", "parameter": "limit", "pointer": "/data/attributes/title" }, "status": "400", "title": "Bad Request" } ] } ``` {% /tab %} {% /tab %} {% tab title="429" %} Too many requests {% tab title="Model" %} API error response. | Field | Type | Description | | ------------------------ | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tab %} ### Code Example ##### \## default # \# Curl command curl -X POST "https://api.datadoghq.com/api/v2/timeseries-anomaly-investigations" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \ -d @- << EOF { "data": { "attributes": { "requests": [ { "formulas": [ { "formula": "anomalies(query1, 'agile', 3)" } ], "from": 1754406000000, "queries": [ { "data_source": "metrics", "name": "query1", "query": "avg:system.cpu.user{env:prod} by {service}" } ], "to": 1754423940000 } ] }, "type": "timeseries_anomaly_investigation" } } EOF {% /tab %}