cohorts.compare
Compare multiple cohorts side-by-side on retention to see which group retains better, such as comparing signup weeks or experiment variants.
Instructions
Compare 2–10 saved cohorts side-by-side on retention. Returns each cohort's size and retention curve over the same period set, so you can read "did this week's signups retain better than last week's?", "is this experiment cohort behaving differently than control?", or stack a few quarters' cohorts to spot a structural retention trend — without composing the rates manually.
Order matters: the first name is treated as the primary; downstream renderings (dashboard, summaries) read deltas relative to it. Duplicates are silently deduplicated.
Examples:
"did April 14 signups retain better than April 7" → names="signups_apr_14,signups_apr_07"
"are pro-plan signups stickier than free" → names="pro_signups_q2,free_signups_q2"
"compare two onboarding variants out to 4 weeks" → names="onboarding_v1,onboarding_v2", periods="1w,2w,4w"
"three-arm experiment retention" → names="control,variant_a,variant_b"
"is signup retention improving quarter-over-quarter" → names="signups_q1,signups_q2,signups_q3,signups_q4"
Limitations: at most 10 cohorts per call. The same retention windows are applied to every cohort — there's no way to use different windows per slot. Sample-size caveats apply per cohort; check each size value before reading rate deltas (small cohorts make differences look meaningful when they aren't). Stacking many cohorts increases the multiple-comparisons risk — a divergent-looking row in a 5-way compare may just be random variation; commit to a hypothesis before reading.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | No | Target project ID (e.g. "proj_abc123"). Required when the credential has access to multiple projects. If omitted and only one project is accessible, that project is used automatically. Call `projects.list` to discover available project IDs. | |
| names | Yes | Comma-separated cohort names, 2–10 entries. First name is treated as the primary. Example: "signups_apr_14,signups_apr_07" or "control,variant_a,variant_b". | |
| periods | No | Comma-separated retention windows, same format as cohorts.retention. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cohorts | Yes |