Compute timeseries analytics

POST https://api.ap1.datadoghq.com/api/v2/product-analytics/analytics/timeserieshttps://api.ap2.datadoghq.com/api/v2/product-analytics/analytics/timeserieshttps://api.datadoghq.eu/api/v2/product-analytics/analytics/timeserieshttps://api.ddog-gov.com/api/v2/product-analytics/analytics/timeserieshttps://api.us2.ddog-gov.com/api/v2/product-analytics/analytics/timeserieshttps://api.datadoghq.com/api/v2/product-analytics/analytics/timeserieshttps://api.us3.datadoghq.com/api/v2/product-analytics/analytics/timeserieshttps://api.us5.datadoghq.com/api/v2/product-analytics/analytics/timeseries

Overview

Compute timeseries analytics results for Product Analytics data. Returns time-bucketed values for charts and trend analysis. The compute.interval field (milliseconds) is required for time bucketing. This endpoint requires the rum_apps_read permission.

Request

Body Data (required)

Expand All

Field

Type

Description

data [required]

object

Data object for an analytics request.

attributes [required]

object

Attributes for an analytics request.

enforced_execution_type

enum

Override the query execution strategy. Allowed enum values: simple,background,trino-multistep,materialized-view

from [required]

int64

Start time in epoch milliseconds. Must be less than to.

query [required]

object

The analytics query definition containing a base query, compute rule, and optional grouping.

audience_filters

object

Audience filter definitions for targeting specific user segments.

accounts

[object]

Account audience queries.

name [required]

string

Name of this query, referenced in the formula.

query

string

Search query for filtering accounts.

formula

string

Boolean formula combining audience queries by name.

segments

[object]

Segment audience queries.

name [required]

string

Name of this query, referenced in the formula.

segment_id [required]

uuid

UUID of the segment to filter by.

users

[object]

User audience queries.

name [required]

string

Name of this query, referenced in the formula.

query

string

Search query for filtering users.

compute [required]

object

A compute rule for aggregating data.

aggregation [required]

string

The aggregation function (count, cardinality, avg, sum, min, max, etc.).

interval

int64

Time bucket size in milliseconds. Required for timeseries queries.

metric

string

The metric to aggregate on. Required for non-count aggregations.

group_by

[object]

Group-by rules for segmenting results.

facet [required]

string

The facet to group by.

limit

int64

Maximum number of groups to return.

should_exclude_missing

boolean

Exclude results with missing facet values.

sort

object

Sort configuration for group-by results.

aggregation

string

The aggregation function to sort by.

metric

string

The metric to sort by.

order

enum

Direction of sort. Allowed enum values: asc,desc

default: desc

source

string

The source for audience-filter-based group-by.

indexes

[string]

Restrict the query to specific indexes. Max 1 entry.

query [required]

 <oneOf>

A query definition discriminated by the data_source field. Use product_analytics for standard event queries, or product_analytics_occurrence for occurrence-filtered queries.

Option 1

object

A standard Product Analytics event query.

data_source [required]

enum

The data source identifier. Allowed enum values: product_analytics

search [required]

object

Search parameters for an event query.

query

string

The search query using Datadog search syntax.

Option 2

object

A Product Analytics occurrence-filtered query.

data_source [required]

enum

The data source identifier for occurrence queries. Allowed enum values: product_analytics_occurrence

search [required]

object

Search parameters for an occurrence query.

occurrences

object

Filter for occurrence-based queries.

meta

object

Additional metadata.

<any-key>

string

operator [required]

string

Comparison operator (=, >=, <=, >, <).

value [required]

string

The occurrence count threshold as a string.

query

string

The search query using Datadog search syntax.

request_id

string

Optional request ID for multi-step query continuation.

to [required]

int64

End time in epoch milliseconds.

type [required]

enum

The resource type for analytics requests. Allowed enum values: formula_analytics_extended_request

