---
name: mixpanel-weekly-retention
description: "Every Monday: week 1 and week 4 retention for the latest weekly signup cohorts in Mixpanel, and whether newer cohorts hold up better. Use when the user asks for this, or when it runs on a schedule."
---

# Mixpanel weekly retention

Every Monday: week 1 and week 4 retention for the latest weekly signup cohorts in Mixpanel, and whether newer cohorts hold up better.

Retention is slow feedback. A change to onboarding shipped this week shows up in week 1 retention next week and in week 4 retention a month from now, by which point nobody remembers to look. Mixpanel's retention report has the numbers, but reading a cohort triangle every Monday is a habit few people keep.

The agent reads the triangle for you. It pulls the recent weekly signup cohorts from the Query API, takes week 1 and week 4 for each, and posts the latest complete week 1 figure as a tile, with week 4 filled in as soon as a cohort is old enough to have one.

## Two ways to get the data

Use the API or MCP route when you have an MCP server, a CLI or an API token for the app. Otherwise, if you can drive a browser the user is signed in to (Claude in Chrome, a Playwright or Chrome DevTools MCP server), use the browser route. Say which one you used.

## Route A: API or MCP server

### What you need

- A Mixpanel service account with access to the project (username and secret in `MIXPANEL_SA_USERNAME` and `MIXPANEL_SA_SECRET`) and the project ID. EU-resident projects use `eu.mixpanel.com`.
- The event that starts a cohort (for example `Sign Up`) and, if any event is too loose a return, the event that should count.

If something is missing, say what and stop; do not invent numbers.

### Steps

1. **Query the retention endpoint** (Mixpanel): `GET https://mixpanel.com/api/query/retention` with `project_id`, `from_date` 12 weeks ago, `to_date` last Sunday, `retention_type=birth`, `born_event=Sign Up` and `unit=week`, with no `event` so any event counts as a return. Authenticate as a service account with HTTP basic auth.
2. **Read the cohorts**: The response is keyed by cohort start date, each with `first` (the cohort size) and `counts` (users returning in each later week). Week 1 retention is `counts[1] / first`; week 4 is `counts[4] / first`.
3. **Leave incomplete weeks blank**: A cohort has a week 1 figure only after its second full week has ended, and week 4 after its fifth. Show the cell as not yet, never as a drop to zero.
4. **Compare recent cohorts**: Average week 1 for the last 4 complete cohorts against the 4 before, and week 4 where enough cohorts have it. Flag any cohort 3 or more points below the average.
5. **Post the retention tile**: Headline: week 1 retention of the newest complete cohort. Glance: the 4-cohort averages. Widget: the last 8 cohorts with size, week 1 and week 4.

## Route B: the browser

### What you need

- Signed in to Mixpanel with at least Consumer access to the project; the Retention report is on every plan.

If something is missing, say what and stop; do not invent numbers.

### Steps

Start at https://mixpanel.com/report. The user is signed in already; never type passwords or codes, and ask if a sign-in page appears.

1. **Open the Retention report**: Mixpanel report URLs carry the project ID, so start at the reports landing page, pick the project (EU projects live at `eu.mixpanel.com`), and open **Retention** from the report picker.
2. **Set the cohort and the return**: In the first slot choose your signup event (for example `Sign Up`) and in the second slot leave **Any Event** as the return event. Set the time unit to **Each Week** and keep the default **On or After** retention criteria. Set the date range to the **last 12 weeks** ending last Sunday.
3. **Read the cohort table**: Below the curve the table lists one row per weekly cohort with its size and a cell per week. Note size, the **Week 1** cell and the **Week 4** cell for the last 8 cohorts. Cells marked with an asterisk are still in progress, so record them as not yet rather than as a value.
4. **Compare recent cohorts**: Average week 1 for the last 4 complete cohorts against the 4 before, and week 4 where enough cohorts have it. Flag any cohort 3 or more points below its average.
5. **Write the tile up**: Week 1 retention of the newest complete cohort, the two averages, and the 8-cohort table with size, week 1 and week 4.

Note: The table shades cells relative to each row, so read the numbers, not the colors. Week 0 in Mixpanel is the signup week itself; week 1 is the first full week after it, the same as counts[1] in the API route.

## The report

