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
1Query the retention endpoint
GET https://mixpanel.com/api/query/retentionwithproject_id,from_date12 weeks ago,to_datelast Sunday,retention_type=birth,born_event=Sign Upandunit=week, with noeventso any event counts as a return. Authenticate as a service account with HTTP basic auth.- 2
2Read the cohorts
The response is keyed by cohort start date, each with
first(the cohort size) andcounts(users returning in each later week). Week 1 retention iscounts[1] / first; week 4 iscounts[4] / first. - 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
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
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.
Post it to the board
With
BRIEFKIN_TOKENset, 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.
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.
shell
curl -fsSL https://briefkin.dev/skills/mixpanel-weekly-retention/install | shRun it
Ask Claude Code:
prompt
Run the mixpanel-weekly-retention skillOr paste the prompt instead of installing:
prompt
Using 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.Put it on a schedule
Mondays at 10:00, from cron on any machine where Claude Code is signed in:
crontab
0 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.Send it to your board
Connect Briefkin once with
curl -fsSL https://briefkin.dev/install | shand 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_USERNAMEandMIXPANEL_SA_SECRET) and the project ID. EU-resident projects useeu.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
- Mixpanel MCP server, Mixpanel's official remote server at
https://mcp.mixpanel.com/mcp(https://mcp-eu.mixpanel.com/mcpfor EU,https://mcp-in.mixpanel.com/mcpfor India). Mixpanel is in Claude's connector directory for US projects; for EU or India, add the regional URL as a custom connector. ItsRun-Querytool runs insights, funnels, flows and retention queries (docs). - Query API with a service account. Create a service account in your organization settings, store
MIXPANEL_SERVICE_ACCOUNT_USERNAME,MIXPANEL_SERVICE_ACCOUNT_SECRETandMIXPANEL_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.