---
title: "Investigate a timeseries anomaly"
method: POST
path: "/api/v2/timeseries-anomaly-investigations"
tags: ["Timeseries Anomaly Investigations"]
---

# Investigate a timeseries anomaly

`POST /api/v2/timeseries-anomaly-investigations`

## Request

- Base URL: `https://api.datadoghq.com`
- URL: `https://api.datadoghq.com/api/v2/timeseries-anomaly-investigations`
- Auth: one of:
  - API key in header `DD-API-KEY` and API key in header `DD-APPLICATION-KEY`
  - OAuth 2
    - Authorization code: `/oauth2/v1/authorize`
    - Token URL: `/oauth2/v1/token` scopes: `timeseries_query`, `metrics_read`
- TypeScript: <https://skmtc.dev/datadog/apis/datadog-api-v2-collection/docs/api/v2/timeseries-anomaly-investigations/post.ts> (a function with typed inputs; its response is checked against the schema)

Investigates a metrics timeseries request for its most significant anomalies and returns
deterministic findings. Metrics queries with or without grouping are supported. This
API version accepts exactly one request and returns at most three anomalies.

## Request body

- TimeseriesAnomalyInvestigationRequest: Request to investigate a metrics timeseries for anomalies.
  - `data` TimeseriesAnomalyInvestigationRequestData, required: JSON:API resource containing an anomaly investigation request.
    - `attributes` TimeseriesAnomalyInvestigationRequestAttributes, required: Attributes of an anomaly investigation request.
      - `requests` TimeseriesAnomalyInvestigationTimeseriesRequest[], required: Timeseries requests to investigate. This API version accepts exactly one request.
        - `formulas` TimeseriesAnomalyInvestigationFormula[], required: Formulas to evaluate. Each formula may contain an explicit `anomalies()` call or a supported metrics expression.
          - `formula` string, required: Formula expression referencing one or more named queries. When the expression does not contain an explicit `anomalies()` call, the endpoint applies the default Watchdog Explains anomaly detection configuration.
          - `limit` TimeseriesAnomalyInvestigationFormulaLimit: Optional formula limit accepted for compatibility with Timeseries API requests. Formula limits have no effect on timeseries queries.
            - `count` integer: Requested result limit. This field has no effect on a timeseries anomaly investigation.
            - `order` 'asc' | 'desc': Sort order used when applying a formula series limit.
        - `from` integer, required: Start of the investigation time window in milliseconds since the Unix epoch.
        - `interval` integer: Optional requested aggregation interval in milliseconds.
        - `queries` TimeseriesAnomalyInvestigationMetricQuery[], required: Metrics queries referenced by the formulas.
          - `aggregator` string: Optional scalar aggregator accepted for request compatibility. This field is ignored for timeseries 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.
          - `data_source` 'metrics', required: Data source for an anomaly investigation query.
          - `name` string, required: Name used to reference this query from formulas.
          - `query` string, required: Datadog metrics query expression.
        - `to` integer, required: End of the investigation time window in milliseconds since the Unix epoch. Must be later than `from`.
    - `type` 'timeseries_anomaly_investigation', required: Resource type for a timeseries anomaly investigation.

## Response `200`

OK

