--- title: Retention description: >- Measure user retention to understand overall user satisfaction with your application. breadcrumbs: Docs > Product Analytics > Charts > Retention --- > For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt). # Retention {% callout %} # Important note for users on the following Datadog sites: app.ddog-gov.com, us2.ddog-gov.com {% alert level="danger" %} This product is not supported for your selected [Datadog site](https://docs.datadoghq.com/getting_started/site.md). ({% placeholder "user-datadog-site-name" /%}). {% /alert %} {% /callout %} Retention charts visualize how often users return to a page or action, helping you assess the ongoing value of your products and features. {% image source="https://docs.dd-static.net/images/product_analytics/retention/retention_chart.9b1fa7e0267d94ead2f59ec683001ccc.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/product_analytics/retention/retention_chart.9b1fa7e0267d94ead2f59ec683001ccc.png?auto=format&fit=max&w=850&dpr=2 2x" alt="An example Retention Analysis chart." /%} User retention is measured within a *cohort*, a group of users who performed a defined start event, such as clicking a specified link. A user in the cohort is *retained* if they subsequently complete the specified return event, such as clicking the same link again or proceeding to payment. Only views and actions can act as events. ## Prerequisites{% #prerequisites %} To populate retention data, set the `usr.id` attribute in your SDK. See [instructions for sending unique user attributes](https://docs.datadoghq.com/real_user_monitoring/application_monitoring/browser/advanced_configuration.md#user-session). ## Calculating retention events{% #calculating-retention-events %} Retention values are calculated as a weighted average cohort, which summarizes overall cohort behavior by accounting for cohort size. Larger cohorts have more influence on the final value, making the result more representative than an average. Datadog applies this calculation across all visualization types. For example, in the retention grid, the weighted average populates the summary cell for each time interval. To calculate the value for a specific interval, such as week 1 in the retention grid, multiply each cohort's value by its size. Sum the results, then divide by the total cohort size: ``` Weighted Average = (Σ (cohort_value × cohort_size)) / (Σ cohort_size) ``` For example, the weighted average retention of 91% after 1 week is calculated as: ``` (99 * 1.8k + 92 * 2.35k + 81 * 1.75k) / (1.8k + 2.35k + 1.75k) ``` Each cohort's retention rate is scaled by its number of users before it contributes to the overall metric. {% image source="https://docs.dd-static.net/images/product_analytics/retention/pana_retention_weighed_avg.a1338a3117bf30c9bb488c2e6a7e9f2a.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/product_analytics/retention/pana_retention_weighed_avg.a1338a3117bf30c9bb488c2e6a7e9f2a.png?auto=format&fit=max&w=850&dpr=2 2x" alt="Example Retention Analysis graph showing a weighted average retention value." /%} {% alert level="info" %} The retention chart displays disabled values when data is partial or incomplete. This occurs when the time period is ongoing and retention can't yet be fully calculated. {% /alert %} ## Create a retention chart{% #create-a-retention-chart %} 1. In Product Analytics, select Create New > Retention. 1. Define start and return steps that you want to understand retention for. 1. (Optional) Filter or group chart results based on properties such as country or device type using Filter by or Compare by. ## Analyze a retention chart{% #analyze-a-retention-chart %} After you build a retention chart, it displays retention as a percentage or count for each cohort, broken down by the return periods you defined. {% image source="https://docs.dd-static.net/images/product_analytics/retention/retention_analysis.4e3397f730b10483cb32559057995b01.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/product_analytics/retention/retention_analysis.4e3397f730b10483cb32559057995b01.png?auto=format&fit=max&w=850&dpr=2 2x" alt="A Retention chart with numbered callouts for the Advanced options return setting, the viewing and grouping controls, the chart type selector, the time range selector, and a cohort cell tooltip." /%} 1. Use Advanced options to scope which return events count toward retention. - Returned on: Calculates the percentage of users who triggered the return event during a specific return period. Use this to see the likelihood of users completing the return event some period of time (for example, days or weeks) after the start event, which is useful for assessing overall retention across your features and products. - Returned on or after: Calculates the percentage of users who triggered the return event during a specific return period or any subsequent period. Use this to see users who either fully leave your product or stop using key functionality, which is useful for assessing the effectiveness of onboarding experiences. 1. Use the Viewing row to control what displays. - All Cohorts, Weighted Average, or a specific cohort: Selects which cohort is plotted. See Calculating retention events for how the weighted average is calculated. - Unique users or Unique accounts: Selects whether retention is measured by `@usr.id`, which can reset when a user clears cookies or switches devices, or by `@account.id`, which tracks the same signed-in account across a longer period. - Rate or Count: Selects whether to display retention as a percentage or an absolute number. - Each day, Each week, or Each month: Selects the time frame that groups return events. Daily retention can be applied for up to a month, weekly retention for up to a year, and monthly retention for up to 16 months. 1. Use the chart type selector to switch between chart types. - Retention: Includes both a retention curve, showing the change in retention for specified cohorts, and a retention grid, showing detailed data on cohorts across time periods. - Timeseries: Shows retention over calendar time for a single return period you choose, without a specific cohort focus. - Query value: Shows a single number, as a rate or count, for a single return period you choose, using whichever cohort is selected: the weighted average across cohorts, or one specific cohort. - Top list: If a Compare property is specified, shows an ordered ranking of grouped results by retention rate or count for the specified period. 1. Use the time range selector to change the period of data the chart analyzes. 1. Hover over a cell to view the exact number of users who returned during that period, the return rate, and how it changed from the previous period. Click a cell to view a list of users, and export the list as a CSV. ### Using matching vs. differing events{% #using-matching-vs-differing-events %} You can configure retention charts with the same or different start and return events. If the events match, week 0 is always 100%, since it represents everyone who completed the initial event. Every other cell compares that week's viewers back to week 0, showing the percentage of the original cohort who completed the event again in that week. {% image source="https://docs.dd-static.net/images/product_analytics/retention/retention_matching_events.34def1ba11073c70a915e744923256bf.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/product_analytics/retention/retention_matching_events.34def1ba11073c70a915e744923256bf.png?auto=format&fit=max&w=850&dpr=2 2x" alt="Retention graph for matching events." /%} Reading the **Aug 17 2026** row of the above graph from left to right: - 23% of the 10.43k users who completed the event that week returned to complete it again after 1 week. - 21% of those users returned to complete it again after 2 weeks. - 11% of those users returned to complete it again after 3 weeks. If the events differ, week 0 represents users who completed both the initial and return events. Every cell after that shows the percentage of the original cohort who completed the return event in that week. {% image source="https://docs.dd-static.net/images/product_analytics/retention/retention_differing_events.eb370607bdaff70c107dc114bf23a556.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/product_analytics/retention/retention_differing_events.eb370607bdaff70c107dc114bf23a556.png?auto=format&fit=max&w=850&dpr=2 2x" alt="Retention graph for differing events." /%} Reading the **Aug 17 2026** row of the above graph from left to right: - 10.43k users completed the start event that week. - 41% of those users also completed the return event within the same week. - 23% completed the return event after 1 week, 20% after 2 weeks, and 11% after 3 weeks.