--- title: "Compute retention scalar values" method: POST path: "/api/v2/product-analytics/retention/scalar" tags: ["Product Analytics"] --- # Compute retention scalar values `POST /api/v2/product-analytics/retention/scalar` ## Request - Base URL: `https://api.datadoghq.com` - URL: `https://api.datadoghq.com/api/v2/product-analytics/retention/scalar` - 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` - TypeScript: (a function with typed inputs; its response is checked against the schema) Compute retention as a single value per group, suitable for a query value or top list widget. ## Request body - ProductAnalyticsFormulaRetentionRequest: Request body for a retention scalar or retention timeseries query. - `data` ProductAnalyticsFormulaRetentionRequestData, required: The single JSON:API resource carrying a retention scalar or timeseries query. Its attributes hold the time window to query and the retention query definition to evaluate. - `attributes` ProductAnalyticsFormulaRetentionRequestAttributes, required: Attributes of a retention scalar or retention timeseries request. - `exclude_anonymous_traffic` boolean: Whether to exclude sessions that are not tied to an identified user. - `from` integer, required: Start of the query window, in epoch milliseconds. - `query` ProductAnalyticsFormulaRetentionQuery, required: Query definition for a retention scalar or retention timeseries request. - `computation_scope` union: Restricts a retention query to part of the grid, so that results can be examined in detail. Omit it to compute the whole grid. - ProductAnalyticsRetentionCohortScope: Narrows a retention query to a single cohort row. - `target` union, required: Selects a cohort, either by index or by the aggregation that rolls all cohorts together. - … - `type` 'cohort', required: The discriminator identifying a scope narrowed to one cohort. - ProductAnalyticsRetentionReturnPeriodScope: Narrows a retention query to a single return-period column. - `target` ProductAnalyticsRetentionIndexTarget, required: Selects a cohort or return period by its zero-based position in the grid. - … - `type` 'return_period', required: The discriminator identifying a scope narrowed to one return period. - ProductAnalyticsRetentionCellScope: Narrows a retention query to a single cell, at the intersection of one cohort and one return period. - `cohort_target` union, required: Selects a cohort, either by index or by the aggregation that rolls all cohorts together. - … - `return_period_target` ProductAnalyticsRetentionIndexTarget, required: Selects a cohort or return period by its zero-based position in the grid. - … - `type` 'cell', required: The discriminator identifying a scope narrowed to one grid cell. - `compute` ProductAnalyticsRetentionCompute, required: The metric and aggregation applied to a retention query. - `aggregation` string, required: The aggregation function applied to the metric, such as `count` or `avg`. - `metric` '__dd.retention' | '__dd.retention_rate', required: The retention metric to compute, either an absolute count or a rate. - `group_by` ProductAnalyticsRetentionGroupBy[]: Splits the results by the values of one or more facets. - `facet` string, required: The attribute path to group by. - `limit` integer: Maximum number of groups to return. Omit it to let the service choose. - `should_exclude_missing` boolean: Whether to drop entities that have no value for the facet. - `sort` ProductAnalyticsGroupBySort: Sort configuration for group-by results. - `aggregation` string: The aggregation function to sort by. - `metric` string: The metric to sort by. - `order` 'asc' | 'desc': Direction of sort. - `source` string: Audience source backing the group-by, when grouping by an audience rather than a facet. - `target` 'cohort' | 'return_period', required: Which axis of the retention grid a group-by applies to. - `search` ProductAnalyticsRetentionSearch, required: Defines the cohort and return criteria that make up a retention query. - `cohort_criteria` ProductAnalyticsRetentionCohortCriteria, required: Defines the event that places an entity into a cohort, and how cohorts are bucketed over time. - `base_query` union, required: A query definition discriminated by the `data_source` field. Use `product_analytics` for standard event queries, or `product_analytics_occurrence` for occurrence-filtered queries. - … - `time_interval` union, required: A retention interval, either aligned to calendar boundaries or of a fixed length. Cohort criteria use calendar intervals; return criteria use fixed intervals. - … - `filters` ProductAnalyticsRetentionFilters: Filters narrowing the events considered by a retention query. - `audience_filters` ProductAnalyticsAudienceFilters: Audience filter definitions for targeting specific user segments. - … - `string_filter` string: Free-text search query applied to the events. - `retention_entity` '@usr.id' | '@account.id', required: The entity whose retention is measured. - `return_condition` 'conversion_on' | 'conversion_on_or_after', required: When an entity counts as having returned. Use `conversion_on` to count only entities that returned during the period itself, or `conversion_on_or_after` to also count later returns. - `return_criteria` ProductAnalyticsRetentionReturnCriteria: Defines the event that counts as a return, and the window in which it must occur. - `base_query` union, required: A query definition discriminated by the `data_source` field. Use `product_analytics` for standard event queries, or `product_analytics_occurrence` for occurrence-filtered queries. - … - `time_interval` union: A retention interval, either aligned to calendar boundaries or of a fixed length. Cohort criteria use calendar intervals; return criteria use fixed intervals. - … - `to` integer, required: End of the query window, in epoch milliseconds. - `type` 'formula_retention_request', required: The resource type identifier for a retention scalar or retention timeseries request. ## Response `200` OK - ProductAnalyticsScalarResponse: Response for a scalar analytics query. - `data` ProductAnalyticsScalarResponseData: Data object for a scalar response. - `attributes` ProductAnalyticsScalarResponseAttributes: Attributes of a scalar analytics response, containing the result columns. - `columns` ProductAnalyticsScalarColumn[]: The list of result columns, each containing values and metadata. - `meta` ProductAnalyticsScalarColumnMeta: Metadata associated with a scalar response column, including optional unit information. - `unit` ProductAnalyticsUnit[], nullable: Unit definitions for the column values, if applicable. - `family` string: The unit family (e.g., time, bytes). - `id` integer: 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` number, 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` 'number' | 'group': Column type. - `values` unknown[]: Column values. - unknown - `id` string: Unique identifier for this response data object. - `type` 'scalar_response': The resource type identifier for a scalar analytics response. - `meta` ProductAnalyticsResponseMeta: Metadata for a Product Analytics query response. - `request_id` string: Unique identifier of the query. - `status` 'done' | 'running' | 'timeout': The execution status of a Product Analytics query. ## Other responses - `400`: Bad Request - `403`: Not Authorized - `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)