Compute scalar analytics

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

Overview

Compute scalar analytics results for Product Analytics data. Returns aggregated values (counts, averages, percentiles) optionally grouped by facets. 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 scalar analytics query.

Expand All

Field

Type

Description

data

object

Data object for a scalar response.

attributes

object

Attributes of a scalar analytics response, containing the result columns.

columns

[object]

The list of result columns, each containing values and metadata.

meta

object

Metadata associated with a scalar response column, including optional unit information.

unit

[object]

Unit definitions for the column values, if applicable.

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).

name

string

Column name (facet name for group-by, or "query").

type

enum

Column type. Allowed enum values: number,group

values

[]

Column values.

id

string

Unique identifier for this response data object.

type

enum

The resource type identifier for a scalar analytics response. Allowed enum values: scalar_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": {
      "columns": [
        {
          "meta": {
            "unit": [
              {
                "family": "time",
                "id": "integer",
                "name": "nanosecond",
                "plural": "string",
                "scale_factor": "number",
                "short_name": "string"
              }
            ]
          },
          "name": "string",
          "type": "string",
          "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/scalar" \ -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 scalar 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_scalar(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 scalar 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_scalar(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 scalar 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.QueryProductAnalyticsScalar(ctx, body)

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

	responseContent, _ := json.MarshalIndent(resp, "", "  ")
	fmt.Fprintf(os.Stdout, "Response from `ProductAnalyticsApi.QueryProductAnalyticsScalar`:\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 scalar 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.ProductAnalyticsScalarResponse;

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 {
      ProductAnalyticsScalarResponse result = apiInstance.queryProductAnalyticsScalar(body);
      System.out.println(result);
    } catch (ApiException e) {
      System.err.println("Exception when calling ProductAnalyticsApi#queryProductAnalyticsScalar");
      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 scalar 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_scalar(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 scalar 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.ProductAnalyticsApiQueryProductAnalyticsScalarRequest = {
  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
  .queryProductAnalyticsScalar(params)
  .then((data: v2.ProductAnalyticsScalarResponse) => {
    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"