upstack query-cohort

Run a cohort analysis from the command line. Wraps POST /api/query-cohort-analysis.

Run a cohort analysis — cohort an audience by acquisition period and analyze retention or LTV over time. Wraps POST /api/query-cohort-analysis — see the API reference.

Usage

upstack query-cohort \
  --measures orders.ltv_cohort_gross_revenue \
  --granularity week \
  --date-start 2026-01-01 \
  --date-end 2026-04-30

Required flags

Flag	Description
--measures <m1,m2,...>	One or more cohort-specific measure ids.
--granularity <g>	week, month, or year.
--date-start <YYYY-MM-DD> --date-end <YYYY-MM-DD>	Date range.

Cohort-only measures

This endpoint only accepts these measure ids:

Measure id	What it computes
orders.ltv_cohort_gross_revenue	Cohorted gross revenue over time.
orders.ltv_cohort_net_revenue	Cohorted net revenue (after refunds).
orders.customers_cohort	Customer count per cohort.
orders.avg_order_value_cohort	Cohort AOV.
orders.cohort_retention_percent	Retention rate per cohort.
orders.cohort_cm1 / cm2	Cohort contribution margins.

Optional flags

Flag	Description	Default
--filter <json>	Canonical Filter as JSON. orders.* fields apply in this context.
--timezone <tz>	IANA timezone.	UTC

See upstack query for the shared output / interactive / from-file flags.

Examples

# Weekly LTV cohort
upstack query-cohort \
  --measures orders.ltv_cohort_gross_revenue,orders.cohort_retention_percent \
  --granularity week \
  --date-start 2026-01-01 --date-end 2026-04-30

# Interactive
upstack query-cohort -i