Explore queries

curl -X POST "https://mythic-analytics.gulp.workers.dev/client/v1/data/query?location_id=LOC" \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "trend",
    "date_range": { "preset": "30d" },
    "interval": "day",
    "series": [{ "event": "$pageview", "math": "dau" }],
    "breakdown": { "property": "utm_source", "limit": 5 },
    "compare": "previous_period",
    "filters": [{ "property": "$device_type", "op": "eq", "value": "mobile" }]
  }'

{
  "success": true,
  "data": {
    "kind": "trend",
    "buckets": ["2026-08-02", "2026-08-03", "…", "2026-09-01"],
    "previous_buckets": ["2026-07-02", "…", "2026-08-01"],
    "breakdown_values": ["google", "", "adwords", "homepage", "incubator", "$$other"],
    "series": [
      {
        "label": "$pageview · dau",
        "math": "dau",
        "event": "$pageview",
        "breakdown_value": "google",
        "data": [18, 22, 0, 31],
        "total": 71,
        "previous": [15, 19, 12, 27]
      }
    ],
    "meta": {
      "from": "2026-08-02",
      "to": "2026-09-01",
      "to_exclusive": "2026-09-01 17:55:00",
      "interval": "day",
      "previous": { "from": "2026-07-02", "to": "2026-08-01", "to_exclusive": "2026-08-01 17:55:00" },
      "sql_ms": 212,
      "rows_read": 778534,
      "bytes_read": 36060000,
      "cached": false
    }
  }
}

{
  "kind": "funnel",
  "date_range": { "preset": "14d" },
  "steps": [
    { "event": "$pageview", "filters": [{ "property": "$pathname", "op": "contains", "value": "/pricing" }] },
    { "event": "signup" },
    { "event": "order_completed" }
  ],
  "window": { "value": 3, "unit": "day" },
  "breakdown": { "property": "$experiment_arm" }
}

{
  "success": true,
  "data": {
    "kind": "funnel",
    "steps": [
      { "step": 1, "label": "$pageview", "event": "$pageview", "users": 1180, "conversion_from_first": 1, "conversion_from_previous": 1 },
      { "step": 2, "label": "signup", "event": "signup", "users": 143, "conversion_from_first": 0.1212, "conversion_from_previous": 0.1212 },
      { "step": 3, "label": "order_completed", "event": "order_completed", "users": 31, "conversion_from_first": 0.0263, "conversion_from_previous": 0.2168 }
    ],
    "breakdown": [
      { "value": "B", "steps": [ { "step": 1, "users": 602, "…": "…" } ] },
      { "value": "A", "steps": [ { "step": 1, "users": 578, "…": "…" } ] }
    ],
    "meta": { "from": "2026-08-18", "to": "2026-09-01", "window_seconds": 259200, "grain": "device", "sql_ms": 340, "rows_read": 51200, "bytes_read": 2100000, "cached": false }
  }
}

What it is

POST /client/v1/data/query is the self-serve half of the Data API. The fixed reports (/events/summary, /events/breakdown, /sessions/breakdown) answer the questions we anticipated. This route answers the ones you compose: any event, any property, filters, several series, a breakdown, a previous-period compare, or an ordered funnel with a conversion window.

You send a spec, not SQL. The spec is validated (unknown keys are rejected), compiled on the server to ClickHouse SQL over a wide, typed events table, and scoped to your location by the compiler itself. There is no field in the spec that can name a tenant, a table, or raw SQL.

A first trend

One series[] entry per spec series × breakdown value. data[] is aligned to buckets[] and zero-filled; previous[] is aligned by index to previous_buckets[]. Omit interval and each entry carries a single value (and previous_value) instead.

The spec

Filters

{ "property": "...", "op": "...", "value": ... }

Properties

Typed names resolve to indexed columns. Anything else is looked up as a custom event property.

Discover keys with GET /properties and values with GET /query/values.

A funnel

Step k counts users who reached steps 1 through k in order within the window. By default users are distinct_ids, so an anonymous visitor who identifies between two steps is two ids and the funnel breaks there. Add "grain": "person" to resolve ids to people first and keep the journey whole — meta.grain echoes what was counted.

That matters most when a step is not a browser event. A CRM or server-side conversion arrives under a contact id, never the visitor's distinct_id, so at device grain the funnel structurally cannot link it: on a live web+CRM tenant a $pageview → opportunity_created funnel found 637 conversions by device and 914 by person, a rate of 3.4% against 5.2%. On a web-only funnel the two agree to within 0.1%, and person grain only costs you time.

Semantics worth knowing

• Unique counts are approximate. dau and unique_sessions use ClickHouse uniq(), accurate to about 1–2%.
• Buckets are UTC and every bucket in the range is present, zero where nothing happened.
• Compare aligns by index. previous[i] is the bucket i of the previous window, so week-over-week lines overlay directly.
• $$other is a real value in breakdown_values and series[], never a separate field.
• Caching. A range that ends before today is served from cache for six hours; one touching today for two minutes. meta.cached tells you which.
• Rate limit. 30 requests per 10 seconds per location, separate from the rest of the Data API.

Errors

Property values

GET /query/values?property=utm_source&days=30&limit=20 returns { success, data: { property, days, values: [{ value, count }], cached } } — the picker behind filter and breakdown inputs. Accepts the same property names as /query, an optional event to narrow, and a case-insensitive search.

Saving one as an insight

An insight is exactly this spec stored as config.query through the Builder API (POST /builder/insights) plus an insight_type that picks the visualization; run it with POST /builder/insights/:id/query. It is validated at write time, executes on this engine, and returns this response shape. See Insight config.

From MCP

The query_events and list_property_values tools are thin proxies over these two routes with the same spec as their input schema.