Queries API

Three analytical query endpoints power the dashboard: segmentation, funnels, and retention. All are POST /api/query/*, require the admin Bearer key, and take an optional projectId in the body (defaulting to the default project). Dates from and to are YYYY-MM-DD strings.

Segmentation

Count occurrences of an event over time, bucketed by unit, optionally split by a breakdown property and filtered.

Request

ts
interface SegmentationQuery {
  event: string;
  from: string;               // YYYY-MM-DD
  to: string;
  unit: "hour" | "day" | "week" | "month";
  type: "total" | "unique";   // total events or unique users
  breakdown?: string;         // property to split series by
  filters?: PropertyFilter[];
  projectId?: number;
}
​
interface PropertyFilter {
  key: string;
  op: "eq" | "neq" | "contains" | "set" | "not_set";
  value?: string;
}

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-06-01",
    "to": "2026-06-30",
    "unit": "day",
    "type": "unique",
    "breakdown": "plan",
    "filters": [{ "key": "path", "op": "contains", "value": "/pricing" }]
  }'

Response

One series per breakdown value (or a single series if no breakdown), aligned to a shared buckets axis.

ts
interface SegmentationResult {
  buckets: string[];
  series: {
    name: string; // breakdown value or event name
    data: { bucket: string; value: number }[];
  }[];
}

Funnel

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

Request

ts
interface FunnelQuery {
  steps: string[];     // ordered event names
  from: string;
  to: string;
  windowDays: number;  // conversion window per user
  projectId?: number;
}

bash
curl -X POST https://cohorly-service.velloalabs.com/api/query/funnel \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "steps": ["Signed Up", "Item Added", "Purchased"],
    "from": "2026-06-01",
    "to": "2026-06-30",
    "windowDays": 7
  }'

Response

An array of step results, one per step in order.

ts
interface FunnelStepResult {
  event: string;
  count: number;                   // unique users reaching this step
  conversionFromPrevious: number;  // 0..1
  conversionFromStart: number;     // 0..1
}

Retention

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

Request

ts
interface RetentionQuery {
  bornEvent: string;
  returnEvent: string;
  from: string;
  to: string;
  unit: "day" | "week";
  buckets: number;       // number of return periods to compute
  projectId?: number;
}

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": "Page Viewed",
    "from": "2026-06-01",
    "to": "2026-06-30",
    "unit": "week",
    "buckets": 6
  }'

Response

An array of cohorts. counts[i] is the number of users from that cohort who returned in period i (0 = the cohort's own period).

ts
interface RetentionCohort {
  cohort: string;    // bucket start date
  size: number;
  counts: number[];  // counts[i] = users returning in bucket i
}