Follow Mixpanel week 1 and week 4 retention for recent cohorts

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

Runs
Mondays at 10:00
Posts
Stat tile

From your apps to your board

How the skill works: your agent reads retention endpoint from Mixpanel; mixpanel project id, event that starts a cohort from What you tell it, mondays at 10:00, and gives you week 1 retention and the report in the chat.

Reads

  • MixpanelRetention endpoint
  • What you tell itMixpanel project ID, Event that starts a cohort
reads
Your agentClaude Code, Codex, Cursor or GeminiMondays at 10:00
posts

You get

  • Week 1 retentionA stat tile on your board, with its trend
  • The report in the chatEvery run, with or without Briefkin

What you get

  • 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.

The card on the right is a sample. Yours shows your own numbers and updates in place every run.

What lands on your board

AcmeWeek 1 retention38%+6% vs previous period, bettervs last report
Week 1, last 4 cohorts36.5%+6.0% vs previous period
Week 4, last 4 cohorts21.3%
An example with made-up numbers. Your agent posts your real ones.

What it does

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.

How it works

  1. 1Query the retention endpoint

    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. 2

    2Read 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. 3

    3Leave 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. 4

    4Compare 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. 5

    5Post 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.

  6. Post it to the board

    With BRIEFKIN_TOKEN set, the agent sends the result as one card that updates in place every run. Without it, you get the report in the chat.

Install and run it

Pick your agent, where the data comes from and how to schedule it; the commands below follow.

Agent
Data
Schedule
  1. Install the skill

    One command. It puts the SKILL.md in ~/.claude/skills and in ~/.agents/skills, which Codex, Cursor, Gemini CLI, Copilot CLI and OpenCode read too.

    shellcurl -fsSL https://briefkin.dev/skills/mixpanel-weekly-retention/install | sh
  2. Run it

    Ask Claude Code:

    promptRun the mixpanel-weekly-retention skill

    Or paste the prompt instead of installing:

    promptUsing the Mixpanel Query API retention endpoint, get birth retention by week for users whose born event is Sign Up, for cohorts from the last 12 weeks, with any event counting as a return. For the last 8 cohorts give me cohort size, week 1 retention (counts[1] divided by first) and week 4 retention (counts[4] divided by first), leaving weeks that are not over yet blank. Compare the average week 1 and week 4 of the last 4 complete cohorts with the 4 before, and flag any cohort 3 or more points below average.
  3. Put it on a schedule

    Mondays at 10:00, from cron on any machine where Claude Code is signed in:

    crontab0 10 * * 1 claude -p "Run the mixpanel-weekly-retention skill"

    Add it with crontab -e. A laptop asleep at that time runs it when it wakes if you use launchd or Task Scheduler instead; GitHub Actions works for the API route.

  4. Send it to your board

    Connect Briefkin once with curl -fsSL https://briefkin.dev/install | sh and every run lands on your board as a stat tile. How setup works

View the SKILL.mdRaw file
SKILL.md---
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

What your agent needs

  • 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.

Connecting Mixpanel

  1. Mixpanel MCP server, Mixpanel's official remote server at https://mcp.mixpanel.com/mcp (https://mcp-eu.mixpanel.com/mcp for EU, https://mcp-in.mixpanel.com/mcp for India). Mixpanel is in Claude's connector directory for US projects; for EU or India, add the regional URL as a custom connector. Its Run-Query tool runs insights, funnels, flows and retention queries (docs).
  2. Query API with a service account. Create a service account in your organization settings, store MIXPANEL_SERVICE_ACCOUNT_USERNAME, MIXPANEL_SERVICE_ACCOUNT_SECRET and MIXPANEL_PROJECT_ID, and call the Query API with basic auth.

Give the service account access to only the project the report covers, with the Consumer or Analyst role rather than Admin.

Questions

Why is week 4 blank for the newest cohorts?

A cohort that signed up three weeks ago has not had a week 4 yet. The skill leaves the cell empty rather than reporting zero, which would look as if everyone churned.

Will it run into Mixpanel's rate limits?

No. The Query API allows 60 queries an hour and 5 at a time per project, and this skill makes one or two calls a week.

Do I need Briefkin to use the Mixpanel weekly retention skill?

No. The skill runs with your own agent and gives you the report in the chat. With a Briefkin token set, each run also posts it to your board as a stat tile, so you can glance at it instead of asking again.

Which agents can run it?

Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot CLI, OpenCode, Windsurf and Amp all read SKILL.md files. The install command puts it in ~/.claude/skills and ~/.agents/skills, where they look. ChatGPT, the Claude app and Grok take the prompt instead. Pick your agent under "Install and run it" and the commands change to match.

Can it work without an API or MCP server, from my browser?

Yes. Switch the data source to "Your browser" and the steps change to the Mixpanel pages themselves: the agent opens mixpanel.com/report in a browser you are signed in to and reads the numbers off the page. Claude Code, Codex, Cursor, Claude app and ChatGPT can drive a browser out of the box; Gemini CLI, Copilot CLI and OpenCode need a Playwright or Chrome DevTools MCP server first. It is slower than the API and needs you signed in, so it suits a report you run by hand or from a scheduler on your own computer.

Watch week 1 retention on your board, run after run

Skills are free to use with any agent. Briefkin is where their results land: one board for every report, number and question your agents send, with a ping when something needs you.

Free during the open beta. No card.