---
title: "List the entities behind a retention cell"
method: POST
path: "/api/v2/product-analytics/retention/list"
tags: ["Product Analytics"]
---

# List the entities behind a retention cell

`POST /api/v2/product-analytics/retention/list`

## Request

- Base URL: `https://api.datadoghq.com`
- URL: `https://api.datadoghq.com/api/v2/product-analytics/retention/list`
- 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: <https://skmtc.dev/datadog/apis/datadog-api-v2-collection/docs/api/v2/product-analytics/retention/list/post.ts> (a function with typed inputs; its response is checked against the schema)

List the individual users or accounts counted in one cell of the retention grid.
Set `computation_scope` to the cohort and return period you want to examine.

## Request body

- ProductAnalyticsRetentionListRequest: Request body listing the individual entities behind one cell of the retention grid.
  - `data` ProductAnalyticsRetentionListRequestData, required: The single JSON:API resource carrying a retention list query. Its attributes hold the time window, the cell to list, and the columns to return for each entity.
    - `attributes` ProductAnalyticsRetentionListRequestAttributes, required: Attributes of a retention list request.
      - `from` integer, required: Start of the query window, in epoch milliseconds.
      - `query` ProductAnalyticsRetentionListQuery, required: Query definition for a retention list request.
        - `columns` ProductAnalyticsRetentionListColumn[]: The attribute columns to include in each returned row.
          - `field` ProductAnalyticsRetentionListColumnField: The attribute selected for a column.
            - `path` string: Attribute path of the column.
        - `computation_scope` ProductAnalyticsRetentionCellScope, required: 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.
            - ProductAnalyticsRetentionIndexTarget: Selects a cohort or return period by its zero-based position in the grid.
              - …
            - ProductAnalyticsRetentionAggregationTarget: Selects the rolled-up row that aggregates every cohort, rather than a single cohort.
              - …
          - `return_period_target` ProductAnalyticsRetentionIndexTarget, required: Selects a cohort or return period by its zero-based position in the grid.
            - `type` 'index', required: The discriminator identifying a target selected by index.
            - `value` integer, required: Zero-based index of the targeted cohort or return period.
          - `type` 'cell', required: The discriminator identifying a scope narrowed to one grid cell.
        - `limit` integer: Maximum number of rows to return. Use `0` for no limit.
        - `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_list_request', required: The resource type identifier for a retention list request.

## Response `200`

OK

- ProductAnalyticsRetentionListResponse: Response for a retention list query.
  - `data` ProductAnalyticsRetentionListResponseData, required: The single JSON:API resource holding the entities behind one retention cell. Its attributes contain the entity whose retention was measured and one row per matching entity.
    - `attributes` ProductAnalyticsRetentionListResponseAttributes, required: Attributes of a retention list response, containing the matching entity rows.
      - `records` ProductAnalyticsRetentionListRecord[]: The matching entity rows.
      - `retention_entity` string: The entity whose retention was measured.
    - `id` string, required: Unique identifier for this response data object.
    - `type` 'retention_list_response', required: The resource type identifier for a retention list 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)