Insights API

Run analytics queries programmatically against the same engine that powers dashboard charts, overview KPIs, and saved tiles. The Insights API is a server-side interface - it is not callable from browser clients.

Service: shared.insights.v1.InsightsService
Auth: Dual - private key (prv_...) via x-api-key or dashboard JWT via Authorization: Bearer. See Authentication.

Methods

Query

POST /shared.insights.v1.InsightsService/Query

Runs an analytics query and returns a typed result. The shape of the result depends on spec.insight_type (see Insight types).

Request: QueryRequest

Response: QueryResponse

The response carries exactly one of the following fields, selected by spec.insight_type:

SegmentUsers

POST /shared.insights.v1.InsightsService/SegmentUsers

Returns a paginated list of distinct user IDs that match a set of event conditions within a time range. Useful for audience export or cross-referencing profiles.

Response: { distinct_ids: string[], next_page_token: string }.

GetFilterSchema

POST /shared.insights.v1.InsightsService/GetFilterSchema

Returns the set of known event kinds and property keys (auto, custom, profile) for the project. Use this to populate filter pickers. The response shape is common.v1.GetFilterSchemaResponse. Optionally scoped to a single event kind or filtered to specific PropertyValueType values.

GetPropertyValues

POST /shared.insights.v1.InsightsService/GetPropertyValues

Returns the distinct observed values for a specific property key. Useful for populating FILTER_OPERATOR_IN value lists.

Response: { "values": string[] } - the distinct observed values.

{ "propertyKey": "$country", "source": "PROPERTY_SOURCE_AUTO" }

Insight types

InsightQuerySpec.insight_type selects the computation and the response field.

Insight type constraints

• INSIGHT_TYPE_FUNNEL: requires at least one event; supports breakdowns (max 5); supports conversion_window (whole seconds, min 1 s); supports include_step_timing.
• INSIGHT_TYPE_RETENTION: requires at least one event; accepts at most 2 (events[0] = start, events[1] = return).
• INSIGHT_TYPE_SEGMENTATION: does not support breakdowns.
• INSIGHT_TYPE_USER_FLOW: requires a user_flow sub-spec; events must be empty; breakdowns are not supported.
• INSIGHT_TYPE_TOP_K: requires a top_k sub-spec; events, session, breakdowns and breakdown_limit must all be empty. Scope events through top_k.scope instead.
• INSIGHT_TYPE_MAP: requires a map sub-spec; events, session, breakdowns and breakdown_limit must all be empty. Scope events through map.scope instead. The country dimension is implied, so there is nothing to break down by and no top-N to bound.
• INSIGHT_TYPE_TRENDS / INSIGHT_TYPE_SEGMENTATION: support numeric aggregations (AGGREGATION_TYPE_SUM, AVG, MIN, MAX); these are not valid for funnel or retention.

Granularities

QueryRequest.granularity controls the time-bucket width and imposes a maximum query range.

InsightQuerySpec fields

Cookieless visitors are excluded from user counts

Cookieless IDs rotate daily, so one returning human would count as a new user every day. By default they are excluded from:

• UNIQUE_USERS and PER_USER_AVG, numerator and denominator alike, wherever those metrics appear: trends, segmentation, top K, map.
• Person-based insights: funnel, retention, user flow, and DIMENSION_USER top K. These resolve people rather than events, so they exclude regardless of which metric is selected.

Event totals, numeric aggregations and all session metrics always count every visitor, cookieless or not. Set include_cookieless: true to fold them into the metrics above as well - useful for a relative trend, misleading as an absolute user count.

EventQuery

Aggregation types

TopKQuery

Ranks the top values of one dimension by an aggregate metric. Top K has no time axis - granularity is still required on the request, but for this insight type it only selects which time-range cap applies, so send the coarsest granularity whose cap admits your window.

TopKResult holds rows, ordered metric-descending with the $others bucket last. Each TopKRow carries dimension_value, value, is_others, and, for resolved DIMENSION_USER rows only, a profile (id, external_id, properties).

Identify the overflow bucket by is_others, never by matching dimension_value against "$others" - a real property value or event kind can legitimately be that literal string. The same contract applies to UserFlowNode.

MapQuery

Measures one metric per country for a choropleth. The dimension is fixed to the $country auto-property - there is no dimension or property field to set, and no limit. Like top K it has no time axis, so granularity only selects which time-range cap applies.

Results arrive in QueryResponse.top_k as a TopKResult, ordered metric-descending, with dimension_value set to the country code. There is no $others bucket - every row is a country.

Filter model

