Skip to content
UltimateTeam.ai Docs

Cohort analysis

GET
/api/v1/ml/cohorts
curl --request GET \
  --url 'https://api.ultimateteam.ai/api/v1/ml/cohorts?cohort_type=signup_week&period=month' \
  --header 'X-API-Key: <X-API-Key>'

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

Section titled “Authorizations”

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters”
cohort_type
Cohort Type
string
default: signup_week /^(signup_week|plan_tier|industry|company_size|acquisition_channel)$/
period
Period
string
default: month /^(week|month)$/

Responses

Section titled “ Responses ”

200

Section titled “200”

Successful Response

Media typeapplication/json
Response Get Cohorts Api V1 Ml Cohorts Get
Array<object>
CohortAnalysisResult

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
Cohort Label
string
cohort_type
required
Cohort Type
string
feature_adoption
required
Feature Adoption
object
key
additional properties
number
retention_curve
required
Retention Curve
Array<object>
CohortRetentionRow

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
Active Count
integer
cohort_label
required
Cohort Label
string
cohort_size
required
Cohort Size
integer
periods_since_start
required
Periods Since Start
integer
retention_rate
required
Retention Rate
number
<= 1
revenue_per_period
required
Revenue Per Period
Array<number>
Examplegenerated
[
  {
    "cohort_label": "example",
    "cohort_type": "example",
    "feature_adoption": {
      "additionalProperty": 1
    },
    "retention_curve": [
      {
        "active_count": 1,
        "cohort_label": "example",
        "cohort_size": 1,
        "periods_since_start": 1,
        "retention_rate": 1
      }
    ],
    "revenue_per_period": [
      1
    ]
  }
]

422

Section titled “422”

Validation Error

Media typeapplication/json
HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
ctx
Context
object
input
Input
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
Examplegenerated
{
  "detail": [
    {
      "ctx": {},
      "input": "example",
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example"
    }
  ]
}