Skip to main content
POST
/
db-mgmt
/
api
/
query-cohort-analysis
Run a cohort analysis
curl --request POST \
  --url https://api.upstackdata.com/db-mgmt/api/query-cohort-analysis \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --header 'x-pixel-id: <api-key>' \
  --data '
{
  "pixelId": "<string>",
  "measures": [],
  "dateRange": {
    "start": "2026-04-01",
    "end": "2026-04-30"
  },
  "timezone": "<string>",
  "filters": {
    "and": [
      {
        "value": "<string>"
      }
    ]
  },
  "orderSettings": {
    "countPendingOrders": true,
    "countVoidedOrders": true,
    "exclusionFilters": [
      {}
    ]
  }
}
'
{
  "results": [
    {
      "dimensions": [
        "<string>"
      ],
      "dateRange": {
        "start": "2026-04-01",
        "end": "2026-04-30"
      },
      "compareDateRange": {
        "start": "2026-04-01",
        "end": "2026-04-30"
      },
      "measureDetails": [
        {
          "measure": "<string>",
          "isAverage": true,
          "isPercentage": true,
          "calculatedAverage": true,
          "success": true,
          "primaryAvg": 123,
          "compareAvg": 123,
          "primarySum": 123,
          "compareSum": 123,
          "percentDiff": 123,
          "hasPacing": true
        }
      ],
      "data": {
        "primary": [
          {
            "dt": "<string>",
            "start": "<string>",
            "end": "<string>"
          }
        ],
        "compare": [
          {
            "dt": "<string>",
            "start": "<string>",
            "end": "<string>"
          }
        ]
      }
    }
  ]
}

Authorizations

​
x-api-key
string
header
required

Your Upstack API key. Starts with upstack_.

​
x-pixel-id
string
header
required

The pixel id the request targets.

Body

application/json
​
pixelId
string
required

Must match the x-pixel-id header.

​
granularity
enum<string>
required
Available options:
week,
month,
year
​
measures
enum<string>[]
required

Cohort-specific measure ids. Pass measure ids as strings (this endpoint differs from /api/query, which takes objects with pacing).

Required array length: 1 - 30 elements
Available options:
orders.ltv_cohort_gross_revenue,
orders.ltv_cohort_net_revenue,
orders.customers_cohort,
orders.avg_order_value_cohort,
orders.cohort_retention_percent,
orders.cohort_cm1,
orders.cohort_cm2
​
dateRange
object
required
​
timezone
string
​
filters
object

Canonical filter applied to the cohort. orders.* fields are valid in this context — discover via GET /api/filters.

​
orderSettings
object

Order-level query settings — exclusion filters, pending/voided handling.

Response

Cohort results.

​
results
object[]
required