{
  "data": {
    "attributes": {
      "enforced_execution_type": "string",
      "from": 1771232048460,
      "query": {
        "audience_filters": {
          "accounts": [
            {
              "name": "",
              "query": "string"
            }
          ],
          "formula": "u",
          "segments": [
            {
              "name": "",
              "segment_id": ""
            }
          ],
          "users": [
            {
              "name": "u",
              "query": "*"
            }
          ]
        },
        "compute": {
          "aggregation": "count",
          "interval": 3600000,
          "metric": "@session.time_spent"
        },
        "group_by": [
          {
            "facet": "@view.name",
            "limit": 10,
            "should_exclude_missing": false,
            "sort": {
              "aggregation": "count",
              "metric": "string",
              "order": "string"
            },
            "source": "string"
          }
        ],
        "indexes": [],
        "query": {
          "data_source": "product_analytics",
          "search": {
            "query": "@type:view"
          }
        }
      },
      "request_id": "string",
      "to": 1771836848262
    },
    "type": "formula_analytics_extended_request"
  }
}

Response

OK

Response for a timeseries analytics query.

Expand All

Field

Type

Description

data

object

Data object for a timeseries analytics response.

attributes

object

Attributes of a timeseries analytics response, containing series data, timestamps, and interval definitions.

intervals

[object]

Interval definitions describing the time buckets used in the response.

milliseconds

int64

The duration of each time bucket in milliseconds.

start_time

int64

The start of this interval as an epoch timestamp in milliseconds.

times

[integer]

Epoch timestamps (in milliseconds) for each bucket in this interval.

type

string

The interval type (e.g., fixed or auto-computed bucket size).

series

[object]

The list of series, each corresponding to a query or group-by combination.

group_tags

[string]

The group-by tag values that identify this series.

query_index

int64

The index of the query that produced this series.

unit

[object]

Unit definitions for the series values.

family

string

The unit family (e.g., time, bytes).

id

int64

Numeric identifier for the unit.

name

string

The full name of the unit (e.g., nanosecond).

plural

string

Plural form of the unit name (e.g., nanoseconds).

scale_factor

double

Conversion factor relative to the base unit of the family.

short_name

string

Abbreviated unit name (e.g., ns).

times

[integer]

Timestamps for each data point (epoch milliseconds).

values

[array]

Values for each series at each time point.

id

string

Unique identifier for this response data object.

type

enum

The resource type identifier for a timeseries analytics response. Allowed enum values: timeseries_response

meta

object

Metadata for a Product Analytics query response.

request_id

string

Unique identifier for the request, used for multi-step query continuation.

status

enum

The execution status of a Product Analytics query. Allowed enum values: done,running,timeout

{
  "data": {
    "attributes": {
      "intervals": [
        {
          "milliseconds": "integer",
          "start_time": "integer",
          "times": [],
          "type": "string"
        }
      ],
      "series": [
        {
          "group_tags": [],
          "query_index": "integer",
          "unit": [
            {
              "family": "time",
              "id": "integer",
              "name": "nanosecond",
              "plural": "string",
              "scale_factor": "number",
              "short_name": "string"
            }
          ]
        }
      ],
      "times": [],
      "values": []
    },
    "id": "string",
    "type": "string"
  },
  "meta": {
    "request_id": "string",
    "status": "string"
  }
}

Bad Request

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Not Authorized

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Too many requests

API error response.

Expand All

Field

Type

Description

errors [required]

[string]

A list of errors.

{
  "errors": [
    "Bad Request"
  ]
}

Code Example

                  ## default
# 

# Curl command
curl -X POST "https://api.ap1.datadoghq.com"https://api.ap2.datadoghq.com"https://api.datadoghq.eu"https://api.ddog-gov.com"https://api.us2.ddog-gov.com"https://api.datadoghq.com"https://api.us3.datadoghq.com"https://api.us5.datadoghq.com/api/v2/product-analytics/analytics/timeseries" \ -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": { "from": 1771232048460, "query": { "compute": { "aggregation": "count" }, "query": { "data_source": "product_analytics", "search": { "query": "@type:view" } } }, "to": 1771836848262 }, "type": "formula_analytics_extended_request" } } EOF
"""
Compute timeseries analytics returns "OK" response
"""

