Documentation Index
Fetch the complete documentation index at: https://hc.pillargtm.com/llms.txt
Use this file to discover all available pages before exploring further.
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
| Parameter | Type | Default | Description |
|---|
cohort_type | string | — | Filter by type: vintage, segment, territory, rep, custom |
Response
| Field | Type | Description |
|---|
definitions | array | Cohort definition records |
count | number | Total definitions returned |
Response Fields: definitions[]
| Field | Type | Description |
|---|
id | string | Cohort definition ID |
org_id | string | Organization ID |
name | string | Display name (e.g. “Vintage 2025-Q3”) |
cohort_type | string | vintage, segment, territory, rep, custom |
grouping_field | string | Field used for grouping |
grouping_value | string | Value of the grouping field |
filter_criteria | object | Custom filter criteria (nullable) |
member_count | number | Number of accounts in the cohort |
POST /api/cohorts/definitions
Auto-generates cohort definitions from the organization’s account data. Creates four cohort types:
- Vintage cohorts — grouped by
created_at quarter
- Segment cohorts — grouped by
segment (Enterprise, Mid-Market, SMB)
- Territory cohorts — grouped by
territory
- Rep cohorts — grouped by
owner_id
Auth: Requires authenticated session. Scoped to organization.
Request Body
No body required.
Response
| Field | Type | Description |
|---|
success | boolean | Operation result |
total_cohorts | number | Total cohorts generated |
inserted | number | New cohort definitions created |
updated | number | Existing definitions updated (member counts refreshed) |
breakdown | object | Per-type counts |
Response Fields: breakdown
| Field | Type | Description |
|---|
vintage | number | Vintage cohorts generated |
segment | number | Segment cohorts generated |
territory | number | Territory cohorts generated |
rep | number | Rep cohorts generated |
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
- Load all accounts for the organization
- Group by quarter (vintage), segment, territory, and owner (rep)
- For each group, check if a matching definition already exists
- 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.
