Insight config reference

Overview

An insight is a saved explore query plus a visualization. Its config is a JSON object with one required key:

{
  "name": "Daily visitors",
  "insight_type": "line",
  "config": {
    "query": {
      "kind": "trend",
      "date_range": { "preset": "30d" },
      "interval": "day",
      "series": [{ "event": "$pageview", "math": "dau", "label": "Visitors" }],
      "compare": "previous_period"
    }
  }
}

• config.query is the same object you would POST /client/v1/data/query. The full grammar — series maths, filters, breakdowns, funnels, limits — lives on the Explore queries page and is not repeated here.
• insight_type is only the visualization. It never changes what is computed.
• Any other key in config is stored verbatim as display settings and never read by the runner.

Which spec per type

The one hard rule: funnel ⇔ kind: "funnel". Every other type must carry a kind: "trend" spec. A trend without interval returns one value per series; with interval it returns data[] per bucket and a total. bar and pie read the totals either way, so leaving interval off is cheaper for those. number renders either way too, but without an interval it has no buckets to draw and shows the scorecards alone.

Examples

number — conversions this week vs last

{
  "insight_type": "number",
  "config": {
    "query": {
      "kind": "trend",
      "date_range": { "preset": "7d" },
      "series": [{ "event": "purchase", "math": "total", "label": "Purchases" }],
      "compare": "previous_period"
    }
  }
}

line — visitors by device

{
  "insight_type": "line",
  "config": {
    "query": {
      "kind": "trend",
      "date_range": { "preset": "30d" },
      "interval": "day",
      "series": [{ "event": "$pageview", "math": "dau" }],
      "breakdown": { "property": "$device_type", "limit": 3 }
    }
  }
}

pie — traffic sources

{
  "insight_type": "pie",
  "config": {
    "query": {
      "kind": "trend",
      "date_range": { "preset": "30d" },
      "series": [{ "event": "$pageview", "math": "unique_sessions" }],
      "breakdown": { "property": "$referring_domain", "limit": 8 }
    }
  }
}

table — top pages

{
  "insight_type": "table",
  "config": {
    "query": {
      "kind": "trend",
      "date_range": { "preset": "7d" },
      "series": [
        { "event": "$pageview", "math": "total", "label": "Views" },
        { "event": "$pageview", "math": "dau", "label": "Visitors" }
      ],
      "breakdown": { "property": "$pathname", "limit": 20 }
    }
  }
}

funnel — checkout

{
  "insight_type": "funnel",
  "config": {
    "query": {
      "kind": "funnel",
      "date_range": { "preset": "30d" },
      "steps": [
        { "event": "$pageview", "filters": [{ "property": "$pathname", "op": "eq", "value": "/pricing" }], "label": "Pricing" },
        { "event": "checkout_started" },
        { "event": "purchase" }
      ],
      "window": { "value": 3, "unit": "day" }
    }
  }
}

Set "grain": "person" on a funnel whose steps cross from the browser into server-side or CRM events — those arrive under a contact id, not the visitor's distinct_id, so the default device grain cannot link them. See Explore queries for the cost.

Discovering events and properties

Don't hardcode names. The Data API answers, with the same key:

• GET /client/v1/data/events/summary — event names with counts for a window.
• GET /client/v1/data/properties?event=<name> — the property catalog (typed keys and how often they occur).
• GET /client/v1/data/query/values?property=<key>&event=<name>&search= — top values of one property, for filter and breakdown pickers.

Validating and previewing

Per-run overrides

POST /insights/{id}/query, POST /public/query and /insights/preview accept two optional overrides that are applied onto the stored spec for that run only:

• dateRange — { "preset": "7d" } (24h, 7d, 14d, 30d, 90d, 365d) or { "preset": "custom", "from": "2026-08-01", "to": "2026-08-31" }. Anything else keeps the stored range.
• granularity — hour, day, week, month; replaces query.interval. Ignored for funnels.

Dashboards use these to apply one date range and interval to every tile.

Reading the results

The run payload is the explore response with the insight attached — see the Queries group for the full schema. In short:

For a number, read each entry's total (with interval) or value for the scorecard, the previous* counterpart for the delta, and buckets against data for the chart beneath them. For a line, plot buckets against each entry's data. For bar/pie, one slice per series[] entry using total/value.

Dashboards: filters and theme

POST /builder/dashboards takes filters and theme objects, both {} by default.