GamebeastDocs
Dashboard

Retention

Measure how many players come back after doing something: day 1, day 7 and day 30 retention, the retention curve, and a cohort grid.

Retention answers one question: of the players who did something, how many came back and did something later? Pick a start event and a return event, and Gamebeast groups players by the day they did the start event, then follows each group forward to see how many returned on day 1, day 2, day 3 and so on.

ALogin
B
Retention criteriaEach Day
By
Show
Retention curve over 10 daily cohorts0%25%50%75%100%Day 0Day 1Day 2Day 3Day 4Day 5Day 6Day 7Day 8Day 9Day 0: 100% (3,547 of 3,547 players). 9 of 10 cohorts have reached this day.Day 1: 34.9% (1,082 of 3,100 players). 8 of 10 cohorts have reached this day.Day 2: 31.01% (827 of 2,667 players). 7 of 10 cohorts have reached this day.Day 3: 27.52% (623 of 2,264 players). 6 of 10 cohorts have reached this day.Day 4: 25.98% (479 of 1,844 players). 5 of 10 cohorts have reached this day.Day 5: 23.58% (336 of 1,425 players). 4 of 10 cohorts have reached this day.Day 6: 20.37% (208 of 1,021 players). 3 of 10 cohorts have reached this day.Day 7: 18.2% (123 of 676 players). 2 of 10 cohorts have reached this day.Day 8: 14.74% (46 of 312 players). 1 of 10 cohorts have reached this day.Day 9: 9.29% (29 of 312 players). This day is still in progress.
Still in progress
InteractiveChange the return event, switch between On and On or after, break it down by platform, and switch between the retention curve, the cohort grid and a line. Hover a point or a cell to see the players behind it.

Retention is built from the markers your experience already sends, so you can measure any period you have data for without adding new events.

How retention is measured

Three rules cover every retention query:

  1. Players are grouped into cohorts. A cohort is everyone who did the start event in the same day (or week, or month).
  2. Each cohort is followed forward. A player is retained on day N when they did the return event N days after their cohort's day. Day 0 is the cohort's own day.
  3. The rate is out of the cohort. Day 7 retention is the share of that cohort's players who returned on day 7.

For example, with Login as both events: if 200 players log in on March 1 and 70 of them log in again on March 2, the March 1 cohort has 35% day 1 retention.

Days are calendar days in the query's timezone. Weeks are calendar weeks starting on Monday, and months are calendar months.

A player is in the cohort of every day they did the start event. Someone who logs in on March 1 and March 2 is in both cohorts, and counts as a day 1 return for March 1. To measure only players who are new, see New-player retention.

Creating a retention query

Open a dashboard, click Edit, then Add panel → Query, and select Retention from the query types at the top of the query setup.

A retention query has two steps:

  • A, the start event: what a player has to do to enter a cohort.
  • B, the return event: what counts as coming back.

Use the same event for both to measure plain return visits, such as Login and Login. Use two different events to ask whether one action leads to another later: with Login as A and Purchase as B, day 3 is the share of players who logged in and then bought something three days later.

Retention criteria

Under the two steps, Retention criteria sets how a return is counted.

When a return counts

OptionA player is retained on day N when they…Use it for
Oncame back in that exact dayClassic day N retention. The default.
On or aftercame back in that day or any later one"Still around" retention: players who hadn't left for good by day N.

On or after is never lower than On. Within a cohort it never rises from one day to the next, because each day includes every day after it. It also keeps rising after the day is over, as more players return later: last month's day 7 value will be higher next week than it is today.

The window

Each Day, Each Week or Each Month sets both the size of a cohort and the unit of N. With Each Week, a cohort is everyone who did the start event in the same calendar week, and week 1 is the week after.

What to show

At the bottom of the step builder:

  • Retention Rate shows the percentage of the cohort that returned. Unique Users shows the number of players who returned.
  • Day 1, Day 7 and so on picks which day to measure, up to day 30, week 12 or month 12. The retention curve and the cohort grid show every day, so this option is hidden for them.

Time range

The time range picks which cohorts the query shows: every day (week, month) the range touches is a cohort. Returns are counted after the range ends too, so a query over last week still measures day 7 for last week's cohorts.

A query covers at most 400 cohorts. For a longer range, switch from Each Day to Each Week or Each Month.

Days that can't be measured yet

Recent cohorts haven't had time to return. A cohort that joined yesterday has no day 7 retention yet, and Gamebeast shows that as missing, never as 0%.

Every value is one of three kinds:

KindWhat it meansHow it's shown
FinalThe day being measured is over.Solid line, filled marker, shaded grid cell
Still in progressThe day being measured is today, so the value will still rise.Dashed line, hollow marker, dashed cell outline
Not measurable yetThe day being measured hasn't started. There is no value.Nothing is drawn. The stretch is shaded and labeled on charts, and hatched in the grid

A value that combines several cohorts, such as a single number or a point on the retention curve, only counts the cohorts whose day is over. Cohorts that haven't got there are left out instead of pulling the value down, and the value says how many it covers: "22 of 30 days measured" beside a single number, or "8 of 10 cohorts have reached this day" when you hover a point on the curve.

Chart types

Pick the chart from the controls above the preview.

Retention Curve

