Queries API

Five analytical query endpoints power the dashboard: segmentation, funnel, retention, flows, and sessions. All are POST /api/query/*, require the admin Bearer key (Authorization: Bearer $API_KEY - superadmin key or a Firebase ID token), and take an optional projectId in the body (defaulting to the caller's oldest project). Dates from and to are YYYY-MM-DD strings.

These are the stable v0 wrapper endpoints every dashboard screen already speaks. POST /api/query runs trend and funnel analyses through the newer Query IR pipeline instead and is the forward path, but is not yet documented here - it takes a free-form IR document rather than a fixed shape, so it does not fit a parameter table the way these five do. All five below are subject to the /api/query/* analytics rate limit (default 30 requests / 60s per authenticated user, or per source IP for the superadmin key).

Segmentation

POST/api/query/segmentation

Copy path

Time-bucketed event trend, optionally split by a property and filtered.

Name	Type	Required	Default	Description
`event`	string	Required	-	Event name, or the $all_events sentinel to match every event.
`from`	string (date)	Required	-	YYYY-MM-DD, inclusive.
`to`	string (date)	Required	-	YYYY-MM-DD, inclusive.
`unit`	"hour" \| "day" \| "week" \| "month"	Required	-	Bucket size.
`type`	"total" \| "unique"	Required	-	Count every occurrence, or count distinct users.
`breakdown`	string	Optional	-	Property key to split the series by; one series per observed value.
`filters`	PropertyFilter[]	Optional	-	Up to 20 property filters, ANDed together.
`filters[].key`	string	Required	-	Property key to filter on.
`filters[].op`	"eq" \| "neq" \| "contains" \| "set" \| "not_set"	Required	-	Comparison operator.
`filters[].value`	string	Optional	-	Required for eq/neq/contains; omitted for set/not_set.
`projectId`	string	Optional	-	Defaults to the caller's oldest project.

bash
curl -X POST https://cohorly-service.velloalabs.com/api/query/segmentation \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "Page Viewed",
    "from": "2026-07-01",
    "to": "2026-07-31",
    "unit": "day",
    "type": "unique",
    "breakdown": "plan",
    "filters": [{ "key": "path", "op": "contains", "value": "/pricing" }]
  }'

json
{
  "buckets": ["2026-07-01", "2026-07-02"],
  "series": [
    {
      "name": "Signed Up",
      "data": [
        { "bucket": "2026-07-01", "value": 12 },
        { "bucket": "2026-07-02", "value": 18 }
      ]
    }
  ]
}

Funnel

POST/api/query/funnel

Copy path

Measure how many users complete an ordered sequence of steps within a conversion window.

Name	Type	Required	Default	Description
`steps`	string[]	Required	-	2 to 10 ordered event names.
`from`	string (date)	Required	-	YYYY-MM-DD, inclusive.
`to`	string (date)	Required	-	YYYY-MM-DD, inclusive.
`windowDays`	integer	Optional	`30`	Max elapsed days from step 0 for a user to still count as converting at a later step (1-366).
`breakdown`	string	Optional	-	Property key to split each step's segments by.
`filters`	PropertyFilter[]	Optional	-	Up to 20 property filters, ANDed together (same shape as segmentation).
`projectId`	string	Optional	-	Defaults to the caller's oldest project.

bash
curl -X POST https://cohorly-service.velloalabs.com/api/query/funnel \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "steps": ["Viewed Pricing", "Signed Up", "Upgraded"],
    "from": "2026-07-01",
    "to": "2026-07-31",
    "windowDays": 14
  }'

json
[
  {
    "event": "Signed Up",
    "count": 340,
    "conversionFromPrevious": 0.62,
    "conversionFromStart": 0.62,
    "droppedCount": 208,
    "dropoffRate": 0.38,
    "convertedUserIds": ["user-42"],
    "droppedUserIds": ["user-7"],
    "segments": [],
    "meanSecondsToConvert": 145.2,
    "medianSecondsToConvert": 98
  }
]

Retention

POST/api/query/retention

Copy path

Track how many users who performed a bornEvent came back to perform a returnEvent in later periods.

Name	Type	Required	Default	Description
`bornEvent`	string	Required	-	Event name, or the $all_events sentinel.
`returnEvent`	string	Required	-	Event name, or the $all_events sentinel.
`from`	string (date)	Required	-	YYYY-MM-DD, inclusive.
`to`	string (date)	Required	-	YYYY-MM-DD, inclusive.
`unit`	"day" \| "week"	Optional	`week`	Cohort bucket size.
`buckets`	integer	Optional	`8`	Number of return periods to compute (1-16).
`projectId`	string	Optional	-	Defaults to the caller's oldest project.

bash
curl -X POST https://cohorly-service.velloalabs.com/api/query/retention \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bornEvent": "Signed Up",
    "returnEvent": "$all_events",
    "from": "2026-05-01",
    "to": "2026-07-31",
    "unit": "week",
    "buckets": 8
  }'

json
[{ "cohort": "2026-07-06", "size": 120, "counts": [120, 54, 40, 31] }]

Flows

POST/api/query/flows

Copy path

Top user paths before or after an anchor event.

Name	Type	Required	Default	Description
`event`	string	Required	-	Anchor event name - a concrete name, not the $all_events sentinel.
`direction`	"after" \| "before"	Required	-	Walk the path forward or backward from the anchor.
`steps`	integer	Optional	`3`	Path length to walk from the anchor (1-5).
`from`	string (date)	Required	-	YYYY-MM-DD, inclusive.
`to`	string (date)	Required	-	YYYY-MM-DD, inclusive.
`limit`	integer	Optional	`20`	Max number of distinct paths to return (1-100).
`projectId`	string	Optional	-	Defaults to the caller's oldest project.

bash
curl -X POST https://cohorly-service.velloalabs.com/api/query/flows \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "Signed Up",
    "direction": "after",
    "steps": 3,
    "from": "2026-07-01",
    "to": "2026-07-31",
    "limit": 20
  }'

json
{
  "paths": [{ "path": ["Signed Up", "Viewed Dashboard", "Upgraded"], "count": 88 }],
  "total": 340
}

Sessions

POST/api/query/sessions

Copy path

Session counts and average duration over time.

Sessions are computed at query time (30 minute inactivity timeout by default, COHORLY_SESSION_TIMEOUT_MS) and bucketed the same way as segmentation.

Name	Type	Required	Default	Description
`from`	string (date)	Required	-	YYYY-MM-DD, inclusive.
`to`	string (date)	Required	-	YYYY-MM-DD, inclusive.
`unit`	"hour" \| "day" \| "week" \| "month"	Optional	-	Bucket size.
`projectId`	string	Optional	-	Defaults to the caller's oldest project.

bash
curl -X POST https://cohorly-service.velloalabs.com/api/query/sessions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "from": "2026-07-01", "to": "2026-07-31", "unit": "day" }'

json
{ "series": [{ "bucket": "2026-07-01", "sessions": 40, "avgDurationSec": 212.5 }] }