Sources

The source is the first token in every query. It determines what data the pipeline operates on.

Event source

Filter events by event_type. Use * for all events.

Syntax:

<event_name>
"<event_name>"
*

A leading | (with no source) is equivalent to *.

Description: Selects rows from the events table matching the given event type. * selects all event types. This is the most common source — most queries start here.

Event names can include special characters such as :, ., and /.

Examples:

# Count page views in the last 7 days
page_view | last 7d | count

# Special-character event names
landing:cta_click | last 7d | count
docs.view | last 7d | count
checkout/success | last 7d | count

# Quoted source form
"landing:cta_click" | last 7d | count

# Daily count of all events, broken down by type
* | last 30d | count by day, event_type

# Filter to web platform, list raw events
signup | where _platform = "web" | last 7d | list

Fallback form when source parsing is ambiguous:

* | where event_type = "landing:cta_click" | last 7d | count

Funnel

Multi-step conversion analysis. Measures how many users complete each step in sequence.

Syntax:

funnel <step1> -> <step2> -> <step3> [-> ...] [exclude <event>[, <event>...]]

Requires at least 2 steps. Supports | by <field> for breakout by a dimension. Supports | window <duration> to set the completion window (default: 30 days).

Description: Computes ordered funnel progression by stitched user (distinct_id) and returns step number + user count. Supports between-step exclusion via exclude ...: users are disqualified only when excluded events occur between completed steps.

Examples:

# Basic 3-step funnel
funnel signup -> activate -> purchase | last 30d

# Funnel with platform breakout
funnel signup -> activate -> purchase | last 30d | by _platform

# Funnel with 7-day completion window
funnel signup -> first_project -> first_query | last 90d | window 7d

# Funnel with between-step exclusion
funnel signup -> purchase exclude support_ticket | last 30d | window 7d

Note

Funnel steps must be event type names. The by stage is a standalone | by field (not | count by). Use it to break funnel results by a dimension like _platform or _browser.

Retention

Cohort retention analysis. Tracks what percentage of users who did a start event come back over subsequent time periods.

Syntax:

retention <start_event>
retention <start_event> returning <return_event>
retention <start_event> returning any

Description: Groups users into cohorts by the period they first did <start_event>. Tracks how many return in subsequent periods. Default granularity is week (12 periods). Default time range is 12 weeks. returning any matches any event as the return action. If returning is omitted, any event counts.

Supports | by <granularity> to change the cohort period (day, week, month). Supports | by <field> for breakdown.

Examples:

# Weekly retention for signups over 90 days
retention signup | last 90d

# Retention with a specific return event
retention signup returning purchase | last 90d

# Monthly retention cohorts
retention signup | last 6m | by month

# Daily retention
retention signup returning login | last 30d | by day

Paths

User flow analysis. Shows common event sequences starting from or leading to a given event.

Syntax:

paths from <event>
paths to <event>

Description: paths from collects event sequences starting at <event> for each user; paths to collects sequences leading up to <event>. Results are grouped by path (array of event types) with user counts. Default depth is 5 steps, default limit is 20 paths, and default path window is 1 hour.

Supports | window <duration> to control forward/backward path window, | depth <N> to control path length, | limit <N> to control number of paths returned, and | by <field> to use a field value as the path node label instead of event_type.

Examples:

# What do users do after signing up?
paths from signup | last 30d

# What leads users to purchase?
paths to purchase | last 30d

# Longer paths with more results
paths from signup | last 30d | depth 8 | limit 50

# Navigation flow by URL path (instead of repeated event_type names)
paths from page_view | last 30d | by _path

# Path flow by country
paths from page_view | last 30d | by _country

Tip

Use | by _path when all events in a path are the same type (e.g. page_view). Without it, you’d see page_view -> page_view -> page_view; with it, you see /home -> /pricing -> /signup.

Sessions

Session-level analytics. Groups events by session_id and computes per-session metrics.

Syntax:

sessions

Description: Aggregates events into sessions (sessions_agg). Default output: session count, average duration (seconds), and average events per session, grouped by day. Requires events to have session_id set (the Script Tag and TypeScript client set this automatically with a 30-minute inactivity timeout).

Supports session.* filters/grouping (attribution, landing/exit, language, geo, origin) and time granularity grouping (| count by day, | count by week).

Examples:

# Daily session metrics for the last 7 days
sessions | last 7d

# Weekly session metrics
sessions | last 12w | count by week

