Skip to main content
GET
Get cohort analytics data

Authorizations

Authorization
string
header
required

Bearer authentication using the project Secret Key (prefixed with sk_, or test_sk_ for sandbox). All v4 public endpoints require the Secret Key — see Authentication. Never expose the Secret Key in client-side code.

Query Parameters

cohort_from
integer<int64>

Cohort-range start (Unix timestamp, seconds). Defaults to now - 90 days.

cohort_to
integer<int64>

Cohort-range end (Unix timestamp, seconds). Defaults to the current time. Normalised to the next day's 00:00 UTC on the server.

mode
enum<string>
default:by_renewals
  • by_renewals — columns are subscription renewal indexes (P1, P2, …).
  • by_days — columns are calendar offsets from the cohort start.
Available options:
by_renewals,
by_days
grouping
enum<string>
default:week

Column (period) granularity.

Available options:
day,
week,
month,
quarter,
year
environment
enum<integer>
default:1

Environment: 0 = sandbox, 1 = production.

Available options:
0,
1
cohort_definition
enum<string>
default:new_customers

What event defines cohort membership.

  • new_customers — first app install / user creation.
  • initial_conversions — first trial or paid conversion.
  • new_paying — first paid transaction.
Available options:
new_customers,
initial_conversions,
new_paying
revenue_type
enum<string>
default:gross
  • gross — raw transaction values.
  • net — after refunds and store commission.
Available options:
gross,
net
currency
string
default:USD

ISO 4217 currency code for monetary cells. Non-USD values are converted at the transaction's historical rate.

Pattern: ^[A-Z]{3}$
group_by
string

Optional segmentation attribute — when set, response includes a segments array, one entry per attribute value. Allowed values match filter_conditions[].attribute from cohorts/meta.

filter[<attribute>][]
string[]

Same attribute-scoped filter schema as the charts endpoint.

Response

Cohort table.

object
enum<string>
required
Available options:
analytics_cohorts
url
string
required
mode
enum<string>
required
Available options:
by_renewals,
by_days
grouping
enum<string>
required
Available options:
day,
week,
month,
quarter,
year
cohort_from
integer<int64>
required
cohort_to
integer<int64>
required
currency
string
required
period_labels
string[]
required

Column labels — P1, P2, … for by_renewals, date strings for by_days.

cohorts
object[]
required

One row per cohort window. Empty when the project has no qualifying cohorts in the range.

max_values
object
required

Maximum per-metric value across the table — used for heatmap coloring in the UI.

total
object | null

Aggregated totals row. Null when the table is empty.

group_by
string

Present only when group_by was supplied on the request.

segments
object[]

Present only when group_by was supplied. One entry per segmentation value.