> ## 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/introduction).

## 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` |
| `--currency <code>` | ISO 4217 code to convert cohort money values to. See [Reporting currency](/concepts/reporting-currency). | `USD` |

See [`upstack query`](/cli/query#shared-flags) for the shared output / interactive / from-file flags. Cohort results are always returned as JSON — other `--output` values print a warning and fall back to `json`.

## 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
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.