from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.product_analytics_api import ProductAnalyticsApi
from datadog_api_client.v2.model.product_analytics_analytics_query import ProductAnalyticsAnalyticsQuery
from datadog_api_client.v2.model.product_analytics_analytics_request import ProductAnalyticsAnalyticsRequest
from datadog_api_client.v2.model.product_analytics_analytics_request_attributes import (
    ProductAnalyticsAnalyticsRequestAttributes,
)
from datadog_api_client.v2.model.product_analytics_analytics_request_data import ProductAnalyticsAnalyticsRequestData
from datadog_api_client.v2.model.product_analytics_analytics_request_type import ProductAnalyticsAnalyticsRequestType
from datadog_api_client.v2.model.product_analytics_compute import ProductAnalyticsCompute
from datadog_api_client.v2.model.product_analytics_event_query import ProductAnalyticsEventQuery
from datadog_api_client.v2.model.product_analytics_event_query_data_source import ProductAnalyticsEventQueryDataSource
from datadog_api_client.v2.model.product_analytics_event_search import ProductAnalyticsEventSearch

body = ProductAnalyticsAnalyticsRequest(
    data=ProductAnalyticsAnalyticsRequestData(
        attributes=ProductAnalyticsAnalyticsRequestAttributes(
            _from=1771232048460,
            query=ProductAnalyticsAnalyticsQuery(
                compute=ProductAnalyticsCompute(
                    aggregation="count",
                ),
                query=ProductAnalyticsEventQuery(
                    data_source=ProductAnalyticsEventQueryDataSource.PRODUCT_ANALYTICS,
                    search=ProductAnalyticsEventSearch(
                        query="@type:view",
                    ),
                ),
            ),
            to=1771836848262,
        ),
        type=ProductAnalyticsAnalyticsRequestType.FORMULA_ANALYTICS_EXTENDED_REQUEST,
    ),
)

configuration = Configuration()
with ApiClient(configuration) as api_client:
    api_instance = ProductAnalyticsApi(api_client)
    response = api_instance.query_product_analytics_timeseries(body=body)

    print(response)

Instructions

First install the library and its dependencies and then save the example to example.py and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" python3 "example.py"
# Compute timeseries analytics returns "OK" response

require "datadog_api_client"
api_instance = DatadogAPIClient::V2::ProductAnalyticsAPI.new

body = DatadogAPIClient::V2::ProductAnalyticsAnalyticsRequest.new({
  data: DatadogAPIClient::V2::ProductAnalyticsAnalyticsRequestData.new({
    attributes: DatadogAPIClient::V2::ProductAnalyticsAnalyticsRequestAttributes.new({
      from: 1771232048460,
      query: DatadogAPIClient::V2::ProductAnalyticsAnalyticsQuery.new({
        compute: DatadogAPIClient::V2::ProductAnalyticsCompute.new({
          aggregation: "count",
        }),
        query: DatadogAPIClient::V2::ProductAnalyticsEventQuery.new({
          data_source: DatadogAPIClient::V2::ProductAnalyticsEventQueryDataSource::PRODUCT_ANALYTICS,
          search: DatadogAPIClient::V2::ProductAnalyticsEventSearch.new({
            query: "@type:view",
          }),
        }),
      }),
      to: 1771836848262,
    }),
    type: DatadogAPIClient::V2::ProductAnalyticsAnalyticsRequestType::FORMULA_ANALYTICS_EXTENDED_REQUEST,
  }),
})
p api_instance.query_product_analytics_timeseries(body)

Instructions

First install the library and its dependencies and then save the example to example.rb and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" rb "example.rb"
// Compute timeseries analytics returns "OK" response

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"os"

	"github.com/DataDog/datadog-api-client-go/v2/api/datadog"
	"github.com/DataDog/datadog-api-client-go/v2/api/datadogV2"
)