- **Week 1 retention** for the newest complete cohort.
- **Cohort table**: size, week 1 and week 4 for the last 8 weekly cohorts, blank where a week is not over.
- **Averages**: the last 4 cohorts against the 4 before.
- Cohorts 3 or more points below average.

## Post it to Briefkin

When `BRIEFKIN_TOKEN` is set, or `~/.config/briefkin/env` exists (the installer from https://briefkin.dev/docs writes it), also send the result to the user's Briefkin board as one card. Keep the `item_key` the same on every run so the card updates in place, use a new `event_id` per run, and put today's real numbers in place of the example ones. If the request fails, say so once and carry on.

```bash
[ -n "${BRIEFKIN_TOKEN:-}" ] || . ~/.config/briefkin/env
curl -sS -X POST "${BRIEFKIN_URL:-https://briefkin.dev}/v1/events" \
  -H "authorization: Bearer $BRIEFKIN_TOKEN" \
  -H "content-type: application/json" \
  -d @- <<'JSON'
{
  "v": 1,
  "event_id": "mixpanel-weekly-retention/<date of this run, e.g. 2026-10-16>",
  "item_key": "mixpanel-weekly-retention",
  "project": "Acme",
  "source": "Mixpanel weekly retention skill",
  "kind": "metric",
  "title": "Week 1 retention 38% for the Sep 28 cohort",
  "metric": {
    "label": "Week 1 retention",
    "value": 38,
    "unit": "%",
    "better": "higher",
    "period_start": "<start of the period, ISO 8601>",
    "period_end": "<end of the period, ISO 8601>"
  },
  "glance": {
    "type": "Grid",
    "props": {
      "columns": 2
    },
    "children": [
      {
        "type": "Stat",
        "props": {
          "label": "Week 1, last 4 cohorts",
          "value": 36.5,
          "unit": "%",
          "delta": 6
        }
      },
      {
        "type": "Stat",
        "props": {
          "label": "Week 4, last 4 cohorts",
          "value": 21.3,
          "unit": "%"
        }
      }
    ]
  },
  "widget": [
    {
      "type": "Table",
      "props": {
        "columns": [
          "Cohort (week of)",
          "Users",
          "Week 1",
          "Week 4"
        ],
        "align": [
          "left",
          "right",
          "right",
          "right"
        ],
        "rows": [
          [
            "Aug 10",
            1240,
            "33%",
            "19%"
          ],
          [
            "Aug 17",
            1315,
            "35%",
            "21%"
          ],
          [
            "Aug 24",
            1198,
            "34%",
            "20%"
          ],
          [
            "Aug 31",
            1402,
            "36%",
            "22%"
          ],
          [
            "Sep 7",
            1356,
            "35%",
            "22%"
          ],
          [
            "Sep 14",
            1287,
            "37%",
            "not yet"
          ],
          [
            "Sep 21",
            1431,
            "36%",
            "not yet"
          ],
          [
            "Sep 28",
            1509,
            "38%",
            "not yet"
          ]
        ]
      }
    },
    {
      "type": "Callout",
      "props": {
        "text": "The last 4 cohorts average 36.5% in week 1, two points above the 4 before. Week 4 is flat at about 21%.",
        "tone": "info"
      }
    }
  ],
  "size": "md"
}
JSON
```

Widgets come from the Briefkin catalog (https://briefkin.dev/v1/catalog). Without a token, just give the user the report.

Set `period_start` and `period_end` to the window the number covers: the tile names it from them ("Last 7 days", "Today", "This month"). For a count right now (open items, a balance), send `"period_label": ""` so no period shows; for another name, send it as `period_label` (at most 24 characters).

## Run it on a schedule

Suggested: Mondays at 10:00 (`0 10 * * 1`). From cron, with the agent signed in on that machine:

```bash
0 10 * * 1 claude -p "Run the mixpanel-weekly-retention skill"
# Codex: codex exec, Gemini CLI: gemini -p, Copilot CLI: copilot -p, OpenCode: opencode run
```

Or use the agent's own scheduler (Claude Code routines, Codex automations, Claude or ChatGPT scheduled tasks): https://briefkin.dev/skills/mixpanel-weekly-retention#schedule

Source: https://briefkin.dev/skills/mixpanel-weekly-retention
