Product Analytics

Send server-side events to Product Analytics. Server-Side Events Ingestion allows you to collect custom events from any server-side source, and retains events for 15 months. Server-side events are helpful for understanding causes of a funnel drop-off which are external to the client-side (for example, payment processing error). See the Product Analytics page for more information.

POST Not supported in the AP1 regionNot supported in the AP2 regionNot supported in the EU regionNot supported in the GOV regionNot supported in the US regionNot supported in the US3 regionNot supported in the US5 region

概要

Send server-side events to Product Analytics. Server-side events are retained for 15 months.

Server-Side events in Product Analytics are helpful for tracking events that occur on the server, as opposed to client-side events, which are captured by Real User Monitoring (RUM) SDKs. This allows for a more comprehensive view of the user journey by including actions that happen on the server. Typical examples could be checkout.completed or payment.processed.

Ingested server-side events are integrated into Product Analytics to allow users to select and filter these events in the event picker, similar to how views or actions are handled.

Requirements:

  • At least one of usr, account, or session must be provided with a valid ID.
  • The application.id must reference a Product Analytics-enabled application.

Custom Attributes: Any additional fields in the payload are flattened and searchable as facets. For example, a payload with {"customer": {"tier": "premium"}} is searchable with the syntax @customer.tier:premium in Datadog.

The status codes answered by the HTTP API are:

  • 202: Accepted: The request has been accepted for processing
  • 400: Bad request (likely an issue in the payload formatting)
  • 401: Unauthorized (likely a missing API Key)
  • 403: Permission issue (likely using an invalid API Key)
  • 408: Request Timeout, request should be retried after some time
  • 413: Payload too large (batch is above 5MB uncompressed)
  • 429: Too Many Requests, request should be retried after some time
  • 500: Internal Server Error, the server encountered an unexpected condition that prevented it from fulfilling the request, request should be retried after some time
  • 503: Service Unavailable, the server is not ready to handle the request probably because it is overloaded, request should be retried after some time

リクエスト

Body Data (required)

Server-side event to send (JSON format).

Expand All

フィールド

種類

説明

account

object

The account linked to your event.

id [required]

string

The account ID used in Datadog.

application [required]

object

The application in which you want to send your events.

id [required]

string

The application ID of your application. It can be found in your application management page.

event [required]

object

Fields used for the event.

name [required]

string

The name of your event, which is used for search in the same way as view or action names.

session

object

The session linked to your event.

id [required]

string

The session ID captured by the SDK.

type [required]

enum

The type of Product Analytics event. Must be server for server-side events. Allowed enum values: server

usr

object

The user linked to your event.

id [required]

string

The user ID used in Datadog.

{
  "account": {
    "id": "account-67890"
  },
  "application": {
    "id": "123abcde-123a-123b-1234-123456789abc"
  },
  "event": {
    "name": "payment.processed"
  },
  "session": {
    "id": "session-abcdef"
  },
  "type": "server",
  "usr": {
    "id": "user-12345"
  }
}

応答

Request accepted for processing (always 202 empty JSON).

Expand All

フィールド

種類

説明

No response body

{}

Bad Request

Error response.

Expand All

フィールド

種類

説明

errors

[object]

Structured errors.

detail

string

Error message.

status

string

Error code.

title

string

Error title.

{
  "errors": [
    {
      "detail": "Malformed payload",
      "status": "400",
      "title": "Bad Request"
    }
  ]
}

Unauthorized

Error response.

Expand All

フィールド

種類

説明

errors

[object]

Structured errors.

detail

string

Error message.

status

string

Error code.

title

string

Error title.

{
  "errors": [
    {
      "detail": "Malformed payload",
      "status": "400",
      "title": "Bad Request"
    }
  ]
}

Forbidden

Error response.

Expand All

フィールド

種類

説明

errors

[object]

Structured errors.

detail

string

Error message.

status

string

Error code.

title

string

Error title.

