​

Cohorts API

The Cohorts API manages cohort definitions. GET lists existing definitions with optional type filtering; POST auto-generates cohorts by grouping accounts into vintage, segment, territory, and rep cohorts.

​

GET /api/cohorts/definitions

Returns cohort definitions for the organization, optionally filtered by cohort type. Auth: Requires authenticated session. Scoped to organization.

​

Query Parameters

​

Response

​

Response Fields: definitions[]

---

​

POST /api/cohorts/definitions

Auto-generates cohort definitions from the organization’s account data. Creates four cohort types:

1. Vintage cohorts — grouped by created_at quarter
2. Segment cohorts — grouped by segment (Enterprise, Mid-Market, SMB)
3. Territory cohorts — grouped by territory
4. Rep cohorts — grouped by owner_id

Auth: Requires authenticated session. Scoped to organization.

​

Request Body

No body required.

​

Response

​

Response Fields: breakdown

​

Side Effects

• Inserts new cohort definitions or updates existing ones (matched by org_id + cohort_type + grouping_field + grouping_value)
• Updates member_count on existing definitions to reflect current account data

​

Computation Flow

1. Load all accounts for the organization
2. Group by quarter (vintage), segment, territory, and owner (rep)
3. For each group, check if a matching definition already exists
4. Insert new definitions or update member counts on existing ones

See the Cohort Intelligence data model page for full details on cohort snapshots, vintage curves, and anomaly detection.