# Sessions for a specific time range
sessions | from 2026-01-01 to 2026-02-01

# Sessions by campaign
sessions | last 30d | count by session.utm_source

# Sessions by region
sessions | last 30d | count by session.region

Lifecycle

Lifecycle status analysis for one event type.

Syntax:

lifecycle <event>

Description: Classifies active users per period into New, Returning, Resurrected, and Dormant. Supports | by day|week|month and | where filters.

Examples:

lifecycle page_view | last 12w | by week
lifecycle core_usage | last 30d | by day

Stickiness

Active-day distribution for one event type.

Syntax:

stickiness <event>

Description: Counts users by number of active days in the selected window.

Examples:

stickiness page_view | last 30d
stickiness core_usage | last 12w

User timeline

All events for a single user, ordered by time.

Syntax:

user "<user_id_or_email>"

The user ID must be quoted. Matches against distinct_id (stitched identity: coalesce(user_id, mapped_user_id, device_id)).

Description: Returns all events for the specified user. Default time range is 30 days. Default output is a chronological event list (most recent first). Supports aggregation stages if you want counts instead of raw events.

Examples:

# Last 90 days of activity for a user
user "alice@acme.org" | last 90d | list

# Count events by type for a user
user "alice@acme.org" | last 30d | count by event_type

# Recent events (default 30d, default list)
user "u_abc123"

Tip

Use the email address or user ID you set via identify(). The query matches against the stitched distinct_id, so it finds events from before and after identification.

Users directory

Query the user_profiles table. Browse, filter, and count users.

Syntax:

users

Description: Queries the user_profiles table (populated by identify calls and ingestion-side profile upserts). Defaults to users active in the last 30 days (by last_seen). Supports | where for filtering, | list for raw profiles, | count for totals, and | count by <field> for breakdowns.

Available fields: user_id, email, email_domain, first_seen, last_seen, user.KEY (custom profile properties).

Examples:

# List users from a specific domain
users | where email_domain = "acme.org" | list

# Count users by email domain
users | count by email_domain | top 20

# Count users on the enterprise plan
users | where user.plan = "enterprise" | count

# Users active this month
users | this month | list

Formula

Computed metrics across event types. Combine count, unique, sum, or avg aggregates with arithmetic operators.

Syntax:

formula <metric>(<event>[, field]) <op> <metric>(<event>[, field]) [<op> ...]

Supported functions: count, unique, sum, avg. Supported operators: +, -, *, /.

Description: Each metric reference queries a specific event type. The formula combines them with arithmetic. Useful for conversion rates, ratios, and computed KPIs. For sum and avg, a second argument specifies the field. For unique, the field argument is optional (defaults to stitched identity when omitted).

Supports | by <granularity> for time-series output.

Examples:

# Conversion rate: purchases per signup
formula count(purchase) / count(signup) | last 30d

# Weekly conversion rate trend
formula count(purchase) / count(signup) | last 12w | by week

# Average revenue per user
formula sum(purchase, event_properties.amount) / unique(purchase) | last 30d

Note

Formula queries are event-level metrics. They do not use stitched identity for count. For unique user counts with identity stitching, prefer event queries with | unique distinct_id.

Fields introspection

Discover all available fields at runtime, including dynamic property keys from your data.

Syntax:

fields

Description: Returns a list of all queryable fields: system/core fields, session fields, user profile fields, plus any event_properties.* and user_properties.* keys actually present in your data within the time range. Supports time range stages.

Examples:

# All fields from the last 7 days
fields | last 7d

# All fields from the last 30 days
fields | last 30d

Tip

Run fields | last 7d when working with a new project to discover what properties are available for filtering and grouping.

Inspect

Discover event types and their properties. Shows counts, unique users, property coverage, sample values, and inferred types.

Syntax:

inspect
inspect *
inspect <event_name>

inspect * (or just inspect) returns a per-event-type overview: count, unique users, first/last seen, and top property keys.

inspect <event_name> returns property-level detail for a single event type: coverage %, inferred type (string/numeric/boolean), and top sample values.

Description: The recommended first query for LLMs and agents working with a new project. It answers “what events exist and what data does each carry?” in a single request.

Examples:

# Overview of all event types
inspect * | last 30d

# Inspect a specific event's properties
inspect signup | last 7d

# Inspect with quoted event name
inspect "landing:cta_click" | last 30d

Tip

Use inspect * to discover event types, then inspect <event> to understand a specific event’s schema before writing analytics queries. This replaces the manual multi-query discovery workflow.