{
  "errors": [
    {
      "detail": "Malformed payload",
      "status": "400",
      "title": "Bad Request"
    }
  ]
}

Request Timeout

Error response.

Expand All

フィールド

種類

説明

errors

[object]

Structured errors.

detail

string

Error message.

status

string

Error code.

title

string

Error title.

{
  "errors": [
    {
      "detail": "Malformed payload",
      "status": "400",
      "title": "Bad Request"
    }
  ]
}

Payload Too Large

Error response.

Expand All

フィールド

種類

説明

errors

[object]

Structured errors.

detail

string

Error message.

status

string

Error code.

title

string

Error title.

{
  "errors": [
    {
      "detail": "Malformed payload",
      "status": "400",
      "title": "Bad Request"
    }
  ]
}

Too Many Requests

Error response.

Expand All

フィールド

種類

説明

errors

[object]

Structured errors.

detail

string

Error message.

status

string

Error code.

title

string

Error title.

{
  "errors": [
    {
      "detail": "Malformed payload",
      "status": "400",
      "title": "Bad Request"
    }
  ]
}

Internal Server Error

Error response.

Expand All

フィールド

種類

説明

errors

[object]

Structured errors.

detail

string

Error message.

status

string

Error code.

title

string

Error title.

{
  "errors": [
    {
      "detail": "Malformed payload",
      "status": "400",
      "title": "Bad Request"
    }
  ]
}

Service Unavailable

Error response.

Expand All

フィールド

種類

説明

errors

[object]

Structured errors.

detail

string

Error message.

status

string

Error code.

title

string

Error title.

{
  "errors": [
    {
      "detail": "Malformed payload",
      "status": "400",
      "title": "Bad Request"
    }
  ]
}

コード例

                  ## Event with account ID
# Send a server-side event linked to an account.

