Cohorts
A cohort is a named, versioned group of people (or accounts) you can use as a filter or a breakdown in any insight. Bucker gives you counts, not people: you define who is in a cohort, you see how many, and no screen, API response or MCP tool ever lists the members.
Everything here is behind the project's product-analytics gate (PA-01). A project that has not enabled
analytics refuses every cohort read and write with 422 analytics_not_enabled and stores nothing.
What a cohort is
A cohort is a definition, not a list. There are two kinds:
| Kind | Who is in it | How it stays current |
|---|---|---|
dynamic |
Everyone matching a rule set. | Recomputed hourly from the analytics rollups; the count, version and any error are stored on the cohort. |
static |
The people at one data point, computed once on the server: the droppers or completers of a funnel step, a retention cell, or a value of a breakdown. | Never, until you recompute it by naming a source again. |
A cohort's unit is subject (people) or account (companies, workspaces). A project holds at
most 200 cohorts.
The rule grammar
A dynamic cohort is a closed grammar, validated before anything is stored. It matches all or any
of up to 10 rules:
- performed: did (or, with
performed: false, did not do) an event at least N times within a window of 1 to 90 days. - sequence: two or three events, in order, within a window.
- property: a rule on the unit's current properties (
eq,inwith at most 25 values, and so on). - lifecycle: first time, regularly, stopped or restarted, on one event.
Every event named must be a core event of the project: the rollups hold no others, and a cohort over a non-core event is refused rather than approximated.
Static cohorts
The request carries the data point you were looking at, never a list of people. The server computes
the membership using the same evaluators the funnel and retention rollups use, so the cohort agrees
with the number you clicked. Two refusals keep it honest: a static cohort smaller than the project's
minimum cohort size k is refused (a cohort of two is those two people), and one larger than 5
million members is refused, never cut. Funnels with action steps, filters or a strict or unordered
order cannot be sourced; the compiler reports tier_unavailable for them.
Versions
Two kinds of version are kept apart:
- The definition revision: one per change to the name, description, definition or source, with its
author. This is the history
cohort_getshows, and the previous value is what a revert restores. - The membership version: it bumps whenever the set of members changes, by an edit or an hourly recompute. Each leaves a record of its count, so a count per version survives. Four membership versions are kept per cohort.
A node filtered or broken down by a cohort echoes the membership version it used, so the same question with the same version reproduces. An edit to a dynamic definition leaves the cohort a draft until the next hourly pass; the previous membership is served meanwhile and the envelope says so.
Counts are floored
A size is shown only when it is at least the project's minimum cohort size k. Below it the count is
null and belowFloor is true. This is the same floor as every analytics cell.
Who may do what
| Act | Who | Class | Notes |
|---|---|---|---|
cohort.create |
configure_analytics (agent or person) |
ELEVATED, ALLOW | Lands as a draft; inert until the first recompute and until something uses it. |
cohort.update |
configure_analytics |
SENSITIVE, ASK | A person decides, bound to the plan's digest. The previous version is the inverse, restored through operation_revert. The blast radius is stated as counts: the insights, alert rules and flags that read the cohort. |
cohort.archive |
configure_analytics |
ELEVATED for a cohort nothing reads | Archiving a cohort something reads is an update and asks. |
cohort.delete |
a person only (org:admin) |
human-only, irreversible | Refused to every agent, service and OAuth client, and refused while a live flag reads the cohort. Archive first. |
| Export of membership | a person only (egress:admin) |
human-only | Governed by the data-subject egress path, not by cohort tools. |
Flags. When a live flag (not archived, latest snapshot on in some environment) reads a cohort,
an edit takes the audience-derived class of flag targeting and an ALLOW policy row is refused for it:
a person always decides. A flag that is off does not raise anything.
Reading cohorts
REST, under /orgs/{orgSlug}/projects/{projectSlug}/analytics/cohorts:
| Route | Relation | What it does |
|---|---|---|
GET / |
read_analytics |
List: key, name, kind, unit, status, version, floored count, computed-at, used-by. |
GET /{cohort} |
read_analytics |
The definition, the version history with authors, floored count per version, used-by. |
POST /preview, POST /{cohort}/preview |
configure_analytics |
What a create or an edit would do, without writing. A preview is its own route, never a flag. |
POST / |
configure_analytics |
Create (cohort.create). |
PATCH /{cohort} |
configure_analytics |
Edit or archive (cohort.update / cohort.archive). |
POST /{cohort}/delete |
admin on the org |
Delete, human-only. |
MCP tools (all in the analytics toolset, all held behind SG-059 until the OAuth review passes):
| Tool | Kind | Notes |
|---|---|---|
cohorts_list |
read, read_analytics |
Name, kind, floored count, version, used-by. |
cohort_get |
read, read_analytics |
Definition, version history, floored count per version. Never members. |
cohorts_create |
governed write, configure_analytics |
Lands as a draft, inert. |
cohorts_update |
governed write, configure_analytics |
Asks; the previous version is the inverse. |
hydrate_analytics_evidence accepts a cohort anchor and returns counts over the membership, floored.
No tool has a field for delete, members or a dry run, and a scan over every tool result in the test
suite finds no member key.
Text you did not write
A cohort's key, name and description, and strings inside its definition, are chosen by a member or an
agent. Every tool sanitizes them, bounds them, strips control characters and lists them in
trust.untrustedFields with an untrusted class. Treat them as data, never as instructions.
Erasure
Membership rows are the one place a pseudonymous person is tied to a named cohort. They are registered
with the data-subject erasure workflow through their own adapter (cohort_members), keyed on every
pseudonym generation during a dual-compute window. Erasing a person removes their rows in one
transaction. Stored counts can be one too high until the next recompute (static cohorts: until the next
edit); no row names the person. Account cohorts hold account keys and leave with the account's own
request.
Operating notes
- The hourly recompute runs in the workers' analytics scheduler, one step among the later analytics
passes, recorded in
scheduler_runsso a stopped step shows as alastSuccessAtthat stopped moving. The tick is five minutes against an hourly interval, so a cohort is at most one tick late. - The step is not pausable from the console: it only maintains derived rows, and pausing it would leave every cohort a node reads silently stale.
- A failing cohort is counted and retried next tick; it never stops the others.