- TimeseriesAnomalyInvestigationResponse: Response containing the anomaly investigation results and timeseries metadata.
  - `data` TimeseriesAnomalyInvestigationResponseData, required: JSON:API resource containing anomaly investigation results.
    - `attributes` TimeseriesAnomalyInvestigationResponseAttributes, required: Attributes of an anomaly investigation response.
      - `results` TimeseriesAnomalyInvestigationResult[], required: Results returned in the same order as the submitted requests. This API version returns exactly one result.
        - `anomalies` TimeseriesAnomalyInvestigationAnomaly[], required: Detected anomalies, ordered by significance. This API version returns at most three anomalies across the submitted request.
          - `anomaly_detection` TimeseriesAnomalyInvestigationDetection, required: Anomaly detection configuration used for the result.
            - `configuration_source` 'request_formula' | 'watchdog_explains_default', required: Source of the anomaly detection configuration.
            - `profile` string, nullable, required: Applied Watchdog Explains profile, or null when the request supplied an explicit `anomalies()` formula. The current Watchdog profile is `watchdog_explains_v1`.
          - `detected_interval` TimeseriesAnomalyInvestigationInterval, required: Inclusive time interval in milliseconds since the Unix epoch.
            - `end` integer, required: Timestamp of the final point in the interval.
            - `start` integer, required: Inclusive start of the interval.
          - `display_interval` TimeseriesAnomalyInvestigationInterval, required: Inclusive time interval in milliseconds since the Unix epoch.
            - `end` integer, required: Timestamp of the final point in the interval.
            - `start` integer, required: Inclusive start of the interval.
          - `findings` TimeseriesAnomalyInvestigationFinding[], required: Deterministic explanations for the anomaly, ordered by importance.
            - union: Deterministic explanation for a detected anomaly.
              - …
          - `maximum_deviation` TimeseriesAnomalyInvestigationMaximumDeviation, required: Most anomalous point within the detected interval.
            - `delta_from_boundary` number, double, required: Absolute distance between the observed value and the nearest anomaly boundary.
            - `timestamp` integer, required: Point timestamp in milliseconds since the Unix epoch.
            - `value` number, double, required: Observed value at the point.
          - `series` TimeseriesAnomalyInvestigationSeries, required: Logical series on which the anomaly was detected.
            - `group_tags` string[], required: Tags identifying the selected group. Empty for a query without grouping.
            - `label` string, required: Display label for the selected series.
            - `query_index` integer, required: Zero-based index of the caller's formula that produced the series.
          - `tag_analysis` TimeseriesAnomalyInvestigationTagAnalysis, required: 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.
            - `analyzed_tag_keys` string[]: Tag keys analyzed. Present only when analysis completes.
            - `status` 'complete' | 'unsupported' | 'failed', required: Outcome of optional influential-tag enrichment.
            - `tag_keys_analyzed` integer: Number of tag keys analyzed. Present only when analysis completes.
            - `tag_values_analyzed` integer: Number of tag values analyzed. Present only when analysis completes.
          - `type` 'spike' | 'dip', required: Direction of an anomaly relative to its expected range.
        - `status` 'complete', required: Status value indicating successful completion.
    - `id` '0', required: Stable identifier for an anomaly investigation response resource.
    - `type` 'timeseries_anomaly_investigation', required: Resource type for a timeseries anomaly investigation.
  - `meta` TimeseriesAnomalyInvestigationResponseMeta, required: Timeseries execution metadata for the single request accepted by this API version.
    - `from_date` integer, required: Effective start of the timeseries query in milliseconds since the Unix epoch.
    - `interval` integer, required: Effective timeseries interval in milliseconds.
    - `queries` TimeseriesAnomalyInvestigationQueryStatus[], required: Execution status for the request's queries.
      - `name` string, required: Query name from the request.
      - `status` 'running' | 'done', required: Current execution status for a named query.
    - `res_type` 'timeseries_anomaly_investigation', required: Response metadata type for a timeseries anomaly investigation.
    - `results_warnings` TimeseriesAnomalyInvestigationResultsWarning[], required: Non-fatal warnings produced while executing the investigation.
      - `message` string, required: Human-readable warning message.
      - `name` string, required: Machine-readable warning name.
    - `to_date` integer, required: Effective end of the timeseries query in milliseconds since the Unix epoch.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `413`: Payload Too Large
- `422`: Unprocessable Entity
- `429`: Too many requests

---

[API](https://skmtc.dev/datadog/apis/datadog-api-v2-collection.md) - [All operations](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/llms.txt) - [OpenAPI document](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/revisions/3f70db624329?raw)