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_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

EventQuery

Aggregation types

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 × 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