> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upstackdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/api-reference/overview).

## Usage

```bash theme={null}
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](/cli/query#filters) as JSON. `orders.*` fields apply in this context. |         |
| `--timezone <tz>` | IANA timezone.                                                                           | `UTC`   |

See [`upstack query`](/cli/query#shared-flags) for the shared output / interactive / from-file flags.

## Examples

```bash theme={null}
# 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
```