func main() {
	body := datadogV2.ProductAnalyticsAnalyticsRequest{
		Data: datadogV2.ProductAnalyticsAnalyticsRequestData{
			Attributes: datadogV2.ProductAnalyticsAnalyticsRequestAttributes{
				From: 1771232048460,
				Query: datadogV2.ProductAnalyticsAnalyticsQuery{
					Compute: datadogV2.ProductAnalyticsCompute{
						Aggregation: "count",
					},
					Query: datadogV2.ProductAnalyticsBaseQuery{
						ProductAnalyticsEventQuery: &datadogV2.ProductAnalyticsEventQuery{
							DataSource: datadogV2.PRODUCTANALYTICSEVENTQUERYDATASOURCE_PRODUCT_ANALYTICS,
							Search: datadogV2.ProductAnalyticsEventSearch{
								Query: datadog.PtrString("@type:view"),
							},
						}},
				},
				To: 1771836848262,
			},
			Type: datadogV2.PRODUCTANALYTICSANALYTICSREQUESTTYPE_FORMULA_ANALYTICS_EXTENDED_REQUEST,
		},
	}
	ctx := datadog.NewDefaultContext(context.Background())
	configuration := datadog.NewConfiguration()
	apiClient := datadog.NewAPIClient(configuration)
	api := datadogV2.NewProductAnalyticsApi(apiClient)
	resp, r, err := api.QueryProductAnalyticsTimeseries(ctx, body)

	if err != nil {
		fmt.Fprintf(os.Stderr, "Error when calling `ProductAnalyticsApi.QueryProductAnalyticsTimeseries`: %v\n", err)
		fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
	}

	responseContent, _ := json.MarshalIndent(resp, "", "  ")
	fmt.Fprintf(os.Stdout, "Response from `ProductAnalyticsApi.QueryProductAnalyticsTimeseries`:\n%s\n", responseContent)
}

Instructions

First install the library and its dependencies and then save the example to main.go and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" go run "main.go"
// Compute timeseries analytics returns "OK" response

import com.datadog.api.client.ApiClient;
import com.datadog.api.client.ApiException;
import com.datadog.api.client.v2.api.ProductAnalyticsApi;
import com.datadog.api.client.v2.model.ProductAnalyticsAnalyticsQuery;
import com.datadog.api.client.v2.model.ProductAnalyticsAnalyticsRequest;
import com.datadog.api.client.v2.model.ProductAnalyticsAnalyticsRequestAttributes;
import com.datadog.api.client.v2.model.ProductAnalyticsAnalyticsRequestData;
import com.datadog.api.client.v2.model.ProductAnalyticsAnalyticsRequestType;
import com.datadog.api.client.v2.model.ProductAnalyticsBaseQuery;
import com.datadog.api.client.v2.model.ProductAnalyticsCompute;
import com.datadog.api.client.v2.model.ProductAnalyticsEventQuery;
import com.datadog.api.client.v2.model.ProductAnalyticsEventQueryDataSource;
import com.datadog.api.client.v2.model.ProductAnalyticsEventSearch;
import com.datadog.api.client.v2.model.ProductAnalyticsTimeseriesResponse;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = ApiClient.getDefaultApiClient();
    ProductAnalyticsApi apiInstance = new ProductAnalyticsApi(defaultClient);

    ProductAnalyticsAnalyticsRequest body =
        new ProductAnalyticsAnalyticsRequest()
            .data(
                new ProductAnalyticsAnalyticsRequestData()
                    .attributes(
                        new ProductAnalyticsAnalyticsRequestAttributes()
                            .from(1771232048460L)
                            .query(
                                new ProductAnalyticsAnalyticsQuery()
                                    .compute(new ProductAnalyticsCompute().aggregation("count"))
                                    .query(
                                        new ProductAnalyticsBaseQuery(
                                            new ProductAnalyticsEventQuery()
                                                .dataSource(
                                                    ProductAnalyticsEventQueryDataSource
                                                        .PRODUCT_ANALYTICS)
                                                .search(
                                                    new ProductAnalyticsEventSearch()
                                                        .query("@type:view")))))
                            .to(1771836848262L))
                    .type(ProductAnalyticsAnalyticsRequestType.FORMULA_ANALYTICS_EXTENDED_REQUEST));

    try {
      ProductAnalyticsTimeseriesResponse result = apiInstance.queryProductAnalyticsTimeseries(body);
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println(
          "Exception when calling ProductAnalyticsApi#queryProductAnalyticsTimeseries");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}

