Cohort analysis

GET

/api/v1/ml/cohorts

• Production
• Local development

Return cohort analysis results for a segmentation dimension.

Cohorts span the entire customer base (no tenant filter), so this is admin/owner only — the same operator-analytics gate as the per-tenant and bulk score endpoints.

Authorizations

• ApiKeyAuth

Parameters

Query Parameters

cohort_type

string

default: signup_week /^(signup_week|plan_tier|industry|company_size|acquisition_channel)$/

period

string

default: month /^(week|month)$/

Responses

200

Successful Response

Array<object>

Complete cohort analysis output.

Attributes: cohort_type: Type of cohort (signup_week, plan_tier, industry). cohort_label: Specific cohort identifier. retention_curve: Retention data points over time. revenue_per_period: Revenue generated per period. feature_adoption: Feature name to adoption rate mapping.

object

cohort_label

required

string

cohort_type

required

string

feature_adoption

required

object

key

additional properties

number

retention_curve

required

Array<object>

A single row in a cohort retention curve.

Attributes: cohort_label: Identifier for this cohort (e.g. “2026-W01”). periods_since_start: Number of periods since cohort start, >= 0. cohort_size: Total members in the cohort at start. active_count: Members still active at this period. retention_rate: Fraction of cohort still active, 0.0 to 1.0.

object

active_count

required

integer

cohort_label

required

string

cohort_size

required

integer

periods_since_start

required

integer

retention_rate

required

number

<= 1

revenue_per_period

required

Array<number>

422

Validation Error

object

detail

Array<object>

object

ctx

object

input

loc

required

Array

msg

required

string

type

required

string