QuerySpec & the query API

Every chart, widget, saved query, alert, AI answer and MCP tool is a QuerySpec run by POST /api/query. The AI plans specs; the engine validates and runs them. Learning this one shape is learning the whole product’s query surface.

The shape

type Filter = { property: string; op: "eq"|"neq"|"contains"|"not_contains"|"starts_with"|"in"|"not_in"
                                   |"gt"|"gte"|"lt"|"lte"|"is_set"|"is_not_set"|"regex"; value?: any };
type Series = { event: string;            // an event name, "$pageview", or "$any"
                math?: "count"|"users"|"sessions"|"sum"|"avg"|"min"|"max"|"p50"|"p75"|"p90"|"p95"|"p99";
                property?: string; filters?: Filter[]; label?: string };
type QuerySpec = {
  kind: "trends" | "metric" | "table" | "funnel" | "retention" | "paths" | "web";
  project_id?: string | null; segment_id?: string | null;
  range?: "24h"|"7d"|"30d"|"90d"|"12m"; from?: string; to?: string;
  interval?: "hour"|"day"|"week"|"month";
  series?: Series[]; filters?: Filter[]; breakdown?: string | null; limit?: number; compare?: boolean;
  steps?: { event: string; filters?: Filter[]; label?: string }[];     // funnel: 2–10 ordered steps
  window?: "1h"|"1d"|"7d"|"30d";                                      // funnel conversion window
  retention?: { start_event: string; return_event: string; period: "day"|"week"|"month"; periods: number };
  paths?: { start?: string; depth?: number };
  web?: "visitors"|"sessions"|"pageviews"|"bounce_rate"|"top_pages"|"referrers"|"countries"|"devices"|"vitals"|…;
};

Properties

A property is an event column (name, type, path, host, url, title, referrer_host, utm_source, utm_medium, utm_campaign, browser, os, device_type, country, region, city, lang, session_id, user_id, el_text, el_selector, el_tag, duration_ms, value, vital, error_message, plus platform, app_version, device_model from apps), a custom property props.<key> (dots for nesting), or a person trait user.<trait> from identify.

Examples

{"kind": "trends", "project_id": "…", "range": "30d", "interval": "day",
 "series": [{"event": "$pageview", "math": "users"}], "breakdown": "utm_source", "limit": 5}

{"kind": "funnel", "project_id": "…", "range": "30d", "window": "1d",
 "steps": [{"event": "$pageview", "filters": [{"property": "path", "op": "eq", "value": "/cart"}]},
           {"event": "$pageview", "filters": [{"property": "path", "op": "eq", "value": "/checkout"}]},
           {"event": "Order completed"}]}

{"kind": "table", "project_id": "…", "range": "7d",
 "series": [{"event": "Module viewed", "math": "users"}], "breakdown": "user.team", "limit": 10}

{"kind": "metric", "project_id": "…", "range": "7d", "compare": true,
 "series": [{"event": "Order completed", "math": "sum", "property": "value"}], "segment_id": "…"}

Results

Each kind has its own result: trends (labels and series), metric (value, previous, change), table (columns and rows), funnel (per step: count, conversion, step conversion, drop-off, median time), retention (cohorts) and paths (nodes and links). Every result carries the normalised spec actually run and sql_ms. Every rate, share, conversion and change is a fraction.

Calling it

curl -s https://clickiq.example.com/api/query \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"kind":"metric","project_id":"…","range":"7d","compare":true,"series":[{"event":"$pageview","math":"users"}]}' 

Other endpoints you will use