Insight config reference

Overview

An insight is a saved explore query or an analysis panel plus a visualization. Its config is a JSON object with exactly one of query or analysis:

{
  "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.
• config.analysis replaces query for a constraint finder, correlation or scanner summary panel. See Analysis panels.
• Any other key in config is stored verbatim as display settings and never read by the runner, except metric on an attribution number (see Ad spend, CPA and ROAS).

Which spec per type

The hard rules: funnel ⇔ kind: "funnel", and attribution only draws as table, bar or number. Every other type carries a kind: "trend" spec. paths cannot be saved. 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.

Ad spend, CPA and ROAS

An attribution spec credits each conversion to the Meta or Google campaign, ad set or ad that brought the visitor, and joins the platform's daily spend. The result has totals (all conversions), filtered and one row per campaign/ad set/ad (and per non-ad channel) with spend, impressions, clicks, conversions, revenue, cpa and roas. cpa is null when no spend was recorded, never 0. See Explore queries for the grammar.

{
  "name": "Cost per lead by ad",
  "insight_type": "table",
  "config": {
    "query": {
      "kind": "attribution",
      "date_range": { "preset": "30d" },
      "goal": { "event": "lead_submitted" },
      "level": "ad"
    }
  }
}

A number shows one total, chosen by config.metric: conversions (default), revenue, spend, roas or cpa. A bar draws the same metric per row.

{ "insight_type": "number", "config": { "metric": "cpa", "query": { "kind": "attribution", "date_range": { "preset": "30d" }, "goal": { "event": "lead_submitted" } } } }

Analysis panels

config.analysis is { "kind", "params" }. The panel runs an existing analysis route as the viewer: their key is sent to the route, so the route's own scope, plan and client checks apply, and the result is cached for 5 minutes per viewer key. Analysis panels therefore do not run on public or embedded dashboards (POST /public/query answers 403).

Parameters are typed (numbers as numbers) and allowlisted: the constraint finder's table and include are not available to panels. POST /insights/{id}/query and run_insight return { "engine": "analysis", "kind", "result" } where result is the route's response body (named result so it is not mistaken for the response envelope's data).

{
  "name": "Where the paid funnel leaks, per ad",
  "insight_type": "table",
  "config": { "analysis": { "kind": "constraints", "params": { "conversion_event": "lead_submitted", "group_by": "ad", "days": 30, "timezone": "America/Los_Angeles" } } }
}

{
  "name": "Sessions with a broken experience",
  "insight_type": "number",
  "config": { "analysis": { "kind": "scanner_summary", "params": { "scanner_id": "921f8759-aafa-4595-ad62-b70d00354b68" } } }
}

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. Trends only.

On an analysis panel, a preset becomes the route's relative window (days, or lookback_days for correlation, which ignores 24h) and a custom range its dates (from/to, or date_from/date_to for a scanner summary).

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.