GET /api/agent/cohorts/summary
Returns the four headline acquisition-cohort KPIs — new customers, repeat-order rate, avg revenue/customer, and 90-day retention — each with a delta vs the prior 6-month window, plus the top-3 cohorts by M3 retention and plain-English insights in notesForAgent. No query parameters: window covers the full cohort history (up to 24 acquisition months). Cohorts aggregate by acquisition month, so no per-contact PII is on the wire (redactedItemCount is always 0). For the full acquisition-month × offset grid use /api/agent/cohorts/retention.
Auth
- Required scope:
READ_SUMMARY - Header:
Authorization: Bearer cr_live_<prefix>_<secret>
Responses
200 — Cohort KPI summary
Body: CohortSummaryResponse
| Field | Type | Required | Notes |
|---|---|---|---|
asOfDate | string (date) | yes | |
currency | string | yes | |
window | object | yes | Span of the loaded cohort history. from is the earliest acquisition month, to is the latest. Both are YYYY-MM month strings (not full dates). Empty string when the org has no cohorts yet. |
kpis | object | yes | The four headline cohort KPIs. Each is a {value, delta, deltaKind} tuple; delta is the period-over-period change and is null when there is no prior base to compare against. |
topCohorts | array of CohortTopEntry | yes | Up to three cohorts ranked by M3 (90-day) retention. |
redactedItemCount | integer | yes | Always 0 — cohorts aggregate by acquisition month, so no per-contact name is ever masked. Present for envelope parity with the other summary endpoints. |
notesForAgent | array of AgentNote | yes |
401 — Unauthorized
Body: ErrorResponse
| Field | Type | Required | Notes |
|---|---|---|---|
error | string | yes |
403 — Key lacks the required scope
Body: ErrorResponse
| Field | Type | Required | Notes |
|---|---|---|---|
error | string | yes |
429 — Rate-limited or quota-exhausted
Body: ErrorResponse
| Field | Type | Required | Notes |
|---|---|---|---|
error | string | yes |
Response headers
Every successful response carries X-CashRunway-Subscription, X-CashRunway-Plan, X-CashRunway-Quota-Remaining, and X-CashRunway-Quota-Reset. Trialing subscriptions also include X-CashRunway-Trial-Days-Remaining. See the overview for details.