Filters are expressed as FilterGroup objects inside spec.filter_groups. Each group contains one or more PropertyFilter entries combined by the group’s own operator. Groups are then combined by spec.filter_groups_operator.

FilterGroup

{
  "filters": [
    { "property": "plan", "operator": "FILTER_OPERATOR_EQUALS", "value": "pro" },
    { "property": "$country", "operator": "FILTER_OPERATOR_IN", "values": ["US", "CA"] }
  ],
  "operator": "LOGICAL_OPERATOR_AND"
}

Filter operators (FilterOperator)

Logical operators (LogicalOperator)

Property names follow the pattern ^\\$?[a-zA-Z0-9_-]+(\\.[a-zA-Z0-9_-]+)*$. Auto-properties use their flat $ key (e.g. $country, $browser); a dotted name addresses a nested key inside a custom property’s JSON (e.g. metadata.tier). For filterable auto-properties see Auto-properties.

Session metrics

When spec.session is set, the query measures session-level data instead of individual events. spec.events must be empty.

SessionQuery.scope (optional EventFilter) restricts which events participate in the metric. An empty scope considers all events in the session.

Worked example: TRENDS query

A daily time series of unique users who fired page_view, broken down by $country, over the last 30 days.

POST /shared.insights.v1.InsightsService/Query
Content-Type: application/json
Connect-Protocol-Version: 1
x-api-key: prv_...

{
  "spec": {
    "insight_type": "INSIGHT_TYPE_TRENDS",
    "events": [
      {
        "event": { "kind": "page_view" },
        "aggregation": "AGGREGATION_TYPE_UNIQUE_USERS"
      }
    ],
    "breakdowns": [
      { "property": "$country" }
    ],
    "breakdown_limit": 10
  },
  "time_range": {
    "from": "2026-05-06T00:00:00Z",
    "to": "2026-06-05T00:00:00Z"
  },
  "granularity": "GRANULARITY_DAY"
}

Response sketch:

{
  "trends": {
    "series": [
      {
        "event_kind": "page_view",
        "breakdown": { "$country": "US" },
        "points": [
          { "time": "2026-05-06T00:00:00Z", "value": 412 },
          { "time": "2026-05-07T00:00:00Z", "value": 389 }
        ]
      },
      {
        "event_kind": "page_view",
        "breakdown": { "$country": "GB" },
        "points": [
          { "time": "2026-05-06T00:00:00Z", "value": 104 },
          { "time": "2026-05-07T00:00:00Z", "value": 97 }
        ]
      }
    ]
  }
}

Each series entry corresponds to one (event_kind, breakdown) pair. points are in ascending time order with one entry per granularity bucket.

Worked example: FUNNEL query

POST /shared.insights.v1.InsightsService/Query
Content-Type: application/json
Connect-Protocol-Version: 1
x-api-key: prv_...

{
  "spec": {
    "insight_type": "INSIGHT_TYPE_FUNNEL",
    "events": [
      { "event": { "kind": "signup_started" } },
      { "event": { "kind": "signup_completed" } },
      { "event": { "kind": "purchase" } }
    ],
    "conversion_window": "604800s"
  },
  "time_range": {
    "from": "2026-05-01T00:00:00Z",
    "to": "2026-06-01T00:00:00Z"
  },
  "granularity": "GRANULARITY_DAY"
}

Response sketch:

{
  "funnel": {
    "series": [
      {
        "breakdown": {},
        "steps": [
          { "event_kind": "signup_started",   "total": 1000 },
          { "event_kind": "signup_completed", "total": 650 },
          { "event_kind": "purchase",         "total": 120 }
        ]
      }
    ]
  }
}

With include_step_timing: true, each non-entry step gains a timing object:

{
  "event_kind": "signup_completed",
  "total": 650,
  "timing": {
    "avg": "180s",
    "median": "95s",
    "p95": "1200s",
    "distribution": [
      { "label": "0-30s",  "upper_bound": "30s",  "count": 78 },
      { "label": "30s-2m", "upper_bound": "120s", "count": 210 }
    ]
  }
}

The distribution array above is truncated for brevity - it always contains exactly 8 buckets in the canonical order, and the 8 boundaries are fixed (a full response returns all 8).

Performance notes

Insights queries run against ClickHouse. Query time scales with:

• Time range x granularity: wider ranges at fine granularities scan more partitions.
• Breakdown cardinality: avoid very high-cardinality breakdowns (e.g. user ID). Use breakdown_limit to cap result size.
• Funnel step count: funnel supports at most 20 steps.

Related

• API reference: base URL, auth, error codes
• Auto-properties: filterable $-prefixed properties
• RPC services: full method index