Instructions

First install the library and its dependencies and then save the example to Example.java and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" java "Example.java"
// Compute timeseries analytics returns "OK" response
use datadog_api_client::datadog;
use datadog_api_client::datadogV2::api_product_analytics::ProductAnalyticsAPI;
use datadog_api_client::datadogV2::model::ProductAnalyticsAnalyticsQuery;
use datadog_api_client::datadogV2::model::ProductAnalyticsAnalyticsRequest;
use datadog_api_client::datadogV2::model::ProductAnalyticsAnalyticsRequestAttributes;
use datadog_api_client::datadogV2::model::ProductAnalyticsAnalyticsRequestData;
use datadog_api_client::datadogV2::model::ProductAnalyticsAnalyticsRequestType;
use datadog_api_client::datadogV2::model::ProductAnalyticsBaseQuery;
use datadog_api_client::datadogV2::model::ProductAnalyticsCompute;
use datadog_api_client::datadogV2::model::ProductAnalyticsEventQuery;
use datadog_api_client::datadogV2::model::ProductAnalyticsEventQueryDataSource;
use datadog_api_client::datadogV2::model::ProductAnalyticsEventSearch;

#[tokio::main]
async fn main() {
    let body = ProductAnalyticsAnalyticsRequest::new(ProductAnalyticsAnalyticsRequestData::new(
        ProductAnalyticsAnalyticsRequestAttributes::new(
            1771232048460,
            ProductAnalyticsAnalyticsQuery::new(
                ProductAnalyticsCompute::new("count".to_string()),
                ProductAnalyticsBaseQuery::ProductAnalyticsEventQuery(Box::new(
                    ProductAnalyticsEventQuery::new(
                        ProductAnalyticsEventQueryDataSource::PRODUCT_ANALYTICS,
                        ProductAnalyticsEventSearch::new().query("@type:view".to_string()),
                    ),
                )),
            ),
            1771836848262,
        ),
        ProductAnalyticsAnalyticsRequestType::FORMULA_ANALYTICS_EXTENDED_REQUEST,
    ));
    let configuration = datadog::Configuration::new();
    let api = ProductAnalyticsAPI::with_config(configuration);
    let resp = api.query_product_analytics_timeseries(body).await;
    if let Ok(value) = resp {
        println!("{:#?}", value);
    } else {
        println!("{:#?}", resp.unwrap_err());
    }
}

Instructions

First install the library and its dependencies and then save the example to src/main.rs and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" cargo run
/**
 * Compute timeseries analytics returns "OK" response
 */

import { client, v2 } from "@datadog/datadog-api-client";

const configuration = client.createConfiguration();
const apiInstance = new v2.ProductAnalyticsApi(configuration);

const params: v2.ProductAnalyticsApiQueryProductAnalyticsTimeseriesRequest = {
  body: {
    data: {
      attributes: {
        from: 1771232048460,
        query: {
          compute: {
            aggregation: "count",
          },
          query: {
            dataSource: "product_analytics",
            search: {
              query: "@type:view",
            },
          },
        },
        to: 1771836848262,
      },
      type: "formula_analytics_extended_request",
    },
  },
};

apiInstance
  .queryProductAnalyticsTimeseries(params)
  .then((data: v2.ProductAnalyticsTimeseriesResponse) => {
    console.log(
      "API called successfully. Returned data: " + JSON.stringify(data)
    );
  })
  .catch((error: any) => console.error(error));

Instructions

First install the library and its dependencies and then save the example to example.ts and run following commands:

    
DD_SITE="datadoghq.comus3.datadoghq.comus5.datadoghq.comdatadoghq.euap1.datadoghq.comap2.datadoghq.comddog-gov.comus2.ddog-gov.com" DD_API_KEY="<API-KEY>" DD_APP_KEY="<APP-KEY>" tsc "example.ts"