# Curl command
curl -X POST /api/v2/prodlytics" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -d @- << EOF { "account": { "id": "account-456" }, "application": { "id": "123abcde-123a-123b-1234-123456789abc" }, "event": { "name": "checkout.completed" }, "type": "server" } EOF
## Event with custom attributes # Send a server-side event with additional custom attributes.
# Curl command
curl -X POST /api/v2/prodlytics" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -d @- << EOF { "application": { "id": "123abcde-123a-123b-1234-123456789abc" }, "customer": { "tier": "premium" }, "event": { "name": "payment.processed" }, "type": "server", "usr": { "id": "123" } } EOF
## Event with session ID # Send a server-side event linked to a session.
# Curl command
curl -X POST /api/v2/prodlytics" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -d @- << EOF { "application": { "id": "123abcde-123a-123b-1234-123456789abc" }, "event": { "name": "form.submitted" }, "session": { "id": "session-789" }, "type": "server" } EOF
## Simple event with user ID # Send a server-side event linked to a user.
# Curl command
curl -X POST /api/v2/prodlytics" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "DD-API-KEY: ${DD_API_KEY}" \ -d @- << EOF { "application": { "id": "123abcde-123a-123b-1234-123456789abc" }, "event": { "name": "payment.processed" }, "type": "server", "usr": { "id": "123" } } EOF
"""
Send server-side events returns "Request accepted for processing (always 202 empty JSON)." 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_server_side_event_item import ProductAnalyticsServerSideEventItem
from datadog_api_client.v2.model.product_analytics_server_side_event_item_account import (
    ProductAnalyticsServerSideEventItemAccount,
)
from datadog_api_client.v2.model.product_analytics_server_side_event_item_application import (
    ProductAnalyticsServerSideEventItemApplication,
)
from datadog_api_client.v2.model.product_analytics_server_side_event_item_event import (
    ProductAnalyticsServerSideEventItemEvent,
)
from datadog_api_client.v2.model.product_analytics_server_side_event_item_session import (
    ProductAnalyticsServerSideEventItemSession,
)
from datadog_api_client.v2.model.product_analytics_server_side_event_item_type import (
    ProductAnalyticsServerSideEventItemType,
)
from datadog_api_client.v2.model.product_analytics_server_side_event_item_usr import (
    ProductAnalyticsServerSideEventItemUsr,
)

body = ProductAnalyticsServerSideEventItem(
    account=ProductAnalyticsServerSideEventItemAccount(
        id="account-67890",
    ),
    application=ProductAnalyticsServerSideEventItemApplication(
        id="123abcde-123a-123b-1234-123456789abc",
    ),
    event=ProductAnalyticsServerSideEventItemEvent(
        name="payment.processed",
    ),
    session=ProductAnalyticsServerSideEventItemSession(
        id="session-abcdef",
    ),
    type=ProductAnalyticsServerSideEventItemType.SERVER,
    usr=ProductAnalyticsServerSideEventItemUsr(
        id="user-12345",
    ),
)

configuration = Configuration()
with ApiClient(configuration) as api_client:
    api_instance = ProductAnalyticsApi(api_client)
    response = api_instance.submit_product_analytics_event(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="Not supported in the US1 regionNot supported in the US3 regionNot supported in the US5 regionNot supported in the EU regionNot supported in the AP1 regionNot supported in the AP2 regionNot supported in the US1-FED region" DD_API_KEY="<DD_API_KEY>" python3 "example.py"
# Send server-side events returns "Request accepted for processing (always 202 empty JSON)." response

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

body = DatadogAPIClient::V2::ProductAnalyticsServerSideEventItem.new({
  account: DatadogAPIClient::V2::ProductAnalyticsServerSideEventItemAccount.new({
    id: "account-67890",
  }),
  application: DatadogAPIClient::V2::ProductAnalyticsServerSideEventItemApplication.new({
    id: "123abcde-123a-123b-1234-123456789abc",
  }),
  event: DatadogAPIClient::V2::ProductAnalyticsServerSideEventItemEvent.new({
    name: "payment.processed",
  }),
  session: DatadogAPIClient::V2::ProductAnalyticsServerSideEventItemSession.new({
    id: "session-abcdef",
  }),
  type: DatadogAPIClient::V2::ProductAnalyticsServerSideEventItemType::SERVER,
  usr: DatadogAPIClient::V2::ProductAnalyticsServerSideEventItemUsr.new({
    id: "user-12345",
  }),
})
p api_instance.submit_product_analytics_event(body)

Instructions

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

    
DD_SITE="Not supported in the US1 regionNot supported in the US3 regionNot supported in the US5 regionNot supported in the EU regionNot supported in the AP1 regionNot supported in the AP2 regionNot supported in the US1-FED region" DD_API_KEY="<DD_API_KEY>" rb "example.rb"
// Send server-side events returns "Request accepted for processing (always 202 empty JSON)." 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.ProductAnalyticsServerSideEventItem{
		Account: &datadogV2.ProductAnalyticsServerSideEventItemAccount{
			Id: "account-67890",
		},
		Application: datadogV2.ProductAnalyticsServerSideEventItemApplication{
			Id: "123abcde-123a-123b-1234-123456789abc",
		},
		Event: datadogV2.ProductAnalyticsServerSideEventItemEvent{
			Name: "payment.processed",
		},
		Session: &datadogV2.ProductAnalyticsServerSideEventItemSession{
			Id: "session-abcdef",
		},
		Type: datadogV2.PRODUCTANALYTICSSERVERSIDEEVENTITEMTYPE_SERVER,
		Usr: &datadogV2.ProductAnalyticsServerSideEventItemUsr{
			Id: "user-12345",
		},
	}
	ctx := datadog.NewDefaultContext(context.Background())
	configuration := datadog.NewConfiguration()
	apiClient := datadog.NewAPIClient(configuration)
	api := datadogV2.NewProductAnalyticsApi(apiClient)
	resp, r, err := api.SubmitProductAnalyticsEvent(ctx, body)

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

	responseContent, _ := json.MarshalIndent(resp, "", "  ")
	fmt.Fprintf(os.Stdout, "Response from `ProductAnalyticsApi.SubmitProductAnalyticsEvent`:\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="Not supported in the US1 regionNot supported in the US3 regionNot supported in the US5 regionNot supported in the EU regionNot supported in the AP1 regionNot supported in the AP2 regionNot supported in the US1-FED region" DD_API_KEY="<DD_API_KEY>" go run "main.go"
// Send server-side events returns "Request accepted for processing (always 202 empty JSON)."
// 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.ProductAnalyticsServerSideEventItem;
import com.datadog.api.client.v2.model.ProductAnalyticsServerSideEventItemAccount;
import com.datadog.api.client.v2.model.ProductAnalyticsServerSideEventItemApplication;
import com.datadog.api.client.v2.model.ProductAnalyticsServerSideEventItemEvent;
import com.datadog.api.client.v2.model.ProductAnalyticsServerSideEventItemSession;
import com.datadog.api.client.v2.model.ProductAnalyticsServerSideEventItemType;
import com.datadog.api.client.v2.model.ProductAnalyticsServerSideEventItemUsr;

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

    ProductAnalyticsServerSideEventItem body =
        new ProductAnalyticsServerSideEventItem()
            .account(new ProductAnalyticsServerSideEventItemAccount().id("account-67890"))
            .application(
                new ProductAnalyticsServerSideEventItemApplication()
                    .id("123abcde-123a-123b-1234-123456789abc"))
            .event(new ProductAnalyticsServerSideEventItemEvent().name("payment.processed"))
            .session(new ProductAnalyticsServerSideEventItemSession().id("session-abcdef"))
            .type(ProductAnalyticsServerSideEventItemType.SERVER)
            .usr(new ProductAnalyticsServerSideEventItemUsr().id("user-12345"));

    try {
      apiInstance.submitProductAnalyticsEvent(body);
    } catch (ApiException e) {
      System.err.println("Exception when calling ProductAnalyticsApi#submitProductAnalyticsEvent");
      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="Not supported in the US1 regionNot supported in the US3 regionNot supported in the US5 regionNot supported in the EU regionNot supported in the AP1 regionNot supported in the AP2 regionNot supported in the US1-FED region" DD_API_KEY="<DD_API_KEY>" java "Example.java"
// Send server-side events returns "Request accepted for processing (always 202
// empty JSON)." response
use datadog_api_client::datadog;
use datadog_api_client::datadogV2::api_product_analytics::ProductAnalyticsAPI;
use datadog_api_client::datadogV2::model::ProductAnalyticsServerSideEventItem;
use datadog_api_client::datadogV2::model::ProductAnalyticsServerSideEventItemAccount;
use datadog_api_client::datadogV2::model::ProductAnalyticsServerSideEventItemApplication;
use datadog_api_client::datadogV2::model::ProductAnalyticsServerSideEventItemEvent;
use datadog_api_client::datadogV2::model::ProductAnalyticsServerSideEventItemSession;
use datadog_api_client::datadogV2::model::ProductAnalyticsServerSideEventItemType;
use datadog_api_client::datadogV2::model::ProductAnalyticsServerSideEventItemUsr;

#[tokio::main]
async fn main() {
    let body = ProductAnalyticsServerSideEventItem::new(
        ProductAnalyticsServerSideEventItemApplication::new(
            "123abcde-123a-123b-1234-123456789abc".to_string(),
        ),
        ProductAnalyticsServerSideEventItemEvent::new("payment.processed".to_string()),
        ProductAnalyticsServerSideEventItemType::SERVER,
    )
    .account(ProductAnalyticsServerSideEventItemAccount::new(
        "account-67890".to_string(),
    ))
    .session(ProductAnalyticsServerSideEventItemSession::new(
        "session-abcdef".to_string(),
    ))
    .usr(ProductAnalyticsServerSideEventItemUsr::new(
        "user-12345".to_string(),
    ));
    let configuration = datadog::Configuration::new();
    let api = ProductAnalyticsAPI::with_config(configuration);
    let resp = api.submit_product_analytics_event(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="Not supported in the US1 regionNot supported in the US3 regionNot supported in the US5 regionNot supported in the EU regionNot supported in the AP1 regionNot supported in the AP2 regionNot supported in the US1-FED region" DD_API_KEY="<DD_API_KEY>" cargo run
/**
 * Send server-side events returns "Request accepted for processing (always 202 empty JSON)." response
 */

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

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

const params: v2.ProductAnalyticsApiSubmitProductAnalyticsEventRequest = {
  body: {
    account: {
      id: "account-67890",
    },
    application: {
      id: "123abcde-123a-123b-1234-123456789abc",
    },
    event: {
      name: "payment.processed",
    },
    session: {
      id: "session-abcdef",
    },
    type: "server",
    usr: {
      id: "user-12345",
    },
  },
};

apiInstance
  .submitProductAnalyticsEvent(params)
  .then((data: any) => {
    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="Not supported in the US1 regionNot supported in the US3 regionNot supported in the US5 regionNot supported in the EU regionNot supported in the AP1 regionNot supported in the AP2 regionNot supported in the US1-FED region" DD_API_KEY="<DD_API_KEY>" tsc "example.ts"

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

概要

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.

リクエスト

Body Data (required)

Expand All

フィールド

種類

説明

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"
  }
}

応答

OK

Response for a scalar analytics query.

Expand All

フィールド

種類

説明

data

object

Data object for a scalar response.

attributes

object

columns

[object]

meta

object

unit

[object]

family

string

id

int64

name

string

plural

string

scale_factor

double

short_name

string

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

type

enum

meta

object

Metadata for a Product Analytics query response.

request_id

string

status

enum

{
  "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

フィールド

種類

説明

errors [required]

[string]

A list of errors.

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

Not Authorized

API error response.

Expand All

フィールド

種類

説明

errors [required]

[string]

A list of errors.

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

Too many requests

API error response.

Expand All

フィールド

種類

説明

errors [required]

[string]

A list of errors.

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

コード例

                  # 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.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": { "audience_filters": { "accounts": [ { "name": "" } ], "segments": [ { "name": "", "segment_id": "" } ], "users": [ { "name": "u" } ] }, "compute": { "aggregation": "count" }, "group_by": [ { "facet": "@view.name" } ], "query": {} }, "to": 1771836848262 }, "type": "formula_analytics_extended_request" } } EOF

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

概要

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.

リクエスト

Body Data (required)

Expand All

フィールド

種類

説明

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"
  }
}

応答

OK

Response for a timeseries analytics query.

Expand All

フィールド

種類

説明

data

object

attributes

object

intervals

[object]

milliseconds

int64

start_time

int64

times

[integer]

type

string

series

[object]

group_tags

[string]

query_index

int64

unit

[object]

family

string

id

int64

name

string

plural

string

scale_factor

double

short_name

string

times

[integer]

Timestamps for each data point (epoch milliseconds).

values

[array]

Values for each series at each time point.

id

string

type

enum

meta

object

Metadata for a Product Analytics query response.

request_id

string

status

enum

{
  "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

フィールド

種類

説明

errors [required]

[string]

A list of errors.

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

Not Authorized

API error response.

Expand All

フィールド

種類

説明

errors [required]

[string]

A list of errors.

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

Too many requests

API error response.

Expand All

フィールド

種類

説明

errors [required]

[string]

A list of errors.

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

コード例

                  # 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.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": { "audience_filters": { "accounts": [ { "name": "" } ], "segments": [ { "name": "", "segment_id": "" } ], "users": [ { "name": "u" } ] }, "compute": { "aggregation": "count" }, "group_by": [ { "facet": "@view.name" } ], "query": {} }, "to": 1771836848262 }, "type": "formula_analytics_extended_request" } } EOF