--- title: "Compute a retention grid" method: POST path: "/api/v2/product-analytics/retention/grid" tags: ["Product Analytics"] --- # Compute a retention grid `POST /api/v2/product-analytics/retention/grid` ## Request - Base URL: `https://api.datadoghq.com` - URL: `https://api.datadoghq.com/api/v2/product-analytics/retention/grid` - 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 a retention grid, showing how much of each cohort came back over each subsequent period. Rows are cohorts, columns are return periods, and each cell holds the count and rate of entities that returned. ## Request body - ProductAnalyticsRetentionGridRequest: Request body for a retention grid query. - `data` ProductAnalyticsRetentionGridRequestData, required: The single JSON:API resource carrying a retention grid query. Its attributes hold the time window to query and the cohort and return criteria that define the grid. - `attributes` ProductAnalyticsRetentionGridRequestAttributes, required: Attributes of a retention grid 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` ProductAnalyticsRetentionGridQuery, required: Query definition for a retention grid or retention metadata 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` 'retention_grid_request', required: The resource type identifier for a retention grid request. ## Response `200` OK - ProductAnalyticsRetentionGridResponse: Response for a retention grid query. - `data` ProductAnalyticsRetentionGridResponseData, required: The single JSON:API resource holding a computed retention grid. Its attributes contain the return periods forming the columns and the cohorts forming the rows. - `attributes` ProductAnalyticsRetentionGridResponseAttributes, required: Attributes of a retention grid response, containing the cohort rows and the period columns. - `cohorts` ProductAnalyticsRetentionGridCohort[]: The cohorts forming the rows of the grid. - `cells` ProductAnalyticsRetentionGridCohortCell[]: The cells of the row, one per return period. - `cell_count` integer: Number of entities that returned during the period. - `cell_rate` number, double: Fraction of the cohort that returned, between `0` and `1`. - `cell_relative_value_change` number, double, nullable: Change in the metric relative to the cohort baseline. - `cell_value` number, double, nullable: Value of the computed metric, when a metric other than the retention rate is requested. - `is_partial_data` boolean: Whether the return period is still open, so the numbers are not yet final. - `return_period_end_time` integer: End of the return period, in epoch milliseconds. - `return_period_index` integer: Zero-based index of the return period this cell belongs to. - `return_period_start_time` integer: Start of the return period, in epoch milliseconds. - `type` 'raw' | 'aggregated': Whether the row holds one cohort's own numbers, or the weighted roll-up across every cohort. - `cohort_end_time` integer: End of the cohort window, in epoch milliseconds. - `cohort_index` integer: Zero-based index of the cohort in the grid. - `cohort_size` integer: Number of entities in the cohort. - `cohort_start_time` integer: Start of the cohort window, in epoch milliseconds. - `group_tags` string[]: The group-by facet values that identify this row. - `name` string: Label identifying the cohort, such as the week it started. - `type` 'raw' | 'aggregated': Whether the row holds one cohort's own numbers, or the weighted roll-up across every cohort. - `unit` ProductAnalyticsUnit[]: Unit definitions for the cell values. - `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). - `retention_entity` string: The entity whose retention was measured. - `retention_periods` ProductAnalyticsRetentionPeriod[]: The return periods forming the columns of the grid. - `unit` string: Time unit of the period, such as `day`, `week`, `month`, or `year`. - `value` integer: Length of the period, expressed in `unit`. - `unit` ProductAnalyticsUnit[]: Unit definitions for the grid values. - `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). - `id` string, required: Unique identifier for this response data object. - `type` 'retention_grid_response', required: The resource type identifier for a retention grid response. ## 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)