The retention curve shows how retention falls off after players join. The x axis is the day number (day 0, day 1, day 2, …), the y axis is retention, and every cohort in the time range is combined into one line, weighted by cohort size.

  • The curve shows up to 30 days, 12 weeks or 12 months, and never more days than have passed since the start of the time range.
  • Later days are read from fewer, older cohorts, because newer cohorts haven't reached them yet. Hover a point to see how many cohorts it covers.
  • Look for where the curve flattens: that is the share of players who stay.

Cohort Grid

The cohort grid shows one row per cohort and one column per day number. Each cell is that cohort's retention on that day, shaded by how high it is. Beside each cohort is the number of players in it.

  • The first row, All cohorts, combines every cohort and matches the retention curve.
  • Newer cohorts have had less time to return, so the grid fills in as a staircase: the bottom-right cells are hatched until those days can be measured.
  • Read down a column to see whether a given day is getting better or worse for newer cohorts. Read along a row to follow one cohort over time.
  • Shading is scaled to the highest value after day 0, so differences between later days stay visible.
  • Hover a cell to see the players behind it.

Line

A line chart follows one day number across cohorts: day 1 retention for each day in the range, for example. Use it to see whether retention is trending up or down.

Each point sits on the day its cohort joined, not the day they returned. The most recent points are dashed while their day is still in progress, and the days that can't be measured yet are shaded.

Change the granularity to combine cohorts: day 1 retention at Week granularity gives one point per week, covering that week's seven daily cohorts. The granularity is never finer than the window.

Stacked Line, Column and Stacked Column show the same values in a different shape.

Metric and the other charts

Metric shows one number: retention on the chosen day across every cohort in the time range whose day is over, weighted by cohort size. Bar, Stacked Bar, Pie, Table and World Map show that same whole-range value for each breakdown value.

Filters

Where you put a filter decides what it limits:

Filter onLimitsExample
Step A (local filter)Who enters a cohort. Returns are counted as usual.Players who finished the tutorial, and whether they logged in later.
Step B (local filter)Which returns count. The cohort stays the same.Players who logged in, and whether they bought the starter pack later.
Global Filters (global filter)Both events.Only events on mobile.

A global filter on an argument or property only works if both events have it. If they don't, filter the step that has it.

New-player retention

By default a cohort is everyone who did the start event that day, new or not. To measure how well you keep new players, add a New User filter (the User tab of the filter picker), globally or on step A. Only start events from a player's first-ever session then count, so each player enters the cohort of the day they first played, and their returns are counted on every day after it.

First Occurrence works the same way for the start event itself: each player enters the cohort of the first time they ever did it, such as their first purchase.

Both describe who enters a cohort. On step B they have no effect.

To follow a group defined by what players did, such as spenders or players who reached level 10, filter by a cohort.

Breakdowns

A breakdown splits retention by a property, argument, cohort or experiment, with one line, row or number per value.

  • Values are read from the start event. A player who did step A on PC and step B on mobile counts as a PC return. The two events don't need to share the property.
  • The curve draws one line per value. The cohort grid shows one row per value instead of one row per cohort, with every cohort combined.
  • There is no combined total. A player can be in more than one group, for example by starting on two platforms, so groups don't add up to a whole and the grid has no All cohorts row.
  • List properties put a player in one group per item in the list.
  • A limit keeps the largest groups, by the number of players who entered them. The rest are left out, not combined into an Other group, and the cohort grid says how many are shown: "Showing the 10 largest of 42 groups".

Saving, dashboards and export

Save a retention query like any other; see Saving a query. On a dashboard it refreshes with the dashboard, and values that were in progress become final as their days end.

Export to → CSV in a chart's ⋮ menu downloads the data. For the cohort grid the file matches the grid: one line per cohort, one column per day, with cells that have no value left empty rather than written as 0.

Tips

  • Start with the Retention Curve to see the overall shape, then switch to the Cohort Grid to see which cohorts are behind it.
  • Put day 1, day 7 and day 30 on a dashboard as three Metric or Line charts to track them over time.
  • Don't read the newest points as a drop. A dashed line or a dashed cell is still filling in.
  • For day 30 retention, use a time range long enough that some cohorts are more than 30 days old. In a 30-day range, no cohort has finished day 30 yet.
  • Compare a change by breaking down by an experiment or a cohort, not by comparing two time ranges with different seasonality.

Changes to older retention queries

Retention is always measured forward from the day a player joined a cohort. Older retention queries were updated automatically, and some of them show different numbers than before:

  • Look Back is gone. It was the default in the query builder, so a query saved without changing it used it. Those queries now measure forward like every other retention query.
  • On or before is gone. Queries saved with it now use On.
  • On or after now counts returns on any later day, as described above. Before, it was calculated the same way as On, so queries saved with it now show higher values.

With the assistant

Ask the assistant things like "what's our day 7 retention?", "show the retention curve for new players this month" or "do players who finish the tutorial come back more?". It builds the query, shows the chart in the chat, and tells you which values are still in progress. It can open the chart in the query builder or add it to a dashboard. Agents connected over MCP can build, run and save retention queries too.

With the API

Run a retention query from your own tools with Execute retention query. Values that can't be measured yet come back as null with state: "pending", never as zero.

On this page