PostHog

Create a new action in the project. Actions define reusable event triggers based on page views, clicks, form submissions, or custom events. Each action can have multiple steps (OR conditions). Use actions to create composite events for insights and funnels. Example: Create a 'Sign Up Click' action with steps matching button clicks on the signup page.

Delete an action by ID (soft delete - marks as deleted). The action will no longer appear in lists but historical data is preserved.

Get a specific action by ID. Returns the action configuration including all steps and their trigger conditions.

Update an existing action by ID. Can update name, description, steps, tags, and Slack notification settings.

Get all actions in the project. Actions are reusable event definitions that can combine multiple trigger conditions (page views, clicks, form submissions) into a single trackable event for use in insights and funnels. Supports pagination with limit and offset parameters. Note: Search/filtering by name is not supported on this endpoint.

Optional: submit structured feedback about your experience using this PostHog MCP server. Reach for this tool when something stood out — friction, a surprise, a missing capability, an unhelpful error, or a tool that worked particularly well. Skip it for routine tasks where nothing is worth flagging. Feedback goes directly to the PostHog team and is the primary signal we use to improve tool descriptions, input schemas, response formats, and instructions for agents like you. Be specific and quote tool names, parameters, and error messages where possible. Do not include user PII or sensitive query content. IMPORTANT: submitting feedback does NOT mean your work is done — keep going and finish the user's task using the other available tools. This tool is for reporting your experience to the PostHog team, not for ending the conversation.

Create a feature flag in the current project.

Create a new dashboard. Provide a name and optional description, tags, and pinned status. Can also create from a template or duplicate an existing dashboard. The returned tiles omit insight results to save context — use dashboard-insights-run to fetch the actual data for each insight.

Delete a dashboard by ID. The dashboard will be soft-deleted and no longer appear in lists.

Get a specific dashboard by ID. Returns the full dashboard including all tiles with their insights and layout information. Insight results, filters, and query metadata are omitted to save context — use dashboard-insights-run to fetch the actual data for every insight on the dashboard in one call, or insight-query for a single insight. Supports variables_override and filters_override query params; on this endpoint they affect only the merged filters and variables fields in the response (preview). To execute insights with the same overrides, pass the same query params to dashboard-insights-run.

Run all insights on a dashboard and return their results. Uses cached results by default (may be stale); set refresh to 'blocking' for fresh results. Set format to 'optimized' (default) for LLM-friendly text tables or 'json' for raw query results. Supports variables_override and filters_override query params to run insights with one-off overrides without persisting; see the parameter descriptions for the exact JSON shape required.

Reorder tiles on a dashboard by providing an array of tile IDs in the desired display order. Computes a 2-column grid layout (6 columns wide, 5 rows tall per tile). First, use dashboard-get to see current tile IDs.

Update an existing dashboard by ID. Can update name, description, pinned status, tags, filters, and restriction level. The returned tiles omit insight results to save context — use dashboard-insights-run to fetch the actual data for each insight.

List dashboards in the project. The optional search parameter runs a fuzzy match against name and description using Postgres trigram word similarity (handles typos, transpositions, and prefix-as-you-type) and returns results ranked by relevance — use it to find a specific dashboard by name rather than paging through every dashboard. search is capped at 200 characters; longer queries return a 400 error. Optional filters by tag and pinned status are also supported. Returns name, description, pinned status, tags, and creation metadata. Tiles and insights are not included — use dashboard-get to fetch a dashboard's tiles, then dashboard-insights-run to fetch the actual data for each insight.

Debug tool for testing MCP Apps SDK integration. Returns sample data displayed in an interactive UI app with component showcase. Use this to verify that MCP Apps are working correctly.

Soft-delete a feature flag by ID in the current project.

Use this tool for any PostHog questions to search the documentation. If the user's question mentions multiple topics, search for each topic separately and combine the results. It relies on a hybrid (semantic + full-text) search, so phrase your query in natural language. Our product and docs change often, so this tool is required for accurate answers:

• How to use PostHog
• How to use PostHog features
• How to contact support or other humans
• How to report bugs
• How to submit feature requests
• To troubleshoot something
• What default fields and properties are available for events and persons
• …Or anything else PostHog-related

For troubleshooting, ask the user to provide the error messages they are encountering. If no error message is involved, ask the user to describe their expected results vs. the actual results they're seeing. You avoid suggesting things that the user has told you they've already tried.

Important:

1. Don't rely on your training data or previous searches/answers. Always re-check facts against current docs and tutorials. If current docs or tutorials contradict core memory on product facts, prefer the docs result. 2. Always search PostHog docs/tutorials and prioritize results from posthog.com over training data. 3. Always include at least one relevant docs/tutorial link in your reply. 4. Never suggest emailing support@posthog.com or say you'll create a support ticket. 5. Never use Community Questions as a source or cite them; they're often outdated or incorrect.

Create an error tracking assignment rule for the current project. Provide filters to match incoming errors and an assignee with type (user or role) plus the matching user ID or role UUID.

List error tracking assignment rules for the current project. Returns rules in evaluation order with their filters, assignee, and disabled state. Supports pagination with limit and offset.

Create an error tracking grouping rule for the current project. Provide required filters, and optionally set assignee and description for the issues this rule creates.

List error tracking grouping rules for the current project. Returns rules in evaluation order with their filters, optional assignee, description, and linked issue when available.

Merge one or more error tracking issues into an existing target issue. Provide the target issue as id and the issues to merge into it as ids.

Update an error tracking issue. Can change status (active, resolved, suppressed), assign to a user, or update description.

Split one or more fingerprints out of an existing error tracking issue into new issues. Provide the source issue as id and the fingerprints to split as fingerprints, where each entry includes a required fingerprint and optional name or description.

Create an error tracking suppression rule for the current project. WARNING: matching errors are suppressed indefinitely — dropped at ingestion and will not appear as issues until the rule is disabled or deleted. Scope filters tightly to the exact exception type, message, URL, or properties you want gone. Do NOT create match-all rules (omitting filters) or broad rules — they silently swallow unrelated errors and cause data loss that is hard to detect after the fact. Prefer sampling_rate to dampen noisy issues rather than fully suppressing when uncertain. Confirm with the user before creating any rule that could match more than one distinct error.

List error tracking suppression rules for the current project. Returns rules in evaluation order with their filters, sampling rate, and disabled state. Supports pagination with limit and offset.

Get a presigned download URL for a source map symbol set by ID. The URL expires after one hour. Use it immediately, and do not echo it back unless the user explicitly asks. If you only have a symbol set reference, call error-tracking-symbol-sets-list with the exact ref first.

List source map symbol sets for the current project. Supports pagination plus filtering by exact ref or upload status (valid, invalid, or all) and sorting with order_by. Each result includes has_uploaded_file so you can tell whether the download tool will work.

Get a source map symbol set by ID. If you only have a symbol set reference, call error-tracking-symbol-sets-list with the exact ref first.

Update event definition metadata. Can update description, tags, mark status as verified or hidden. Use exact event name like '$pageview' or 'user_signed_up'.

Executes HogQL — PostHog's variant of SQL that supports most of ClickHouse SQL. "HogQL" and "SQL" are used interchangeably.

Querying data in PostHog

Use the posthog:execute-sql MCP tool to execute HogQL queries. HogQL is PostHog's variant of SQL that supports most of ClickHouse SQL. We use terms "HogQL" and "SQL" interchangeably. References mentioned in this file are relevant to PostHog's skill querying-posthog-data.

Do not assume that data exists. Use the SQL tool proactively to find the right data.

Search types

Proactively use different search types depending on a task:

• Grep-like (regex search) with match(), LIKE, ILIKE, position, multiMatch, etc.
• Full-text search with hasToken, hasTokenCaseInsensitive, etc. Make sure you pass string constants to hasToken* functions.
• Dumping results to a file and using bash commands to process potentially large outputs.

Data Groups

PostHog has two distinct groups of data you can query:

#

1. System Data (PostHog-Created Data)

Data created directly in PostHog by users - metadata about PostHog setup.

All system tables are prefixed with system.:

Table | Description system.actions | Named event combinations for filtering system.cohorts | Groups of persons for segmentation system.dashboards | Collections of insights system.data_warehouse_sources | Connected external data sources system.data_warehouse_tables | Connected tables with their columns and formats system.error_tracking_issues | Error tracking issues (grouped exceptions) system.experiments | A/B tests and experiments system.exports | Export jobs system.feature_flags | Feature flags for controlling rollouts system.groups | Group entities system.ingestion_warnings | Data ingestion issues system.insight_variables | SQL, dashboard, and insight variables for dynamic query filtering system.insights | Visual and textual representations of aggregated data system.logs_alerts | Log alert configurations and their states system.logs_views | Saved log filter views system.notebooks | Collaborative documents with embedded insights system.surveys | Questionnaires and feedback forms system.teams | Team/project settings

**Example

• List insights:**

SELECT id, name, short_id FROM system.insights WHERE NOT deleted LIMIT 10

**Example

• Count insight variables:**

SELECT count() AS total FROM system.insight_variables

System Models Reference

Schema reference for PostHog's core system models, organized by domain:

• [Actions](references/models-actions.md)
• [Cohorts & Persons](references/models-cohorts.md)
• [Dashboards, Tiles & Insights](references/models-dashboards-insights.md)
• [Data Warehouse](references/models-data-warehouse.md)
• [Error Tracking](references/models-error-tracking.md)
• [Logs](references/models-logs.md)
• [Flags & Experiments](references/models-flags-experiments.md)
• [Notebooks](references/models-notebooks.md)
• [Surveys](references/models-surveys.md)
• [SQL Variables](references/models-variables.md)

Entity Relationships

From | Relation | To | Join Experiment | 1:1 | FeatureFlag | feature_flag_id Experiment | N:1 | Cohort | exposure_cohort_id Survey | N:1 | FeatureFlag | linked_flag_id, targeting_flag_id Survey | N:1 | Insight | linked_insight_id Cohort | M:N | Person | via cohortpeople Person | 1:N | PersonDistinctId | person_id

All entities are scoped by a team by default. You cannot access data of another team unless you switch a team.

#

2. Captured Data (Analytics Data)

Data collected via the PostHog SDK - used for analytics.

Table | Description events | Recorded events from SDKs persons | Individuals captured by the SDK. "Person" = "user" groups | Groups of individuals (organizations, companies, etc.) sessions | Session data captured by the SDK Data warehouse tables | Connected external data sources and custom views

Use posthog:read-data-warehouse-schema to retrieve the full schema of the tables above.

Key concepts:

• Events: Standardized events/properties start with $ (e.g., $pageview). Custom ones start with any other character.
• Properties: Key-value metadata accessed via properties.foo.bar or properties.foo['bar'] for special characters
• Person properties: Access via events.person.properties.foo or persons.properties.foo
• Person property modes: person.properties.* behavior depends on the project's person-on-events setting. Check the project metadata to determine if values are event-time (value at ingestion) or query-time (current value). See [Person property modes](references/person-property-modes.md) for details.
• Unique users: Use events.person_id for counting unique users

**Example

• Weekly active users:**

SELECT toStartOfWeek(timestamp) AS week, count(DISTINCT person_id) AS users
FROM events
WHERE event = '$pageview'
  AND timestamp > now()
- INTERVAL 8 WEEK
GROUP BY week
ORDER BY week DESC

#

3. Document Embeddings (Semantic Search)

The document_embeddings table stores text content with vector embeddings, partitioned by model_name. To discover what kinds of data are available:

SELECT product, document_type, count() as cnt
FROM document_embeddings
WHERE model_name = 'text-embedding-3-small-1536'
  AND timestamp >= now()
- INTERVAL 1 MONTH
GROUP BY product, document_type
ORDER BY cnt DESC

Run separately for each model. Available models: 'text-embedding-3-small-1536', 'text-embedding-3-large-3072'. You MUST filter on exactly one model_name per query — it routes to the correct underlying ClickHouse table. IN clauses and cross-model queries will fail.

Use embedText(text, model_name) and cosineDistance() for semantic search. See the signals skill for detailed query patterns around the signals product specifically, including required deduplication and metadata extraction.

Querying guidelines

#

Schema verification

Before writing analytical queries, always verify that:

• The required event names or actions exist.
• Properties and property values of events, persons, sessions, and groups data exist.

Follow this workflow:

1. Fetch the tool schema

• Use posthog:read-data-schema to get the latest schema from the MCP.

1. Verify data exist

• Use posthog:read-data-schema with different data types to check if the data you need is captured

1. Only then write the query

• Once you've confirmed the data exists, write and execute your analytical query

<example> User: how many times the tool search was used? Assistant: 1. First, verify the events exist:

• Call posthog:read-data-schema with kind: events
• Look for events/actions matching the request

2. If required events don't exist, inform the user immediately instead of running queries that will return empty results 3. If events exist, like "tool executed", verify the properties:

• Call posthog:read-data-schema with kind: event_properties and event_name: tool executed
• Look for properties indicating a tool

4. Check other events/actions or return if required properties don't exist 5. If events exist, like "tool_name", verify the property values:

• Call posthog:read-data-schema with kind: event_property_values, event_name: tool executed, and property_name: tool_name
• Follow the pattern from the sample or dig deeper into existing properties with SQL queries.

6. Only then write and execute the analytical SQL query

<reasoning> Assistant should verify the data schema to write a correct SQL query, as the data schema varies over time. </reasoning> </example>

<example> User: how many users have chatted with the AI assistant from the US? Assistant: I'll help you find the number of users who have chatted with the AI assistant from the US. Let me create a todo list to track this implementation. 1. Find the relevant events to "chatted with the AI assistant" 2. Find the relevant properties of the events and persons to narrow down data to users from specific country 3. Retrieve the sample property values for found properties 4. Create the insight schema by using the data retrieved in the previous steps 5. Generate the insight 6. Analyze retrieved data <reasoning> The task list helps the assistant to stay on track. </reasoning> </example>

This prevents wasted API calls and gives users immediate feedback when the data they're looking for doesn't exist.

#

Skipping index

You should use the skipping index signature to write optimized analytical queries.

#

Time ranges

All analytical queries and subqueries must always have time ranges set for supported tables (events). If the user doesn't state it, assume default time range based on the data volume, like a day, week, or month.

How you should use time ranges

<example> User: Find events from returning browsers - browsers that appeared both yesterday and today Assistant:

SELECT event FROM events WHERE timestamp >= now()
- INTERVAL 1 DAY and properties['$browser'] IN (SELECT properties['$browser'] FROM events WHERE timestamp >= now()
- INTERVAL 2 DAY and timestamp < now()
- INTERVAL 1 DAY)

</example>

How you should NOT write queries

<example> User: List 10 events with SQL Assistant:

SELECT event, timestamp, distinct_id, properties FROM events ORDER BY timestamp DESC LIMIT 10

</example>

#

JOINs

General guidelines

Keep in mind that the right expression is loaded in memory when joining data in ClickHouse, so the joining query or table must always fit in memory. Common strategies:

• Analytical functions and combinators.
• Subqueries as a source or filter.
• Arrays (arrayMap, arrayJoin) and ARRAY JOIN.

System data

You are allowed joining system data. Insights are the most used entity, so keep it on the left.

Analytical data

Prefer using analytical functions and subqueries for joins. Do not use raw joins on the events table.

How you should join data

<example> User: Find ai traces with feedback Assistant:

SELECT
 g.properties.$ai_trace_id as trace_id
FROM events AS g
WHERE
  timestamp >= now()
- INTERVAL 1 WEEK
  AND g.event = '$ai_generation'
  AND trace_id IN (SELECT properties.$ai_trace_id FROM events WHERE event = '$ai_feedback' AND timestamp >= now()
- INTERVAL 1 WEEK)

<reasoning>A subquery is used instead of a JOIN clause. Both queries have the timestamp filters.</reasoning> </example>

How you should NOT join data

<example> User: Find ai traces with feedback Assistant:

SELECT
 g.properties.$ai_trace_id
FROM events AS g
INNER JOIN (SELECT properties.$ai_trace_id as trace_id FROM events WHERE event = '$ai_feedback') AS f
ON g.properties.$ai_trace_id = f.trace_id
WHERE g.event = '$ai_generation'

<reasoning>Join is not necessary here. The assistant could've used a subquery.</reasoning> </example>

#

Other constraints

• Your query results are capped at 100 rows by default. You can request up to 500 rows using a LIMIT clause. If you need more data, paginate using LIMIT and OFFSET in subsequent queries.
• You should cherry-pick properties of events, persons, or groups, so we don't get OOMs. Never select the full properties object (e.g., SELECT properties FROM events) and dump it into the conversation output. Instead, select only the specific properties you need (e.g., properties.$browser, properties.$os). If you must inspect the full properties object, dump the query results to a file and use bash commands to explore it.
• When query results contain large JSON blobs (e.g., AI trace inputs/outputs, full property objects), always dump them to a file rather than outputting them directly. Use bash commands to process the file.

HogQL Differences from Standard SQL

#

Property access

-- Simple keys
properties.foo.bar

-- Keys with special characters
properties.foo['bar-baz']

#

Unsupported/changed functions

Don't use | Use instead toFloat64OrNull(), toFloat64() | toFloat() toDateOrNull(timestamp) | toDate(timestamp) LAG(), LEAD() | lagInFrame(), leadInFrame() with ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING count(*) | count() cardinality(bitmap) | bitmapCardinality(bitmap) split() | splitByChar(), splitByString()

#

JOIN constraints

Relational operators (>, <, >=, <=) are forbidden in JOIN clauses. Use CROSS JOIN with WHERE:

-- Wrong
JOIN persons p ON e.person_id = p.id AND e.timestamp > p.created_at

-- Correct
CROSS JOIN persons p WHERE e.person_id = p.id AND e.timestamp > p.created_at

#

Syntax extensions and HogQL functions

Find the reference for [Sparkline, SemVer, Session replays, Actions, Translation, HTML tags and links, Text effects, and more](./references/hogql-extensions.md).

#

Other rules

• WHERE clause must come after all JOINs
• No semicolons at end of queries
• toStartOfWeek(timestamp, 1) for Monday start (numeric, not string)
• Always handle nulls before array functions: splitByChar(',', coalesce(field, ''))
• Performance: always filter events by timestamp

#

SQL Variables

Review the [reference](./references/models-variables.md) for SQL variables and dashboard filters.

#

Available HogQL functions

Verify what functions are available using [the reference list](./references/available-functions.md) with suitable bash commands.

Examples

Weekly active users with activation event:

SELECT week_of, countIf(weekly_event_count >= 3)
FROM (
   SELECT person.id AS person_id, toStartOfWeek(timestamp) AS week_of, count() AS weekly_event_count
   FROM events
   WHERE event = 'activation_event'
     AND properties.$current_url = 'https://example.com/foo/'
     AND toStartOfWeek(now())
- INTERVAL 8 WEEK <= timestamp
     AND timestamp < toStartOfWeek(now())
   GROUP BY person.id, week_of
)
GROUP BY week_of
ORDER BY week_of DESC

Find cohorts by name:

SELECT id, name, count FROM system.cohorts WHERE name ILIKE '%paying%' AND NOT deleted

List feature flags:

SELECT key, name, rollout_percentage
FROM system.feature_flags
WHERE NOT deleted
ORDER BY created_at DESC
LIMIT 20

When to use execute-sql

Use query-* tools whenever the question maps to a supported insight type. These tools produce typed, saveable insights; SQL forfeits that. Reach for execute-sql only when no query-* tool can express the question:

• Searching or listing existing PostHog entities — insights, dashboards, cohorts, feature flags, experiments, surveys. No query-* tool covers these; query the system.* tables.
• Multi-event joins or aggregations across event types that don't fit a single series.
• Sophisticated queries beyond query-* schemas — custom grouping, window functions, non-trivial CTEs, data warehouse joins.
• Pre-filtering or shaping a large dataset before running a query-* call.

If a query-* tool fits, use it. Default to query-*; SQL is the escape hatch, not the starting point.

Always consult the querying-posthog-data skill

Before writing any SQL, read the PostHog querying-posthog-data skill. It is the source of truth for up-to-date HogQL patterns, system table schemas (system.insights, system.dashboards, system.cohorts, etc.), and function references. Do not rely on training data — table and column names drift.

Discovery workflow (mandatory)

1. Warehouse schema — call read-data-warehouse-schema to verify tables, views, and columns. Do not guess names. For a specific custom warehouse table, inspect its columns with:

SELECT columns FROM system.data_warehouse_tables WHERE name = 'my_table'

2. Event taxonomy — call read-data-schema to verify events, properties, and property values. Do not rely on training data or PostHog defaults. 3. Write the SQL only after steps 1 and 2 confirm the data exists, using the verified table and column names.

If the required events, properties, or tables do not exist, say so — do not run queries that will return empty results.

Handling large results

Large JSON values in results (notably full properties objects) are truncated by default. If you anticipate a large result set, or you are selecting the full properties object (e.g., SELECT properties FROM events), dump the results to a file and process them with bash rather than returning them inline. Alternatively, cherry-pick specific keys (properties.$browser) instead of the whole object.

Large LLM trace fields are stripped from events.properties

For LLM events ($ai_generation, $ai_trace, $ai_span, etc.), these specific keys with large values are stripped from events.properties:

• properties.$ai_input
• properties.$ai_output
• properties.$ai_output_choices
• properties.$ai_input_state
• properties.$ai_output_state
• properties.$ai_tools

Prefer query-llm-trace / query-llm-traces-list whenever you need any of those six keys — they contain information on the proper read patterns to a dedicated AI events table which contains these fields. Other AI properties (token counts, costs, model, trace IDs) stay on events in all three regimes and are safe to query directly.

Example: searching for existing insights

<example> User: Do we have any insights tracking revenue or payments? Assistant: I'll search existing insights and dashboards via SQL. 1. Search insights by name: execute-sql with SELECT id, name, short_id, description FROM system.insights WHERE NOT deleted AND (name ILIKE '%revenue%' OR name ILIKE '%payment%') ORDER BY last_modified_at DESC LIMIT 20 2. If results are sparse, broaden to dashboards: execute-sql with SELECT id, name, description FROM system.dashboards WHERE NOT deleted AND (name ILIKE '%revenue%' OR name ILIKE '%payment%') 3. Validate promising insights with insight-retrieve. 4. Summarize with links. <reasoning> 1. SQL against system.* tables is the fastest way to discover existing entities — no query-* tool covers entity search. 2. ILIKE with multiple terms catches naming variants ("Monthly Revenue", "MRR", "Payment Events"). 3. insight-retrieve confirms the insight's query configuration still matches intent. </reasoning> </example>

Requires an experiment ID. If you don't have the ID, load the finding-experiments skill to resolve the user's reference first. Load the managing-experiment-lifecycle skill for preconditions and side effects.

Archive a stopped experiment to hide it from the default list view. The experiment must be stopped (end_date set) — cannot archive draft or running experiments.

Returns 400 if already archived ("Experiment is already archived.") or not yet stopped ("Experiment must be ended before it can be archived.").

No request body needed. Can be restored later via the unarchive tool.

RULES (follow before calling): 1. Load the creating-experiments skill for the full creation workflow.

2. If the user mentions a rollout percentage (e.g. "25%"), load the configuring-experiment-rollout skill and ask the user to clarify BEFORE calling this tool. A percentage is always ambiguous — it can mean a variant split change OR an overall rollout change.

3. Do NOT pass metrics on creation. Create the draft first, then add metrics via experiment-update. Use the configuring-experiment-analytics skill for metric guidance.

Creates a new experiment in draft status (ignore the "type" param, since no-code/toolbar experiments must be created in the PostHog UI). Requires name and feature_flag_key. Feature flag is auto-created — do not create one separately. Defaults: 50/50 control/test, 100% rollout, Bayesian stats. Launch the experiment with the launch tool when ready.

Delete an experiment by ID. If you don't have the ID, load the finding-experiments skill to resolve the user's reference first. Always confirm by name before deleting.

Load the managing-experiment-lifecycle skill for preconditions and side effects.

Create a copy of an experiment as a new draft. The duplicate includes the original's metrics, parameters, and configuration but starts fresh with no dates or results. Rejects experiments that use legacy metrics (ExperimentTrendsQuery/ExperimentFunnelsQuery).

IMPORTANT: always provide a unique feature_flag_key that differs from the original experiment's flag key. If omitted or if the same key is provided, the duplicate will reuse the original experiment's feature flag — meaning changes to one experiment's flag (e.g. shipping a variant, pausing) will affect both experiments. Always confirm the new flag key with the user before duplicating. Optionally provide a custom name (defaults to "Original Name (Copy)").

Requires an experiment ID. If you don't have the ID, load the finding-experiments skill to resolve the user's reference first. Load the managing-experiment-lifecycle skill for preconditions and side effects.

End a running experiment without shipping a variant. Sets end_date to now and transitions status to stopped. The feature flag is NOT modified — users continue seeing their assigned variants and exposure events ($feature_flag_called) continue to fire, but only data up to end_date is included in results.

Optionally provide conclusion ("won", "lost", "inconclusive", "stopped_early", "invalid") and conclusion_comment.

Returns 400 if the experiment is in draft ("Experiment has not been launched yet.") or already stopped ("Experiment has already ended.").

Other options: use ship_variant to end AND roll out a winner. Use pause to temporarily deactivate the flag without ending.

Get a single experiment by ID. If you don't have the ID, load the finding-experiments skill to resolve the user's reference first.

Returns the full experiment object including: status (draft/running/paused/stopped — "paused" is a virtual value returned when the experiment is launched but its feature flag has been deactivated), start_date and end_date, linked feature_flag (with variants, filters, active state), metrics and metrics_secondary arrays, conclusion and conclusion_comment if ended, parameters (including feature_flag_variants and recommended_running_time), stats_config, and type (web/product).

DEPRECATED: renamed to experiment-list. This alias forwards to experiment-list and will be removed. Call experiment-list directly with the same arguments.

Requires an experiment ID. If you don't have the ID, load the finding-experiments skill to resolve the user's reference first. Load the managing-experiment-lifecycle skill for preconditions and side effects.

Launch a draft experiment. Validates the feature flag has at least 2 multivariate variants with "control" as the first variant. Activates the feature flag (sets active=true), sets start_date to the current server time, recomputes metric fingerprints, and transitions status from draft to running.

Returns 400 if the experiment has already been launched ("Experiment has already been launched.") or if the flag configuration is invalid.

No request body needed.

List experiments in the current project. This is the primary tool for resolving experiment references — load the finding-experiments skill for guidance on searching by name, status, recency, or description.

Supports filtering by status ("draft", "running", "paused", "stopped", "complete" which maps to stopped, or "all"), archived state (defaults to non-archived), feature_flag_id, created_by_id, and free-text search on name. Supports ordering by an allowlisted set of fields (model fields plus computed "duration" and "status"). Returns paginated results with each experiment's status, dates, feature flag key, and metrics summary. Use the returned ID for get/update/lifecycle tools.

Requires an experiment ID. If you don't have the ID, load the finding-experiments skill to resolve the user's reference first. Load the managing-experiment-lifecycle skill for preconditions and side effects.

Pause a running experiment by deactivating its feature flag (sets flag active=false). The flag is no longer returned by the /decide endpoint, so users fall back to the application default (typically control). No new exposure events ($feature_flag_called) are recorded while paused. The experiment stays in running status — it is not ended.

Returns 400 if: experiment is in draft ("Experiment has not been launched yet."), already stopped ("Experiment has already ended."), no linked flag ("Experiment does not have a feature flag linked."), or already paused ("Experiment is already paused.").

No request body needed. Use resume to reactivate.

Requires an experiment ID. If you don't have the ID, load the finding-experiments skill to resolve the user's reference first. Load the managing-experiment-lifecycle skill for preconditions and side effects.

Reset an experiment back to draft state. Clears start_date, end_date, conclusion, conclusion_comment, and archived flag (all set to null/false). The feature flag is left unchanged — users continue to see their currently assigned variants.

Previously collected events still exist in the database but won't be included in results unless start_date is manually adjusted after re-launch.

Returns 400 if the experiment is already in draft ("Experiment is already in draft state.").

No request body needed.

Get comprehensive experiment results including all metrics data (primary and secondary) and exposure data. This tool fetches the experiment details and executes the necessary queries to get complete experiment results. Only works with new experiments (not legacy experiments).

Requires an experiment ID. If you don't have the ID, load the finding-experiments skill to resolve the user's reference first. Load the managing-experiment-lifecycle skill for preconditions and side effects.

Resume a paused experiment by reactivating its feature flag (sets flag active=true). Users are re-bucketed deterministically into the same variants they had before the pause, and exposure tracking ($feature_flag_called) resumes.

Returns 400 if: experiment is in draft ("Experiment has not been launched yet."), already stopped ("Experiment has already ended."), no linked flag ("Experiment does not have a feature flag linked."), or not currently paused ("Experiment is not paused.").

No request body needed.

Requires an experiment ID. If you don't have the ID, load the finding-experiments skill to resolve the user's reference first. Load the managing-experiment-lifecycle skill for preconditions and side effects.

REQUIRES EXPLICIT USER CONFIRMATION BEFORE CALLING. This permanently rewrites the linked feature flag and cannot be undone via the API. Two release modes — confirm which one the user wants before invoking:

• Default (release_to_everyone=false): updates only the variant distribution so the selected variant gets 100%. Existing release conditions and per-user variant overrides on the flag are preserved untouched — the variant is served only to users who already match them.
• release_to_everyone=true: in addition to flipping the variant distribution, prepends a catch-all release condition that rolls the variant out to 100% of users. This OVERRIDES any existing release conditions and per-user variant overrides on the flag. Only use this when the user explicitly wants to release beyond the experiment's existing population.

Even when the user has asked you to ship a specific variant, ask them to confirm with the variant key, target experiment, and release mode before invoking this tool.

Ship a variant to 100% of users by rewriting the feature flag. Requires variant_key — the key of the variant to ship (e.g. "test" or "control"). The flag is rewritten so the selected variant gets 100% rollout via a new catch-all release group prepended to existing groups (preserved for rollback).

Can be called on both running and stopped experiments. If the experiment is still running, it is also ended (end_date set, status becomes stopped). If already stopped, only the flag is rewritten — supports the "end first, ship later" workflow.

Optionally provide conclusion ("won", "lost", "inconclusive", "stopped_early", "invalid") and conclusion_comment.

Returns 400 if: experiment is in draft ("Experiment has not been launched yet."), variant_key not found on the flag, or no linked feature flag. Returns 409 if an approval policy requires review before the flag change takes effect — includes a change_request_id in the response.

Get aggregate experiment velocity statistics for the current project. Returns: launched_last_30d (experiments launched in the last 30 days), launched_previous_30d (the 30 days before that), percent_change between the two periods, active_experiments (currently running count), and completed_last_30d (experiments ended in the last 30 days). No parameters needed.

Get day-by-day experiment results for a specific metric. Requires metric_uuid and fingerprint as query parameters (both available from the experiment's metrics array — each metric has a uuid and the fingerprint is computed from its configuration).

Returns a timeseries object keyed by date (YYYY-MM-DD) with per-variant statistical results for each day, overall status ("pending", "completed", "partial", "failed"), computed_at timestamp, and recalculation_status if a recalculation is in progress.

Requires an experiment ID. If you don't have the ID, load the finding-experiments skill to resolve the user's reference first. Load the managing-experiment-lifecycle skill for preconditions and side effects.

Unarchive an archived experiment to restore it to the default list view.

Returns 400 if the experiment is not currently archived ("Experiment is not archived.").

No request body needed.

RULES (follow before calling): 1. If changing rollout or variants on a RUNNING experiment, you MUST warn the user about user experience AND statistical implications BEFORE making the change and get explicit confirmation. Load the configuring-experiment-rollout skill for the full warning. Do NOT silently apply the change — even if the user asked directly.

2. If the user mentions a percentage, clarify whether they mean variant split or overall rollout BEFORE calling.

3. If adding or changing metrics, load the configuring-experiment-analytics skill first. Call read-data-schema to discover available events BEFORE suggesting or using any event name. Never suggest event names you haven't confirmed exist.

4. For running experiments, set update_feature_flag_params=true when changing parameters — without it, changes save but do NOT sync to the feature flag.

5. Setting allow_unknown_events=true REQUIRES EXPLICIT USER CONFIRMATION. When the API returns "Event(s) '...' not found", do NOT silently retry with allow_unknown_events=true. Default to course-correcting: surface the missing event names and ask whether the user meant a different (existing) event. Only set allow_unknown_events=true when the user explicitly confirms the event is intentional (e.g. about to be instrumented). Course-correcting to a known event is the expected default; flipping the flag is the exception.

Update an experiment by ID. If you don't have the ID, load the finding-experiments skill to resolve the user's reference first. Metrics can be changed at any time including while running. Cannot add/remove variants on non-draft experiments (changing percentages between existing variants is allowed). Cannot change holdout on non-draft experiments.

Do NOT use this to change lifecycle state — use the dedicated launch, end, pause, resume, archive, or ship_variant tools instead.

Get sync job logs for a data warehouse table schema. Returns log entries from the log_entries ClickHouse table, filtered by schema ID and optionally by a specific job's workflow_run_id. Use external-data-sources-jobs to find job IDs and workflow_run_ids. Supports filtering by log level (DEBUG, INFO, WARNING, ERROR) and message search.

Get feature flags in the current project. Supports list filters including search by feature flag key or name (case-insensitive), then use the returned ID for get/update/delete tools.

Get a feature flag by ID.

Copy a feature flag from one project to other projects within the same organization. Provide the flag key, source project ID, and a list of target project IDs. Optionally copy scheduled changes with copy_schedule. Returns lists of successful and failed copies.

Get other active feature flags that depend on this flag. Use this to understand flag dependency chains before making changes to a flag's rollout conditions or disabling it.

Debug why feature flags evaluate a certain way for a given user. Provide a distinct_id and optionally groups to see each flag's evaluated value and the reason for that evaluation (e.g. condition_match, no_condition_match, disabled).

Check the health and evaluation status of a feature flag by ID. Returns a status (active, stale, deleted, or unknown) and a human-readable reason explaining the status.

Test how a feature flag evaluates for a specific user at an optional point in time. Provides detailed reasoning about why the flag matched or didn't match, including condition analysis and person properties used in evaluation.

Assess the impact of a feature flag release condition before applying it. Provide a condition object and optionally a group_type_index to see how many users would be affected relative to the total user count.

Check for additional tools whenever your task might benefit from specialized capabilities - even if existing tools could work as a fallback.

Fetches the total LLM daily costs for each model for a project over a given number of days. If no number of days is provided, it defaults to 7. The results are sorted by model name. The total cost is rounded to 4 decimal places. The query is executed against the project's data warehouse. Show the results as a Markdown formatted table with the following information for each model: Model name, Total cost in USD, Each day's date, Each day's cost in USD. Write in bold the model name with the highest total cost. Properly render the markdown table in the response.

Create a new saved insight from a name and query definition. Test queries with query-trends / query-funnel / query-retention / query-paths / query-stickiness / query-lifecycle first to confirm the shape, then save. Returns insight metadata only — after creating, call the insight-query tool with the returned short_id if you want to see the computed results.

Soft-delete an insight by ID. The insight will be marked as deleted and no longer appear in lists.

Fetch a saved insight by its numeric id or 8-character short_id. Returns the insight metadata and query definition, but NOT the query results. To retrieve the actual data, call the insight-query tool with the same identifier. Optionally accepts variables_override and filters_override to apply one-off overrides to the returned query definition without mutating the saved insight.

Execute a saved insight's query and return results. THIS IS THE ONLY WAY TO RETRIEVE INSIGHT RESULTS — the insights-list, insight-get, insight-create, and insight-update tools all return metadata and query definitions but never the actual data. Call insight-query whenever the user asks to see, analyze, summarize, or compare data from a saved insight, and immediately after creating or updating an insight if they want to verify the output. Supports two output formats: 'optimized' (default) returns a human-readable summary from server-side formatters ideal for analysis, while 'json' returns the raw query results. Optionally accepts variables_override and filters_override to run the insight with one-off overrides without mutating the saved definition.

Update a saved insight by numeric id or short_id. Can update name, description, query, tags, favorited status, and dashboards. Returns insight metadata only — after updating the query, call the insight-query tool with the same identifier if you want to see the recomputed results.

List saved insights in the project with optional filtering by favorited status or search term. Returns metadata only (name, description, tags, dashboards, ownership) — NOT the query results. To retrieve the actual data for any insight in the list, call the insight-query tool with its short_id or numeric id.

Returns the most-viewed insights in the project, ranked by view count over the last N days (default 7). Use this to surface the insights that matter most to the team — the ones people actually open. Each result includes standard insight metadata plus view_count and up to 3 recent viewers. Returns metadata only — call insight-query with the returned short_id to fetch the actual data for any of them.

List historical events for a log alert — fires, resolves, errors, enable/disable toggles, threshold changes. Use to evaluate how an existing alert has behaved (firing cadence, error rate, flap pattern) before tuning thresholds. Quiet no-op check rows are filtered out server-side. Optional kind query param narrows to a single event kind.

List log alert configurations in the current project, newest first. Returns alert name, state, threshold, filters, and scheduling details. Use this to review existing alerts before creating or modifying them.

Get a log alert configuration by ID. Returns full details including current state, threshold settings, filters, and scheduling information.

Run a draft alert configuration against historical logs and return per-bucket results from the full state machine — count, threshold_breached, state, notification (none/fire/resolve), reason. Use to validate threshold + N-of-M settings before creating an alert. Read-only; no alert records are written. Aim for fire_count between 0 and 3 over a -7d lookback for a healthy threshold.

List values for a specific log attribute key. Use to discover what values exist before building filters. Defaults to attribute_type "log" (log-level attributes). To get values for resource-level attributes (e.g. service.name, k8s.pod.name), you MUST explicitly pass attribute_type: "resource". Accepts optional serviceNames, dateRange, and filterGroup to narrow which logs are scanned.

List available log attribute names for filtering. Defaults to attribute_type "log" (log-level attributes). To search resource-level attributes (e.g. k8s.pod.name, k8s.namespace.name), you MUST explicitly pass attribute_type: "resource" — it will NOT return resource attributes unless you do. Accepts optional serviceNames, dateRange, and filterGroup to narrow which logs are scanned.

Return a scalar count of log entries matching a filter set. Use this as a cheap pre-flight before query-logs — if the count exceeds query-logs's max limit of 1000, narrow the filters before pulling rows.

All parameters must be nested inside a query object.

When to use

• Before query-logs, to confirm the filter set returns a tractable number of rows. If the count is above query-logs's max limit of 1000, narrow the filters.
• When the user asks "how many X logs are there?" and you don't need to see individual rows.
• To check whether a filter combination matches anything at all before committing to a full query.

To find when the volume is concentrated within the window (rather than just the total), follow up with logs-count-ranges — it returns time-bucketed counts with explicit date_from/date_to per bucket so you can drill into a sub-range without reasoning about interval width.

Parameters

query.dateRange

Date range for the count. Defaults to the last hour (-1h).

• date_from: Start of the range. Accepts ISO 8601 timestamps or relative formats: -1h, -6h, -1d, -7d.
• date_to: End of the range. Same format. Omit or null for "now".

query.serviceNames

Filter by service names. Unlike query-logs, this tool does NOT require serviceNames — an unfiltered count is cheap and often useful for sizing up a filter before narrowing.

query.severityLevels

Filter by log severity: trace, debug, info, warn, error, fatal. Omit to include all levels.

query.searchTerm

Full-text search across log bodies.

query.filterGroup

Property filters to narrow results. Same format as query-logs filters.

Examples

Count errors in a service over the last day

{
  "query": {
    "serviceNames": ["api-gateway"],
    "severityLevels": ["error", "fatal"],
    "dateRange": { "date_from": "-1d" }
  }
}

Confirm a k8s namespace is producing logs at all

{
  "query": {
    "dateRange": { "date_from": "-1h" },
    "filterGroup": [
      { "key": "k8s.namespace.name", "operator": "exact", "type": "log_resource_attribute", "value": "payments" }
    ]
  }
}

Get adaptive-interval bucket counts for a filtered log stream. Returns a flat list of {date_from, date_to, count} buckets covering the requested window. Modeled on Elasticsearch's auto_date_histogram — caller specifies a target bucket count, the engine picks the interval.

Use this to find where the volume is concentrated before pulling rows. Cheaper than query-logs, more agent-friendly than logs-sparkline-query (each bucket carries explicit date_from/date_to you can feed straight back as the next call's dateRange to drill in).

When to use this vs other tools

• logs-count — total volume in a window. Scalar.
• logs-count-ranges (this tool) — _when_ in the window the volume sits. Time-bucketed.
• query-logs — pull individual log rows. Most expensive; only call after counts confirm the window is right-sized.

Recursion pattern (the main reason this tool exists)

Use the response to narrow into a sub-range without reasoning about interval width:

1. Call logs-count-ranges with the user's window (e.g. last 24h). 2. Pick the bucket(s) of interest (densest, an obvious spike, an unexpectedly empty stretch). 3. Call logs-count-ranges again with that bucket's date_from and date_to as the next dateRange. 4. Repeat up to ~3–4 levels — stop when buckets are shorter than your precision goal (e.g. 1 minute). 5. Once narrowed, call query-logs for the actual rows.

This is the same pattern Elasticsearch users follow with auto_date_histogram. Keep recursion shallow — every call is cheap individually but they multiply quickly.

Parameters

All parameters must be nested inside a query object.

query.dateRange

Window to bucket. Defaults to the last hour (-1h). Same format as query-logs.

query.targetBuckets

Approximate bucket count. Defaults to 10, max 100. The engine picks the interval adaptively from a fixed list (1/5/10s, 1/2/5/10/15/30/60/120/240/360/720/1440m) to land near this target — actual count may differ slightly. Empty buckets are dropped, so the response can have fewer rows than targetBuckets.

Pick a value based on what you're doing:

• 10 (default) — overview, finding spikes, "is this concentrated or spread out?"
• 20–30 — characterising a known busy window
• 50+ — high-resolution drill-down, only when you know the window is small

query.severityLevels, query.serviceNames, query.searchTerm, query.filterGroup

Same shape as query-logs. Applied before bucketing.

Response

{
  "ranges": [
    { "date_from": "2026-04-26T00:00:00", "date_to": "2026-04-26T02:24:00", "count": 1024 },
    { "date_from": "2026-04-26T02:24:00", "date_to": "2026-04-26T04:48:00", "count": 47 }
  ],
  "interval": "2h"
}

• ranges — buckets ordered by date_from ascending. Empty buckets are omitted — infer gaps by comparing each bucket's date_to to the next bucket's date_from.
• interval — short-form duration of the chosen bucket width (1s / 5m / 1h / 1d). Informational only — for follow-up queries, use the per-bucket date_from/date_to.

Examples

Find when errors spiked over the last day

{
  "query": {
    "dateRange": { "date_from": "-1d" },
    "targetBuckets": 24,
    "serviceNames": ["api-gateway"],
    "severityLevels": ["error", "fatal"]
  }
}

Drill into the densest hour from a previous call

After picking the densest bucket from the response above (say {date_from: "2026-04-26T15:00:00", date_to: "2026-04-26T16:00:00", count: 894}):

{
  "query": {
    "dateRange": {
      "date_from": "2026-04-26T15:00:00",
      "date_to": "2026-04-26T16:00:00"
    },
    "targetBuckets": 12,
    "serviceNames": ["api-gateway"],
    "severityLevels": ["error", "fatal"]
  }
}

Reminders

• Cap recursion at ~3–4 levels. If your bucket width drops below your precision goal (e.g. 1 minute), stop and call query-logs.
• Empty windows return {"ranges": [], "interval": "..."} — that's not an error, it's "I asked, nothing matched."
• Always include serviceNames or a resource attribute filter, just like query-logs. Don't bucket the entire team's log stream.

Return the top-25 services by log volume in the window, each with log_count, error_count, and error_rate, plus a per-service sparkline. Use this as the entry point when triaging which services are worth alerting on — high volume × non-zero error_rate is the natural alert candidate. Far cheaper than walking attribute-values + per-service counts.

Get a time-bucketed sparkline of log volume, broken down by severity or service. Use this to understand log volume patterns before querying individual log entries — it is much cheaper than a full log query.

All parameters must be nested inside a query object.

Parameters

query.dateRange

Date range for the sparkline. Defaults to the last hour (-1h).

• date_from: Start of the range. Accepts ISO 8601 timestamps or relative formats: -1h, -6h, -1d, -7d.
• date_to: End of the range. Same format. Omit or null for "now".

query.serviceNames

Filter by service names.

query.severityLevels

Filter by log severity: trace, debug, info, warn, error, fatal. Omit to include all levels.

query.searchTerm

Full-text search across log bodies.

query.filterGroup

Property filters to narrow results. Same format as query-logs filters.

query.sparklineBreakdownBy

Break down the sparkline by "severity" (default) or "service". Use "service" to see which services are producing the most logs.

Examples

Error volume over the last day

{
  "query": {
    "serviceNames": ["api-gateway"],
    "severityLevels": ["error", "fatal"],
    "dateRange": { "date_from": "-1d" }
  }
}

Log volume by service

{
  "query": {
    "serviceNames": ["api-gateway"],
    "sparklineBreakdownBy": "service",
    "dateRange": { "date_from": "-6h" }
  }
}

Log volume by severity

{
  "query": {
    "serviceNames": ["api-gateway"],
    "sparklineBreakdownBy": "severity",
    "dateRange": { "date_from": "-1d" }
  }
}

Get details of an organization by ID including name, membership level, member count, teams, and projects. If no ID is provided, returns the active organization.

List all organizations the user has access to. Returns org ID, name, slug, and membership level. Use the ID with organization-get for details or switch-organization to change context.

Retrieve a project and its settings. Pass @current as the ID to fetch the caller's active project.

Fetches projects that the user has access to in the current organization.

Get full details of a specific reverse proxy by ID. Returns the domain, CNAME target (the DNS record value the user needs to configure), current provisioning status, and any error or warning messages. Use this to debug why a proxy isn't working or to check DNS verification status.

List all managed reverse proxies configured for the current organization. Returns each proxy's domain, CNAME target, provisioning status, and the maximum number of proxies allowed by the current plan. Use this to check whether a reverse proxy is set up before recommending one.

Get compact details for one Error tracking issue.

Use this after query-error-tracking-issues-list when you have an issueId and need issue status, name/description, first/last seen timestamps, assignee, compact impact counts, top in-app frame, and latest release metadata.

Defaults are intentionally useful: last 7 days, test accounts filtered out, aggregate impact included, and no sparkline unless requested.

Parameters

• issueId: required Error tracking issue UUID.
• dateRange: time range for impact counts and latest-event metadata. Defaults to last 7 days.
• includeSparkline: set true only if a trend/sparkline helps answer the user. When true, volumeResolution defaults to 12 if not provided.
• volumeResolution: number of volume buckets when sparkline data is needed.

Next steps

Use query-error-tracking-issue-events with the same issueId when the user needs concrete event examples, stack traces, browser/OS/URL context, or $session_id values for Session replay.

Fetch sampled $exception events for one Error tracking issue.

Use this when the user asks for concrete examples, stack traces, affected URLs, browser/OS/library context, or Session replay links for a specific issue.

Returns sampled events with plural exception fields ($exception_types, $exception_values), normalized $exception_list, $exception_fingerprint, $exception_issue_id, $session_id, $lib, browser/OS fields, and $current_url.

Parameters

• issueId: required Error tracking issue UUID.
• dateRange: time range for sampled events. Defaults to last 7 days.
• searchQuery: search exception types, values, and current URL.
• filterGroup: advanced flat AND property filters applied to sampled events.
• verbosity: summary (default), stack, or raw. Use raw only when exact untruncated exception payloads are needed.
• onlyAppFrames: defaults to true to reduce vendor-frame noise.
• limit: defaults to 1 and maxes at 20. Keep low unless the user asks for multiple examples.

Session recordings

When $session_id is present and the user asks what happened before the error, call query-session-recordings-list with session_ids to fetch matching recordings. Use multiple $session_id values in one call when available.

List and filter Error tracking issues. Returns compact issue rows with aggregate impact counts (occurrences, users, sessions) and optional volume buckets.

Use this first when the user asks which errors are happening, which errors are most common, or wants to narrow issues by status, release, library, fingerprint, URL, user, person, or properties.

Defaults are intentionally useful: active issues, last 7 days, sorted by occurrences, test accounts filtered out, and compact aggregate counts.

Be minimalist. Only add filters needed to answer the user’s question. Do not add "is set" filters unless the user explicitly asks for them.

Common filters

• status: active, resolved, suppressed, pending_release, archived, or all. Defaults to active.
• searchQuery: free-text search for exception names, values, stack frames, and email text.
• library: exact $lib match, for example posthog-js.
• release: exact release ID, release version, or git commit ID captured in $exception_releases. This intentionally does not match project name, branch, or timestamp fragments.
• fingerprint: exact $exception_fingerprint match.
• url: substring match on $current_url.
• personId: exact PostHog person UUID.
• user: user/email text search.
• filePath: stack-frame file/source text search.
• filterGroup: advanced flat AND property filters. Prefer typed fields above when they fit.

Use dateRange for time, not property filters. Omit date_to for now.

Next steps

• Use query-error-tracking-issue with issueId to inspect one issue.
• Use query-error-tracking-issue-events with issueId to fetch sampled exception events, stack traces, URLs, and $session_id values.
• If the user asks what people were doing before the error, use $session_id values from issue events with query-session-recordings-list and its session_ids parameter.

Run a funnel query to analyze conversion rates through a sequence of steps. Funnel insights help understand user behavior as users navigate through a product. A funnel consists of a sequence of at least two events or actions, where some users progress to the next step while others drop off. Funnels use percentages as the primary aggregation type.

Use 'read-data-schema' to discover available events, actions, and properties for filters and breakdowns.

IMPORTANT: Funnels REQUIRE AT LEAST TWO series (events or actions).

The funnel insights have the following features:

• Various visualization types (steps, time-to-convert, historical trends).
• Filter data and apply exclusion steps (events only, not actions).
• Break down data using a single property.
• Specify conversion windows (default 14 days), step order (strict/ordered/unordered), and attribution settings.
• Aggregate by users, sessions, or specific group types.
• Track first-time conversions with special math aggregations.

Examples of use cases include:

• Conversion rates between steps.
• Drop off steps (which step loses most users).
• Steps with the highest friction and time to convert.
• If product changes are improving their funnel over time.
• Average/median/histogram of time to convert.
• Conversion trends over time (using trends visualization type).
• First-time user conversions (using first_time_for_user math).

CRITICAL: Be minimalist. Only include filters, breakdowns, and settings that are essential to answer the user's specific question. Default settings are usually sufficient unless the user explicitly requests customization.

Data narrowing

Property filters

Use property filters to narrow results. Only include property filters when they are essential to directly answer the user's question. Avoid adding them if the question can be addressed without additional segmentation and always use the minimum set of property filters needed.

IMPORTANT: Do not check if a property is set unless the user explicitly asks for it.

When using a property filter, you should:

• Prioritize properties directly related to the context or objective of the user's query. Avoid using properties for identification like IDs. Instead, prioritize filtering based on general properties like paidCustomer or icp_score.
• Ensure that you find both the property group and name. Property groups should be one of the following: event, person, session, group.
• After selecting a property, validate that the property value accurately reflects the intended criteria.
• Find the suitable operator for type (e.g., contains, is set).
• If the operator requires a value, use the read-data-schema tool to find the property values.
• You set logical operators to combine multiple properties of a single series: AND or OR.

Infer the property groups from the user's request. If your first guess doesn't yield any results, try to adjust the property group.

Supported operators for the String type are:

• equals (exact)
• doesn't equal (is_not)
• contains (icontains)
• doesn't contain (not_icontains)
• matches regex (regex)
• doesn't match regex (not_regex)
• is set
• is not set

Supported operators for the Numeric type are:

• equals (exact)
• doesn't equal (is_not)
• greater than (gt)
• less than (lt)
• is set
• is not set

Supported operators for the DateTime type are:

• equals (is_date_exact)
• doesn't equal (is_not for existence check)
• before (is_date_before)
• after (is_date_after)
• is set
• is not set

Supported operators for the Boolean type are:

• equals
• doesn't equal
• is set
• is not set

All operators take a single value except for equals and doesn't equal which can take one or more values (as an array).

Time period

You should not filter events by time using property filters. Instead, use the dateRange field. If the question doesn't mention time, use last 30 days as a default time period.

Funnel guidelines

Exclusion steps

Users may want to use exclusion events to filter out conversions in which a particular event occurred between specific steps. These events should not be included in the main sequence. You should include start and end indexes (0-based) for each exclusion where the minimum funnelFromStep is 0 (first step) and the maximum funnelToStep is the number of steps minus one. Exclusion events cannot be actions, only events.

IMPORTANT: Exclusion steps filter out conversions where the exclusion event occurred BETWEEN the specified steps. This does NOT exclude users who completed the event before the funnel started or after it ended.

For example, there is a sequence with three steps: sign up (step 0), finish onboarding (step 1), purchase (step 2). If the user wants to exclude all conversions in which users navigated away between sign up and finishing onboarding, the exclusion step will be $pageleave with funnelFromStep: 0 and funnelToStep: 1.

Breakdown

A breakdown is used to segment data by a single property value. They divide all defined funnel series into multiple subseries based on the values of the property. Include a breakdown only when it is essential to directly answer the user's question. You should not add a breakdown if the question can be addressed without additional segmentation.

When using breakdowns, you should:

• Identify the property group and name for a breakdown.
• Provide the property name for a breakdown.
• Validate that the property value accurately reflects the intended criteria.

Examples of using a breakdown:

• page views to sign up funnel by country: you need to find a property such as $geoip_country_code and set it as a breakdown.
• conversion rate of users who have completed onboarding after signing up by an organization: you need to find a property such as organization name and set it as a breakdown.

Combining multiple events into a single step (GroupNode)

Use a GroupNode when the user wants a single funnel step to match any of several events — e.g. "Pageview OR Pageleave counts as one step", or "the user signed up via any of these channels". Different filters per event are fine — put them on the inner nodes. Use separate steps instead when the user wants the events to occur in sequence. Only OR is supported.

Funnel math (first_time_for_user etc.), optionalInFunnel, and step-wide property filters are not supported on a grouped step — filters must live on the inner nodes, and any math / optional handling must use a regular non-grouped step.

Where things live:

• On the group: only name (display label).
• On each inner node: event (or action id), properties, name — all respected normally; per-node properties apply only to that node.

Example — funnel with a grouped step

A 3-step funnel where the middle step matches either $pageview on Safari or $pageleave on Chrome:

{
  "kind": "FunnelsQuery",
  "series": [
    { "kind": "EventsNode", "event": "sign up" },
    {
      "kind": "GroupNode",
      "operator": "OR",
      "name": "Pageview on Safari, Pageleave on Chrome",
      "nodes": [
        {
          "kind": "EventsNode",
          "event": "$pageview",
          "name": "Pageview",
          "properties": [{ "key": "$browser", "operator": "exact", "type": "event", "value": ["Safari"] }]
        },
        {
          "kind": "EventsNode",
          "event": "$pageleave",
          "name": "Pageleave",
          "properties": [{ "key": "$browser", "operator": "exact", "type": "event", "value": ["Chrome"] }]
        }
      ]
    },
    { "kind": "EventsNode", "event": "purchase" }
  ],
  "dateRange": { "date_from": "-30d" }
}

Examples

Conversion from first event ingested to insight saved for organizations over 6 months

{
  "kind": "FunnelsQuery",
  "series": [
    { "kind": "EventsNode", "event": "first team event ingested" },
    { "kind": "EventsNode", "event": "insight saved" }
  ],
  "dateRange": { "date_from": "-6m" },
  "interval": "month",
  "aggregation_group_type_index": 0,
  "funnelsFilter": {
    "funnelOrderType": "ordered",
    "funnelVizType": "trends",
    "funnelWindowInterval": 14,
    "funnelWindowIntervalUnit": "day"
  },
  "filterTestAccounts": true
}

Signup page CTA click rate within one hour, excluding page leaves, broken down by OS

{
  "kind": "FunnelsQuery",
  "series": [
    {
      "kind": "EventsNode",
      "event": "$pageview",
      "properties": [{ "key": "$current_url", "type": "event", "value": "signup", "operator": "icontains" }]
    },
    {
      "kind": "EventsNode",
      "event": "click subscribe button",
      "properties": [{ "key": "$current_url", "type": "event", "value": "signup", "operator": "icontains" }]
    }
  ],
  "dateRange": { "date_from": "-180d" },
  "interval": "week",
  "funnelsFilter": {
    "funnelWindowInterval": 1,
    "funnelWindowIntervalUnit": "hour",
    "funnelOrderType": "ordered",
    "exclusions": [{ "kind": "EventsNode", "event": "$pageleave", "funnelFromStep": 0, "funnelToStep": 1 }]
  },
  "breakdownFilter": { "breakdown_type": "event", "breakdown": "$os" },
  "filterTestAccounts": true
}

Credit card purchase rate from viewing a product with strict ordering (no events in between)

{
  "kind": "FunnelsQuery",
  "series": [
    { "kind": "EventsNode", "event": "view product" },
    {
      "kind": "EventsNode",
      "event": "purchase",
      "properties": [{ "key": "paymentMethod", "type": "event", "value": "credit_card", "operator": "exact" }]
    }
  ],
  "dateRange": { "date_from": "-30d" },
  "funnelsFilter": {
    "funnelOrderType": "strict",
    "funnelWindowInterval": 14,
    "funnelWindowIntervalUnit": "day"
  },
  "filterTestAccounts": true
}

View product to buy button to purchase, using actions and events

{
  "kind": "FunnelsQuery",
  "series": [
    { "kind": "ActionsNode", "id": 8882, "name": "view product" },
    { "kind": "EventsNode", "event": "click buy button" },
    {
      "kind": "ActionsNode",
      "id": 573,
      "name": "purchase",
      "properties": [
        { "key": "shipping_method", "value": "express_delivery", "operator": "icontains", "type": "event" }
      ]
    }
  ],
  "funnelsFilter": { "funnelVizType": "steps" },
  "filterTestAccounts": true
}

Reminders

• You MUST ALWAYS use AT LEAST TWO series (events or actions) in the funnel.
• Ensure that any properties included are directly relevant to the context and objectives of the user's question. Avoid unnecessary or unrelated details.
• Avoid overcomplicating the response with excessive property filters. Focus on the simplest solution.
• The default funnel step order is ordered (events in sequence but with other events allowed in between). Use strict when events should happen consecutively with no events in between. Use unordered when order doesn't matter.
• Exclusion events in funnels only exclude conversions where the event happened between the specified steps, not before or after the funnel.

Run a lifecycle query to categorize users into lifecycle stages based on their activity pattern relative to a single event or action. Lifecycle insights break users into four mutually exclusive groups for each time period: new, returning, resurrecting, and dormant. They're useful for understanding the composition of your active users and diagnosing growth or churn patterns.

Use 'read-data-schema' to discover available events, actions, and properties for filters.

Examples of use cases include:

• What is the composition of my active users over time?
• Are we gaining new users faster than we're losing dormant ones?
• How many users resurrected (came back after being inactive) last week?
• Is the returning user base growing or shrinking?
• How does user engagement change after a product launch?

CRITICAL: Be minimalist. Only include filters and settings that are essential to answer the user's specific question. Default settings are usually sufficient unless the user explicitly requests customization.

Data narrowing

Property filters

Use property filters to narrow results. Only include property filters when they are essential to directly answer the user's question. Avoid adding them if the question can be addressed without additional segmentation and always use the minimum set of property filters needed.

IMPORTANT: Do not check if a property is set unless the user explicitly asks for it.

When using a property filter, you should:

• Prioritize properties directly related to the context or objective of the user's query. Avoid using properties for identification like IDs. Instead, prioritize filtering based on general properties like paidCustomer or icp_score.
• Ensure that you find both the property group and name. Property groups should be one of the following: event, person, session, group.
• After selecting a property, validate that the property value accurately reflects the intended criteria.
• Find the suitable operator for type (e.g., contains, is set).
• If the operator requires a value, use the read-data-schema tool to find the property values.
• You set logical operators to combine multiple properties of a single series: AND or OR.

Infer the property groups from the user's request. If your first guess doesn't yield any results, try to adjust the property group.

Supported operators for the String type are:

• equals (exact)
• doesn't equal (is_not)
• contains (icontains)
• doesn't contain (not_icontains)
• matches regex (regex)
• doesn't match regex (not_regex)
• is set
• is not set

Supported operators for the Numeric type are:

• equals (exact)
• doesn't equal (is_not)
• greater than (gt)
• less than (lt)
• is set
• is not set

Supported operators for the DateTime type are:

• equals (is_date_exact)
• doesn't equal (is_not for existence check)
• before (is_date_before)
• after (is_date_after)
• is set
• is not set

Supported operators for the Boolean type are:

• equals
• doesn't equal
• is set
• is not set

All operators take a single value except for equals and doesn't equal which can take one or more values (as an array).

Time period

You should not filter events by time using property filters. Instead, use the dateRange field. If the question doesn't mention time, use last 30 days as a default time period.

Lifecycle guidelines

Lifecycle insights analyze a single event or action over time. The series array must contain exactly one item. If the user mentions multiple events, pick the most relevant one or clarify.

Lifecycle statuses

Each user is categorized into one of four statuses for each time period:

• New – the user performed the event for the first time ever during this period.
• Returning – the user was active in the previous period and is active again in the current period.
• Resurrecting – the user was inactive for one or more periods and became active again.
• Dormant – the user was active in the previous period but did not perform the event in the current period. Dormant counts are shown as negative values.

Time interval

Specify the time interval using the interval field. Available intervals are: hour, day, week, month. The default is day.

Unless the user has specified otherwise, use the following default interval:

• If the time period is less than two days, use the hour interval.
• If the time period is less than a month, use the day interval.
• If the time period is less than three months, use the week interval.
• Otherwise, use the month interval.

Toggled lifecycles

Use toggledLifecycles in lifecycleFilter to control which lifecycle statuses are displayed. By default, all four statuses are shown. Only set this when the user wants to focus on specific statuses (e.g., only new and dormant users).

Math aggregation

Lifecycle insights do not support math aggregation types. Do not set math on the series node.

Examples

Daily lifecycle of pageviews over the last 30 days

{
  "kind": "LifecycleQuery",
  "series": [{ "kind": "EventsNode", "event": "$pageview" }],
  "dateRange": { "date_from": "-30d" },
  "interval": "day"
}

Weekly lifecycle of sign ups, excluding test accounts

{
  "kind": "LifecycleQuery",
  "series": [{ "kind": "EventsNode", "event": "user signed up" }],
  "dateRange": { "date_from": "-90d" },
  "interval": "week",
  "filterTestAccounts": true
}

Monthly lifecycle of "insight created" showing only new and dormant users

{
  "kind": "LifecycleQuery",
  "series": [{ "kind": "EventsNode", "event": "insight created" }],
  "dateRange": { "date_from": "-12m" },
  "interval": "month",
  "lifecycleFilter": {
    "toggledLifecycles": ["new", "dormant"]
  },
  "filterTestAccounts": true
}

Lifecycle of purchases by mobile users

{
  "kind": "LifecycleQuery",
  "series": [{ "kind": "EventsNode", "event": "purchase completed" }],
  "dateRange": { "date_from": "-30d" },
  "interval": "day",
  "properties": [{ "key": "$os", "operator": "exact", "type": "event", "value": ["iOS", "Android"] }]
}

Reminders

• Lifecycle insights support only one series — do not add multiple events or actions.
• Do not set math on the series node — lifecycle does not support math aggregation.
• Ensure that any properties included are directly relevant to the context and objectives of the user's question. Avoid unnecessary or unrelated details.
• Avoid overcomplicating the response with excessive property filters. Focus on the simplest solution.

Fetch a single LLM trace by its trace ID for deep inspection. Returns the complete trace with all nested events and their full properties — including inputs, outputs, model parameters, costs, and errors. Use after finding a trace via query-llm-traces-list to inspect the complete event tree.

Use cases:

• Inspect the full input/output of each generation in a trace
• Debug a specific error trace found in the list
• Examine the agent's decision-making flow across spans
• Review tool calls and their results within a trace
• Analyze token usage and costs per generation

CRITICAL: This tool requires a traceId. Get the trace ID from query-llm-traces-list results first.

Response shape

The response contains a single trace in JSON format with:

• id — the trace ID
• traceName — name of the trace (if set via SDK)
• createdAt — timestamp of the first event in the trace
• distinctId — the person's distinct ID
• aiSessionId — session ID grouping related traces (e.g., a conversation)
• totalLatency — total latency in seconds
• inputTokens / outputTokens — token counts across all generations
• inputCost / outputCost / totalCost — costs in USD
• inputState / outputState — JSON input/output state from the root $ai_trace event (e.g., conversation messages)
• events — all child events in the trace at every nesting depth (not just direct children). Each event has full properties.

Unlike query-llm-traces-list, this tool does NOT return errorCount, isSupportTrace, or tools — those are summary fields on the list tool only.

Event types and their properties

Each event in events has an event field indicating its type. Key properties vary by type:

• $ai_generation / $ai_embedding — an LLM or embedding API call. Properties include $ai_input (input prompt JSON), $ai_output_choices (output message JSON), $ai_model, $ai_provider, $ai_latency, $ai_input_tokens, $ai_output_tokens, $ai_input_cost_usd, $ai_output_cost_usd, $ai_total_cost_usd, $ai_tools_called, $ai_is_error, $ai_error.
• $ai_span — a unit of work within a trace (e.g., a retrieval step, tool execution). Properties include $ai_input_state, $ai_output_state, $ai_latency, $ai_span_name, $ai_parent_id.
• $ai_metric — a named evaluation metric. Properties include $ai_metric_name, $ai_metric_value.
• $ai_feedback — user-provided feedback. Properties include $ai_feedback_text.

Note: $ai_trace events are NOT included in the events array — their data is surfaced via the trace-level inputState, outputState, and traceName fields.

Tree structure (IDs and parent-child relationships)

Events in a trace form a tree. Each event carries three IDs that define its position:

• $ai_trace_id — present on every event, identifies which trace it belongs to (same as the trace's id)
• $ai_span_id (or $ai_generation_id for generations) — the event's own unique identifier
• $ai_parent_id — points to the parent event's $ai_span_id

To reconstruct the tree:

1. Events where $ai_parent_id equals $ai_trace_id are root-level children of the trace 2. Other events are children of the event whose $ai_span_id matches their $ai_parent_id 3. Group events by $ai_parent_id and walk from root children downward

Generations ($ai_generation) and embeddings ($ai_embedding) are always leaf nodes. Spans ($ai_span) can have children.

Examples

Fetch a trace by ID

{
  "kind": "TraceQuery",
  "traceId": "c9222e05-8708-41b8-98ea-d4a21849e761"
}

Fetch with a date range hint

If the trace is old, provide a date range to help the query find it efficiently:

{
  "kind": "TraceQuery",
  "traceId": "c9222e05-8708-41b8-98ea-d4a21849e761",
  "dateRange": { "date_from": "-30d" }
}

Reminders

• Always get the traceId from query-llm-traces-list results — do not guess or fabricate trace IDs.
• If no date range is provided, the default lookback window is used. For older traces, provide an explicit dateRange.
• The events array contains ALL events in the trace (including deeply nested ones), making this suitable for full tree reconstruction.
• Use query-llm-traces-list first to find traces, then this tool to inspect a specific one.

List LLM traces to inspect AI/LLM usage across your application. Returns traces with their events, latency, token usage, costs, errors, and other metadata. Use this tool for AI observability — debugging slow generations, investigating errors, analyzing token spend, and auditing LLM behavior.

Use 'read-data-schema' to discover available event properties for filtering (e.g. $ai_model, $ai_provider).

Examples of use cases include:

• How much are we spending on LLM tokens per day?
• Which LLM generations are the slowest?
• Are there any traces with errors in the last 24 hours?
• What models are being used and how do their costs compare?
• Show me traces for a specific user to debug their experience.
• Are there any traces with unusually high token usage?

CRITICAL: Be minimalist. Only include filters and settings that are essential to answer the user's specific question. Default settings are usually sufficient unless the user explicitly requests customization.

Data narrowing

Property filters

Use property filters to narrow results. Only include property filters when they are essential to directly answer the user's question. Avoid adding them if the question can be addressed without additional segmentation and always use the minimum set of property filters needed.

IMPORTANT: Do not check if a property is set unless the user explicitly asks for it.

When using a property filter, you should:

• Prioritize properties directly related to the context or objective of the user's query. Common AI properties include $ai_model, $ai_provider, $ai_trace_id, $ai_session_id, $ai_latency, $ai_input_tokens, $ai_output_tokens, $ai_total_cost_usd, $ai_is_error, $ai_http_status, $ai_span_name.
• Note: $ai_is_error and $ai_error are valid filter properties but may not appear via read-data-schema. Use $ai_is_error with operator exact and value ["true"] to find error traces, or use $ai_error with is set to find traces with error messages.
• Ensure that you find both the property group and name. Property groups should be one of the following: event, person, session, group.
• After selecting a property, validate that the property value accurately reflects the intended criteria.
• Find the suitable operator for type (e.g., contains, is set).
• If the operator requires a value, use the read-data-schema tool to find the property values.

Infer the property groups from the user's request. If your first guess doesn't yield any results, try to adjust the property group.

Supported operators for the String type are:

• equals (exact)
• doesn't equal (is_not)
• contains (icontains)
• doesn't contain (not_icontains)
• matches regex (regex)
• doesn't match regex (not_regex)
• is set
• is not set

Supported operators for the Numeric type are:

• equals (exact)
• doesn't equal (is_not)
• greater than (gt)
• less than (lt)
• is set
• is not set

Supported operators for the DateTime type are:

• equals (is_date_exact)
• doesn't equal (is_not for existence check)
• before (is_date_before)
• after (is_date_after)
• is set
• is not set

Supported operators for the Boolean type are:

• equals
• doesn't equal
• is set
• is not set

All operators take a single value except for equals and doesn't equal which can take one or more values (as an array).

Time period

You should not filter events by time using property filters. Instead, use the dateRange field. If the question doesn't mention time, use last 7 days as a default time period.

Traces guidelines

This is a listing tool, not a visualization/insight tool. It returns a paginated list of LLM traces — it does NOT support series, breakdowns, math aggregations, or chart types.

Response shape

Each trace in the results contains:

• id — unique trace ID
• traceName — name of the trace (if set via SDK)
• createdAt — timestamp of the first event in the trace
• distinctId — the person's distinct ID
• aiSessionId — session ID grouping related traces (e.g., a conversation)
• totalLatency — total latency in seconds
• inputTokens / outputTokens — token counts across all generations in the trace
• inputCost / outputCost / totalCost — costs in USD
• inputState / outputState — JSON input/output state of the trace (e.g., conversation messages), from the $ai_trace event
• errorCount — number of errors in the trace
• isSupportTrace — whether the trace was from a support impersonation session
• tools — list of tool names called during the trace
• events — list of direct child events (generations, metrics, feedback). Each event's properties contains the full event data — see "Event types and their properties" below.

Event types and their properties

Each event in events has an event field indicating its type. The key properties vary by type:

• $ai_generation / $ai_embedding — an LLM or embedding API call. Properties include $ai_input (input prompt JSON), $ai_output_choices (output message JSON), $ai_model, $ai_provider, $ai_latency, $ai_input_tokens, $ai_output_tokens, $ai_input_cost_usd, $ai_output_cost_usd, $ai_total_cost_usd, $ai_tools_called, $ai_is_error, $ai_error.
• $ai_span — a unit of work within a trace (e.g., a retrieval step, a tool execution). Properties include $ai_input_state, $ai_output_state, $ai_latency, $ai_span_name, $ai_parent_id.
• $ai_trace — the root trace event. Properties include $ai_input_state (e.g., conversation messages sent), $ai_output_state (e.g., final response), $ai_span_name.
• $ai_metric — a named evaluation metric. Properties include $ai_metric_name, $ai_metric_value.
• $ai_feedback — user-provided feedback. Properties include $ai_feedback_text.

All event types share $ai_trace_id, $ai_span_id, and $ai_parent_id for tree structure (see below).

Tree structure (IDs and parent-child relationships)

Events in a trace form a tree. Each event carries three IDs that define its position:

• $ai_trace_id — present on every event, identifies which trace it belongs to (same as the trace's id)
• $ai_span_id (or $ai_generation_id for generations) — the event's own unique identifier
• $ai_parent_id — points to the parent event's $ai_span_id

To reconstruct the tree:

1. Events where $ai_parent_id equals $ai_trace_id are root-level children of the trace 2. Other events are children of the event whose $ai_span_id matches their $ai_parent_id 3. Group events by $ai_parent_id and walk from root children downward

Generations ($ai_generation) and embeddings ($ai_embedding) are always leaf nodes. Spans ($ai_span) can have children.

Important: This list tool only returns direct children of the trace (events where $ai_parent_id = trace ID) plus all $ai_metric and $ai_feedback events — NOT deeply nested events. For the full event tree with all nested children, use query-llm-trace with the trace's id.

Pagination

Use limit and offset for pagination. The default limit is 100. The response includes a hasMore field indicating whether more results are available.

Filtering

• filterTestAccounts — exclude internal/test users
• filterSupportTraces — exclude support impersonation traces
• personId — filter by a specific person UUID
• groupKey + groupTypeIndex — filter by a specific group
• randomOrder — use random ordering instead of newest-first (useful for representative sampling)

Examples

Recent traces with errors

{
  "kind": "TracesQuery",
  "dateRange": { "date_from": "-7d" },
  "filterTestAccounts": true,
  "properties": [{ "key": "$ai_is_error", "operator": "exact", "type": "event", "value": ["true"] }],
  "limit": 50
}

Traces for a specific model

{
  "kind": "TracesQuery",
  "dateRange": { "date_from": "-7d" },
  "filterTestAccounts": true,
  "properties": [{ "key": "$ai_model", "operator": "exact", "type": "event", "value": ["gpt-4o"] }]
}

Traces for a specific person

{
  "kind": "TracesQuery",
  "dateRange": { "date_from": "-30d" },
  "personId": "01234567-89ab-cdef-0123-456789abcdef",
  "filterTestAccounts": true
}

Random sample of traces (avoids recency bias)

{
  "kind": "TracesQuery",
  "dateRange": { "date_from": "-30d" },
  "filterTestAccounts": true,
  "randomOrder": true,
  "limit": 20
}

Reminders

• Ensure that any properties included are directly relevant to the context and objectives of the user's question. Avoid unnecessary or unrelated details.
• Avoid overcomplicating the response with excessive property filters. Focus on the simplest solution.
• This tool returns raw trace data — it does not aggregate or visualize. For aggregated LLM metrics over time (e.g. total token usage per day), use query-trends with AI events like $ai_generation instead.
• Use filterTestAccounts: true by default to exclude internal users unless the user asks otherwise.
• The default time range is last 7 days. LLM trace data tends to be recent, so shorter ranges are usually appropriate.
• For deep inspection of a single trace (full event tree with all nested children and complete properties), use query-llm-trace with the trace's id.

Query log entries with filtering by severity, service name, date range, search term, and structured attribute filters. Supports cursor-based pagination. The response schema (see the tool's typed output) lists every returned field — prefer severity_text over severity_number / level, and be aware that trace_id and span_id return zero-padded strings rather than null when unset.

Use logs-attributes-list and logs-attribute-values-list to discover available attributes before building filters.

Workflow — follow this order every time

1. Discover services first. Call logs-attribute-values-list with key: "service.name" and attribute_type: "resource" to see available services. 2. Explore resource attributes. Call logs-attributes-list with attribute_type: "resource" to discover resource-level attributes (e.g. k8s.pod.name, k8s.namespace.name). Then call logs-attribute-values-list with attribute_type: "resource" for relevant attributes to validate what data exists. 3. Explore log attributes if needed. Call logs-attributes-list (defaults to log attributes) and logs-attribute-values-list to discover log-level attributes. 4. Size the total volume with logs-count. Call logs-count with the discovered serviceNames and filters. If it exceeds query-logs's max limit of 1000 — or if the user's question is about _when_ something happened — continue to step 5. 5. Find where the volume sits with logs-count-ranges. Call logs-count-ranges to get time-bucketed counts. Each bucket carries explicit date_from/date_to you can pass straight back as the next call's dateRange to drill into a sub-range. Recurse up to 3–4 levels to narrow onto a spike or a specific window. Stop when the bucket width drops below your precision goal (e.g. 1 minute). 6. Only then query logs. Once the count is in range and the window is right-sized, call query-logs with serviceNames and any additional filters.

Many cheap calls (attribute/value queries, counts, count-ranges) beat one expensive query-logs. Prefer thorough exploration over speculative log searches.

CRITICAL: Be minimalist. Only include filters and settings that are essential to answer the user's specific question. Default settings are usually sufficient unless the user explicitly requests customization.

MANDATORY: Never call query-logs without setting serviceNames or at least one log_resource_attribute filter. Unfiltered log queries are too broad, expensive, and noisy. If the user hasn't specified a service, use the workflow above to discover services first, then ask or infer.

All parameters must be nested inside a query object.

Data narrowing

Property filters

Use property filters via the query.filterGroup field to narrow results. Only include property filters when they are essential to directly answer the user's question.

When using a property filter, you should:

• Choose the right type. Log property types are:
• log — filters the log body/message. Use key "message" for this type.
• log_attribute — filters log-level attributes (e.g. "k8s.container.name", "http.method").
• log_resource_attribute — filters resource-level attributes (e.g. k8s labels, deployment info).
• Use logs-attributes-list to discover available attribute keys before building filters.
• Use logs-attribute-values-list to discover valid values for a specific attribute key.
• Find the suitable operator for the value type (see supported operators below).

Important: The logs-attributes-list and logs-attribute-values-list tools default to attribute_type: "log" (log-level attributes). To search resource-level attributes (e.g. k8s.pod.name, k8s.namespace.name), you must explicitly pass attribute_type: "resource". Forgetting this will return log-level attributes when you intended resource-level ones.

Supported operators:

• String: exact, is_not, icontains, not_icontains, regex, not_regex
• Numeric: exact, gt, lt
• Date: is_date_exact, is_date_before, is_date_after
• Existence (no value needed): is_set, is_not_set

The value field accepts a string, number, or array of strings depending on the operator. Omit value for is_set/is_not_set.

Time period

Use the query.dateRange field to control the time window. If the question doesn't mention time, the default is the last hour (-1h). Examples of relative dates: -1h, -6h, -1d, -7d, -30d.

Parameters

All parameters go inside query.

query.severityLevels

Filter by log severity: trace, debug, info, warn, error, fatal. Omit to include all levels.

query.serviceNames

Filter by service names. Use logs-attribute-values-list with key: "service.name" and attribute_type: "resource" to discover available services.

query.searchTerm

Full-text search across log bodies. Use this when the user is looking for specific text in log messages.

query.orderBy

Sort by timestamp: latest (default) or earliest.

query.filterGroup

A list of property filters to narrow results. Each filter specifies key, operator, type (log/log_attribute/log_resource_attribute), and optionally value. See the "Property filters" section above.

query.dateRange

Date range to filter results. Defaults to the last hour (-1h).

• date_from: Start of the range. Accepts ISO 8601 timestamps or relative formats: -1h, -6h, -1d, -7d, -30d.
• date_to: End of the range. Same format. Omit or null for "now".

query.limit

Maximum number of results (1-1000). Defaults to 100.

query.after

Cursor for pagination. Use the nextCursor value from the previous response.

Examples

List recent error logs

{
  "query": {
    "severityLevels": ["error", "fatal"],
    "serviceNames": ["<service>"]
  }
}

Search for a specific log message

{
  "query": {
    "searchTerm": "connection refused",
    "serviceNames": ["<service>"],
    "dateRange": { "date_from": "-6h" }
  }
}

Filter logs from a specific service

{
  "query": {
    "serviceNames": ["api-gateway"],
    "dateRange": { "date_from": "-1d" }
  }
}

Filter by a log attribute

{
  "query": {
    "serviceNames": ["<service>"],
    "filterGroup": [{ "key": "http.status_code", "operator": "exact", "type": "log_attribute", "value": "500" }],
    "dateRange": { "date_from": "-1d" }
  }
}

Combine severity and attribute filters

{
  "query": {
    "severityLevels": ["error"],
    "filterGroup": [
      { "key": "k8s.container.name", "operator": "exact", "type": "log_resource_attribute", "value": "web" }
    ],
    "dateRange": { "date_from": "-12h" }
  }
}

Filter by log body content using property filter

{
  "query": {
    "serviceNames": ["<service>"],
    "filterGroup": [{ "key": "message", "operator": "icontains", "type": "log", "value": "timeout" }]
  }
}

Check if an attribute exists

{
  "query": {
    "serviceNames": ["<service>"],
    "filterGroup": [{ "key": "trace_id", "operator": "is_set", "type": "log_attribute" }]
  }
}

Reminders

• Always set serviceNames or a resource attribute filter. Never run a broad unfiltered log query.
• Limit dateRange to at most -1d (24 hours) unless the user explicitly requests a longer range.
• When using logs-attributes-list or logs-attribute-values-list, remember they default to attribute_type: "log". Pass attribute_type: "resource" to search resource-level attributes.
• Ensure that any property filters are directly relevant to the user's question. Avoid unnecessary filtering.
• Use logs-attributes-list and logs-attribute-values-list to discover attributes before guessing filter keys/values.
• Prefer searchTerm for simple text matching; use filterGroup with type log and key message for regex or exact matching.

Run a paths query to analyze the most common sequences of events or pages that users navigate through. Paths insights visualize user flows as a directed graph, showing how users move between steps and where they drop off.

Use 'read-data-schema' to discover available events, actions, and properties for filters.

Examples of use cases include:

• What do users do after signing up?
• What pages do users visit before making a purchase?
• What are the most common navigation flows on your website?
• Where do users drop off in a particular flow?
• What custom events lead to a conversion?

CRITICAL: Be minimalist. Only include filters and settings that are essential to answer the user's specific question. Default settings are usually sufficient unless the user explicitly requests customization.

Data narrowing

Property filters

Use property filters to narrow results. Only include property filters when they are essential to directly answer the user's question. Avoid adding them if the question can be addressed without additional segmentation and always use the minimum set of property filters needed.

IMPORTANT: Do not check if a property is set unless the user explicitly asks for it.

When using a property filter, you should:

• Prioritize properties directly related to the context or objective of the user's query. Avoid using properties for identification like IDs. Instead, prioritize filtering based on general properties like paidCustomer or icp_score.
• Ensure that you find both the property group and name. Property groups should be one of the following: event, person, session, group.
• After selecting a property, validate that the property value accurately reflects the intended criteria.
• Find the suitable operator for type (e.g., contains, is set).
• If the operator requires a value, use the read-data-schema tool to find the property values.
• You set logical operators to combine multiple properties of a single series: AND or OR.

Infer the property groups from the user's request. If your first guess doesn't yield any results, try to adjust the property group.

Supported operators for the String type are:

• equals (exact)
• doesn't equal (is_not)
• contains (icontains)
• doesn't contain (not_icontains)
• matches regex (regex)
• doesn't match regex (not_regex)
• is set
• is not set

Supported operators for the Numeric type are:

• equals (exact)
• doesn't equal (is_not)
• greater than (gt)
• less than (lt)
• is set
• is not set

Supported operators for the DateTime type are:

• equals (is_date_exact)
• doesn't equal (is_not for existence check)
• before (is_date_before)
• after (is_date_after)
• is set
• is not set

Supported operators for the Boolean type are:

• equals
• doesn't equal
• is set
• is not set

All operators take a single value except for equals and doesn't equal which can take one or more values (as an array).

Time period

You should not filter events by time using property filters. Instead, use the dateRange field. If the question doesn't mention time, use last 30 days as a default time period.

Paths guidelines

Event types

Paths analyze sequences of events. Specify which event types to include using includeEventTypes. If omitted, all events are included without type filtering.

• $pageview - web page views. Path values come from $current_url, with trailing slashes stripped, so they must match your stored URL format. This is often a path like /login, but may also be a full URL like https://example.com/login. Best for analyzing website navigation flows. This is the most common choice.
• $screen - mobile screen views. Path values are screen names (from $screen_name). Use for mobile app navigation analysis.
• custom_event - custom events (any event whose name does not start with $). Path values are event names. Use for analyzing flows of custom-tracked events like button clicks, form submissions, or feature usage.
• hogql - custom HogQL expression. Use with pathsHogQLExpression for advanced path definitions.

You can combine multiple types. For example, include both $pageview and custom_event to see how page views and custom events interleave.

Start and end points

Use startPoint to filter paths that begin at a specific step, or endPoint to filter paths that end at a specific step. The value format depends on the event type:

• For $pageview: use the same URL format as your $current_url values, often paths like /login, /dashboard, /settings, but sometimes full URLs
• For $screen: use screen names
• For custom_event: use event names like user signed up, purchase completed

Path cleaning

Use localPathCleaningFilters to normalize dynamic URLs. Each filter has a regex pattern (ClickHouse regex syntax) and an alias replacement. Filters are applied in sequence using replaceRegexpAll(path, regex, alias). For example, to normalize product URLs: { "regex": "\\/product\\/\\d+", "alias": "/product/:id" }.

Use pathGroupings for simpler glob-like grouping of paths into single nodes. Use * as a wildcard — the patterns are auto-escaped so only * has special meaning. For example, /product/* groups all product sub-pages into one node.

Exclusions

Use excludeEvents to remove specific path items that clutter the visualization. The values must match path item values, not event types: for $pageview paths these must match your stored $current_url format (e.g., /health-check or https://example.com/health-check), for custom_event paths these are event names (e.g., heartbeat). To control which event types are included, use includeEventTypes instead.

Examples

What pages do users visit after the homepage?

{
  "kind": "PathsQuery",
  "pathsFilter": {
    "includeEventTypes": ["$pageview"],
    "startPoint": "/",
    "stepLimit": 5
  },
  "dateRange": { "date_from": "-30d" },
  "filterTestAccounts": true
}

What do users do after signing up?

{
  "kind": "PathsQuery",
  "pathsFilter": {
    "includeEventTypes": ["custom_event"],
    "startPoint": "user signed up",
    "stepLimit": 5
  },
  "dateRange": { "date_from": "-30d" },
  "filterTestAccounts": true
}

Navigation paths excluding noisy URLs

{
  "kind": "PathsQuery",
  "pathsFilter": {
    "includeEventTypes": ["$pageview"],
    "excludeEvents": ["/health-check", "/ping"],
    "stepLimit": 5,
    "edgeLimit": 30
  },
  "dateRange": { "date_from": "-14d" },
  "filterTestAccounts": true
}

Custom event paths excluding noisy events

{
  "kind": "PathsQuery",
  "pathsFilter": {
    "includeEventTypes": ["custom_event"],
    "excludeEvents": ["heartbeat"],
    "stepLimit": 5
  },
  "dateRange": { "date_from": "-14d" },
  "filterTestAccounts": true
}

Paths with URL cleaning for dynamic segments

{
  "kind": "PathsQuery",
  "pathsFilter": {
    "includeEventTypes": ["$pageview"],
    "stepLimit": 5,
    "localPathCleaningFilters": [
      { "regex": "\\/user\\/\\d+", "alias": "/user/:id" },
      { "regex": "\\/project\\/[a-f0-9-]+", "alias": "/project/:id" }
    ]
  },
  "dateRange": { "date_from": "-30d" },
  "filterTestAccounts": true
}

What paths lead to the pricing page for mobile users?

{
  "kind": "PathsQuery",
  "pathsFilter": {
    "includeEventTypes": ["$pageview"],
    "endPoint": "/pricing",
    "stepLimit": 5
  },
  "properties": [{ "key": "$os", "operator": "exact", "type": "event", "value": ["iOS", "Android"] }],
  "dateRange": { "date_from": "-30d" },
  "filterTestAccounts": true
}

Reminders

• Ensure that any properties included are directly relevant to the context and objectives of the user's question. Avoid unnecessary or unrelated details.
• Avoid overcomplicating the response with excessive property filters. Focus on the simplest solution.
• Always specify includeEventTypes to scope the analysis to relevant event types. If omitted, all events are included which may produce noisy results.
• Use $pageview as the default event type for web navigation questions.
• Path cleaning filters (localPathCleaningFilters) use ClickHouse regex and are only needed when dynamic URL segments would fragment the visualization. Path groupings (pathGroupings) use glob-like patterns with * wildcards for simpler cases.
• Paths group events into sessions with a 30-minute inactivity threshold — events more than 30 minutes apart start a new path session.

Run a retention query to analyze how many users return over time after performing an initial action. Retention insights show you how many users return during subsequent periods. They're useful for understanding user engagement and stickiness.

Use 'read-data-schema' to discover available events, actions, and properties for filters.

Examples of use cases include:

• Are new sign ups coming back to use your product after trying it?
• Have recent changes improved retention?
• How many users come back and perform an action after their first visit.
• How many users come back to perform action X after performing action Y.
• How often users return to use a specific feature.

CRITICAL: Be minimalist. Only include filters and settings that are essential to answer the user's specific question. Default settings are usually sufficient unless the user explicitly requests customization.

Data narrowing

Property filters

Use property filters to narrow results. Only include property filters when they are essential to directly answer the user's question. Avoid adding them if the question can be addressed without additional segmentation and always use the minimum set of property filters needed.

IMPORTANT: Do not check if a property is set unless the user explicitly asks for it.

When using a property filter, you should:

• Prioritize properties directly related to the context or objective of the user's query. Avoid using properties for identification like IDs. Instead, prioritize filtering based on general properties like paidCustomer or icp_score.
• Ensure that you find both the property group and name. Property groups should be one of the following: event, person, session, group.
• After selecting a property, validate that the property value accurately reflects the intended criteria.
• Find the suitable operator for type (e.g., contains, is set).
• If the operator requires a value, use the read-data-schema tool to find the property values.
• You set logical operators to combine multiple properties of a single series: AND or OR.

Infer the property groups from the user's request. If your first guess doesn't yield any results, try to adjust the property group.

Supported operators for the String type are:

• equals (exact)
• doesn't equal (is_not)
• contains (icontains)
• doesn't contain (not_icontains)
• matches regex (regex)
• doesn't match regex (not_regex)
• is set
• is not set

Supported operators for the Numeric type are:

• equals (exact)
• doesn't equal (is_not)
• greater than (gt)
• less than (lt)
• is set
• is not set

Supported operators for the DateTime type are:

• equals (is_date_exact)
• doesn't equal (is_not for existence check)
• before (is_date_before)
• after (is_date_after)
• is set
• is not set

Supported operators for the Boolean type are:

• equals
• doesn't equal
• is set
• is not set

All operators take a single value except for equals and doesn't equal which can take one or more values (as an array).

Time period

You should not filter events by time using property filters. Instead, use the dateRange field. If the question doesn't mention time, use last 30 days as a default time period.

Retention guidelines

Retention insights always require two entities:

• The activation event (targetEntity) – determines if the user is a part of a cohort (when they "start").
• The retention event (returningEntity) – determines whether a user has been retained (when they "return").

For activation and retention events, use the $pageview event by default or the equivalent for mobile apps $screen. Avoid infrequent or inconsistent events like signed in unless asked explicitly, as they skew the data.

The activation and retention events can be the same (e.g., both $pageview to see if users who viewed pages come back to view pages again) or different (e.g., activation is signed up and retention is completed purchase to see if sign-ups convert to purchases over time).

Examples

Weekly retention of users who created an insight

{
  "kind": "RetentionQuery",
  "retentionFilter": {
    "period": "Week",
    "totalIntervals": 9,
    "targetEntity": { "id": "insight created", "name": "insight created", "type": "events" },
    "returningEntity": { "id": "insight created", "name": "insight created", "type": "events" },
    "retentionType": "retention_first_time",
    "retentionReference": "total",
    "cumulative": false
  },
  "filterTestAccounts": true
}

Do users who sign up come back to view pages?

{
  "kind": "RetentionQuery",
  "retentionFilter": {
    "period": "Week",
    "totalIntervals": 8,
    "targetEntity": { "id": "user signed up", "name": "user signed up", "type": "events" },
    "returningEntity": { "id": "$pageview", "name": "$pageview", "type": "events" },
    "retentionType": "retention_first_time",
    "retentionReference": "total",
    "cumulative": false
  },
  "dateRange": { "date_from": "-60d" },
  "filterTestAccounts": true
}

Daily retention of pageviews for mobile users only

{
  "kind": "RetentionQuery",
  "retentionFilter": {
    "period": "Day",
    "totalIntervals": 14,
    "targetEntity": { "id": "$pageview", "name": "$pageview", "type": "events" },
    "returningEntity": { "id": "$pageview", "name": "$pageview", "type": "events" },
    "retentionType": "retention_first_time",
    "retentionReference": "total",
    "cumulative": false
  },
  "properties": [{ "key": "$os", "operator": "exact", "type": "event", "value": ["iOS", "Android"] }],
  "dateRange": { "date_from": "-30d" },
  "filterTestAccounts": true
}

Reminders

• Ensure that any properties included are directly relevant to the context and objectives of the user's question. Avoid unnecessary or unrelated details.
• Avoid overcomplicating the response with excessive property filters. Focus on the simplest solution.

Run a stickiness query to measure how many intervals (e.g. days) within a date range users performed an event. Stickiness insights show user engagement intensity — the X-axis shows the number of intervals (1, 2, 3, ...) and the Y-axis shows how many users performed the event on exactly that many intervals. They're useful for understanding how deeply users engage with a feature.

Use 'read-data-schema' to discover available events, actions, and properties for filters.

Examples of use cases include:

• How many days per week do users use a feature?
• What percentage of users are power users (using the product every day)?
• How engaged are users with a specific feature over the past month?
• Compare stickiness of different features to find the most engaging one.
• Has a product change improved user engagement frequency?

CRITICAL: Be minimalist. Only include filters and settings that are essential to answer the user's specific question. Default settings are usually sufficient unless the user explicitly requests customization.

Data narrowing

Property filters

Use property filters to narrow results. Only include property filters when they are essential to directly answer the user's question. Avoid adding them if the question can be addressed without additional segmentation and always use the minimum set of property filters needed.

IMPORTANT: Do not check if a property is set unless the user explicitly asks for it.

When using a property filter, you should:

• Prioritize properties directly related to the context or objective of the user's query. Avoid using properties for identification like IDs. Instead, prioritize filtering based on general properties like paidCustomer or icp_score.
• Ensure that you find both the property group and name. Property groups should be one of the following: event, person, session, group.
• After selecting a property, validate that the property value accurately reflects the intended criteria.
• Find the suitable operator for type (e.g., contains, is set).
• If the operator requires a value, use the read-data-schema tool to find the property values.
• You set logical operators to combine multiple properties of a single series: AND or OR.

Infer the property groups from the user's request. If your first guess doesn't yield any results, try to adjust the property group.

Supported operators for the String type are:

• equals (exact)
• doesn't equal (is_not)
• contains (icontains)
• doesn't contain (not_icontains)
• matches regex (regex)
• doesn't match regex (not_regex)
• is set
• is not set

Supported operators for the Numeric type are:

• equals (exact)
• doesn't equal (is_not)
• greater than (gt)
• less than (lt)
• is set
• is not set

Supported operators for the DateTime type are:

• equals (is_date_exact)
• doesn't equal (is_not for existence check)
• before (is_date_before)
• after (is_date_after)
• is set
• is not set

Supported operators for the Boolean type are:

• equals
• doesn't equal
• is set
• is not set

All operators take a single value except for equals and doesn't equal which can take one or more values (as an array).

Time period

You should not filter events by time using property filters. Instead, use the dateRange field. If the question doesn't mention time, use last 30 days as a default time period.

Stickiness guidelines

Stickiness insights measure engagement intensity — how many intervals (days, weeks, etc.) within a date range each user performed an event. Unlike trends which show event counts over time, stickiness shows the distribution of user engagement frequency.

Key concepts:

• The interval field determines what counts as one period. With day interval over a 30-day range, the chart shows how many users performed the event on 1 day, 2 days, 3 days, etc., up to 30 days.
• When math is omitted on a series, stickiness counts unique persons by default.
• Multiple series can be included to compare stickiness of different events side by side.
• Stickiness does NOT support breakdowns.

Aggregation

The default aggregation for stickiness is unique persons. You can change how users are identified using the math field on each series:

• dau or omit math — count unique persons (default behavior; both resolve to person_id aggregation)
• unique_group — count unique groups (requires math_group_type_index to be set to the group type index from the group mapping)
• hogql — custom HogQL expression (requires math_hogql to be set to a valid HogQL aggregation expression, e.g. count(distinct properties.$session_id))

Stickiness criteria

Use stickinessFilter.stickinessCriteria to filter which intervals count based on event frequency within each interval. This applies a HAVING clause to the inner aggregation.

• operator — one of gte (greater than or equal), lte (less than or equal), exact (exactly equal)
• value — the threshold count

For example, to only count intervals where the user performed the event at least 3 times, set stickinessCriteria: { "operator": "gte", "value": 3 }.

Cumulative mode

Use stickinessFilter.computedAs to change how stickiness is computed:

• non_cumulative (default) — each bar shows users active on exactly N intervals
• cumulative — each bar shows users active on N or more intervals

Time interval

Specify the time interval using the interval field. Available intervals are: hour, day, week, month. Unless the user has specified otherwise, use day as the default interval.

Use intervalCount to group multiple base intervals into a single period. For example, interval: "day" with intervalCount: 7 groups by 7-day periods. Defaults to 1.

Compare

Use compareFilter with compare: true to show the current and previous period side by side.

Examples

How many days per week do users use pageview?

{
  "kind": "StickinessQuery",
  "series": [{ "kind": "EventsNode", "event": "$pageview" }],
  "dateRange": { "date_from": "-30d" },
  "interval": "day",
  "filterTestAccounts": true
}

Compare stickiness of two features

{
  "kind": "StickinessQuery",
  "series": [
    { "kind": "EventsNode", "event": "insight created" },
    { "kind": "EventsNode", "event": "dashboard viewed" }
  ],
  "dateRange": { "date_from": "-30d" },
  "interval": "day",
  "filterTestAccounts": true
}

Weekly stickiness for paid users, compared to previous period

{
  "kind": "StickinessQuery",
  "series": [{ "kind": "EventsNode", "event": "$pageview" }],
  "dateRange": { "date_from": "-90d" },
  "interval": "week",
  "properties": [{ "key": "paidCustomer", "operator": "exact", "type": "person", "value": ["true"] }],
  "compareFilter": { "compare": true },
  "filterTestAccounts": true
}

Stickiness with criteria: only count days with 3+ events

{
  "kind": "StickinessQuery",
  "series": [{ "kind": "EventsNode", "event": "$pageview" }],
  "dateRange": { "date_from": "-30d" },
  "interval": "day",
  "filterTestAccounts": true,
  "stickinessFilter": {
    "stickinessCriteria": { "operator": "gte", "value": 3 }
  }
}

Cumulative stickiness: users active on N or more days

{
  "kind": "StickinessQuery",
  "series": [{ "kind": "EventsNode", "event": "feature used" }],
  "dateRange": { "date_from": "-30d" },
  "interval": "day",
  "filterTestAccounts": true,
  "stickinessFilter": {
    "computedAs": "cumulative"
  }
}

Organization-level stickiness for a feature

{
  "kind": "StickinessQuery",
  "series": [
    {
      "kind": "EventsNode",
      "event": "feature used",
      "math": "unique_group",
      "math_group_type_index": 0
    }
  ],
  "dateRange": { "date_from": "-30d" },
  "interval": "day",
  "filterTestAccounts": true,
  "stickinessFilter": { "display": "ActionsBar" }
}

Reminders

• Ensure that any properties included are directly relevant to the context and objectives of the user's question. Avoid unnecessary or unrelated details.
• Avoid overcomplicating the response with excessive property filters. Focus on the simplest solution.
• Stickiness does NOT support breakdowns — do not include a breakdownFilter.
• When using group aggregations (unique groups), always set math_group_type_index to the appropriate group type index from the group mapping.
• The default interval is day and the default math is unique persons — omit these unless the user asks for something different.

Run a trends query to analyze metrics over time. Trends insights visualize events over time using time series. They're useful for finding patterns in historical data.

Use 'read-data-schema' to discover available events, actions, and properties for filters and breakdowns.

The trends insights have the following features:

• The insight can show multiple trends in one request.
• Custom formulas can calculate derived metrics, like A/B*100 to calculate a ratio.
• Filter and break down data using multiple properties.
• Compare with the previous period and sample data.
• Apply various aggregation types, like sum, average, etc., and chart types.

Examples of use cases include:

• How the product's most important metrics change over time.
• Long-term patterns, or cycles in product's usage.
• The usage of different features side-by-side.
• How the properties of events vary using aggregation (sum, average, etc).
• Users can also visualize the same data points in a variety of ways.

CRITICAL: Be minimalist. Only include filters, breakdowns, and settings that are essential to answer the user's specific question. Default settings are usually sufficient unless the user explicitly requests customization.

Data narrowing

Property filters

Use property filters to narrow results. Only include property filters when they are essential to directly answer the user's question. Avoid adding them if the question can be addressed without additional segmentation and always use the minimum set of property filters needed.

IMPORTANT: Do not check if a property is set unless the user explicitly asks for it.

When using a property filter, you should:

• Prioritize properties directly related to the context or objective of the user's query. Avoid using properties for identification like IDs. Instead, prioritize filtering based on general properties like paidCustomer or icp_score.
• Ensure that you find both the property group and name. Property groups should be one of the following: event, person, session, group.
• After selecting a property, validate that the property value accurately reflects the intended criteria.
• Find the suitable operator for type (e.g., contains, is set).
• If the operator requires a value, use the read-data-schema tool to find the property values.
• You set logical operators to combine multiple properties of a single series: AND or OR.

Infer the property groups from the user's request. If your first guess doesn't yield any results, try to adjust the property group.

Supported operators for the String type are:

• equals (exact)
• doesn't equal (is_not)
• contains (icontains)
• doesn't contain (not_icontains)
• matches regex (regex)
• doesn't match regex (not_regex)
• is set
• is not set

Supported operators for the Numeric type are:

• equals (exact)
• doesn't equal (is_not)
• greater than (gt)
• less than (lt)
• is set
• is not set

Supported operators for the DateTime type are:

• equals (is_date_exact)
• doesn't equal (is_not for existence check)
• before (is_date_before)
• after (is_date_after)
• is set
• is not set

Supported operators for the Boolean type are:

• equals
• doesn't equal
• is set
• is not set

All operators take a single value except for equals and doesn't equal which can take one or more values (as an array).

Time period

You should not filter events by time using property filters. Instead, use the dateRange field. If the question doesn't mention time, use last 30 days as a default time period.

Trends guidelines

Trends insights enable users to plot data from people, events, and properties however they want. They're useful for finding patterns in data, as well as monitoring product usage. Users can use multiple independent series in a single query to see trends. They can also use a formula to calculate a metric. Each series has its own set of property filters. Trends insights do not require breakdowns or filters by default.

Aggregation

Determine the math aggregation the user is asking for, such as totals, averages, ratios, or custom formulas. If not specified, choose a reasonable default based on the event type (e.g., total count). By default, the total count should be used. You can aggregate data by events, event's property values, groups, or users. If you're aggregating by users or groups, there's no need to check for their existence.

Available math aggregation types for the event count are:

• total count
• average
• minimum
• maximum
• median
• 90th percentile
• 95th percentile
• 99th percentile
• unique users
• unique sessions
• weekly active users
• daily active users
• first time for a user
• unique groups (requires math_group_type_index to be set to the group type index from the group mapping)

Available math aggregation types for event's property values are:

• average
• sum
• minimum
• maximum
• median
• 90th percentile
• 95th percentile
• 99th percentile

Available math aggregation types counting number of events completed per user (intensity of usage) are:

• average
• minimum
• maximum
• median
• 90th percentile
• 95th percentile
• 99th percentile

Examples of using aggregation types:

• unique users to find how many distinct users have logged the event per a day.
• average by the $session_duration property to find out what was the average session duration of an event.
• 99th percentile by users to find out what was the 99th percentile of the event count by users.

Combining multiple events into a single series (GroupNode)

Use a GroupNode when the user says "X OR Y" (or "any of these events") and wants one line / one number as the result. Different filters per event are fine — put them on the inner nodes. Use separate top-level series instead when the user wants the events compared side by side. Only OR is supported.

Where things live:

• On the group: math / math_property / math_property_type / math_multiplier / math_group_type_index / math_hogql, plus name. The engine reads aggregation from here.
• On each inner node: event (or action id), properties, name — all respected normally; properties applies only to that node. Mirror the group's math* values on each inner node for UI round-trip, but they're ignored at execution time.

Example — different filter per event

"Pageviews on Safari OR pageleaves on Chrome, as one line." Each inner node carries its own properties; the group ORs them and aggregates as one series.

{
  "kind": "TrendsQuery",
  "series": [
    {
      "kind": "GroupNode",
      "operator": "OR",
      "name": "Pageviews on Safari, Pageleaves on Chrome",
      "math": "total",
      "nodes": [
        {
          "kind": "EventsNode",
          "event": "$pageview",
          "name": "Pageview",
          "math": "total",
          "properties": [{ "key": "$browser", "operator": "exact", "type": "event", "value": ["Safari"] }]
        },
        {
          "kind": "EventsNode",
          "event": "$pageleave",
          "name": "Pageleave",
          "math": "total",
          "properties": [{ "key": "$browser", "operator": "exact", "type": "event", "value": ["Chrome"] }]
        }
      ]
    }
  ],
  "dateRange": { "date_from": "-30d" },
  "interval": "day"
}

Math formulas

If the math aggregation is more complex or not listed above, use custom formulas to perform mathematical operations like calculating percentages or metrics. If you use a formula, you should use the following syntax: A/B, where A and B are the names of the series. You can combine math aggregations and formulas.

When using a formula, you should:

• Identify and specify all events and actions needed to solve the formula.
• Carefully review the list of available events and actions to find appropriate entities for each part of the formula.
• Ensure that you find events and actions corresponding to both the numerator and denominator in ratio calculations.

Examples of using math formulas:

• If you want to calculate the percentage of users who have completed onboarding, you need to find and use events or actions similar to $identify and onboarding complete, so the formula will be A / B * 100, where A is onboarding complete (unique users) and B is $identify (unique users).
• To calculate conversion rate: A / B * 100 where A is conversions and B is total events.
• To calculate average value: A / B where A is sum of property and B is count.

Time interval

Specify the time interval (group by time) using the interval field. Available intervals are: hour, day, week, month. Unless the user has specified otherwise, use the following default interval:

• If the time period is less than two days, use the hour interval.
• If the time period is less than a month, use the day interval.
• If the time period is less than three months, use the week interval.
• Otherwise, use the month interval.

Breakdowns

Breakdowns are used to segment data by property values of maximum three properties. They divide all defined trends series into multiple subseries based on the values of the property. Include breakdowns only when they are essential to directly answer the user's question. You should not add breakdowns if the question can be addressed without additional segmentation. Always use the minimum set of breakdowns needed.

When using breakdowns, you should:

• Identify the property group and name for each breakdown.
• Provide the property name for each breakdown.
• Validate that the property value accurately reflects the intended criteria.

Examples of using breakdowns:

• page views trend by country: you need to find a property such as $geoip_country_code and set it as a breakdown.
• number of users who have completed onboarding by an organization: you need to find a property such as organization name and set it as a breakdown.

Examples

How many users signed up?

{
  "kind": "TrendsQuery",
  "series": [{ "kind": "EventsNode", "event": "user signed up", "math": "total" }],
  "dateRange": { "date_from": "-30d" },
  "interval": "month",
  "trendsFilter": { "display": "BoldNumber" }
}

Page views by referring domain for the last month

{
  "kind": "TrendsQuery",
  "series": [{ "kind": "EventsNode", "event": "$pageview", "math": "total" }],
  "dateRange": { "date_from": "-30d" },
  "interval": "day",
  "breakdownFilter": {
    "breakdowns": [{ "property": "$referring_domain", "type": "event" }]
  }
}

DAU to MAU ratio for users from the US, compared to the previous period

{
  "kind": "TrendsQuery",
  "series": [
    { "kind": "EventsNode", "event": "$pageview", "math": "dau" },
    { "kind": "EventsNode", "event": "$pageview", "math": "monthly_active" }
  ],
  "dateRange": { "date_from": "-7d" },
  "interval": "day",
  "properties": {
    "type": "AND",
    "values": [
      {
        "type": "AND",
        "values": [{ "key": "$geoip_country_name", "operator": "exact", "type": "event", "value": ["United States"] }]
      }
    ]
  },
  "compareFilter": { "compare": true },
  "trendsFilter": { "display": "ActionsLineGraph", "formula": "A/B", "aggregationAxisFormat": "percentage_scaled" }
}

Unique users and first-time users for "insight created" over the last 12 months

{
  "kind": "TrendsQuery",
  "series": [
    { "kind": "EventsNode", "event": "insight created", "math": "dau" },
    { "kind": "EventsNode", "event": "insight created", "math": "first_time_for_user" }
  ],
  "dateRange": { "date_from": "-12m" },
  "interval": "month",
  "filterTestAccounts": true,
  "trendsFilter": { "display": "ActionsLineGraph" }
}

P99, P95, and median of a "refreshAge" property on "viewed dashboard" events

{
  "kind": "TrendsQuery",
  "series": [
    { "kind": "EventsNode", "event": "viewed dashboard", "math": "p99", "math_property": "refreshAge" },
    { "kind": "EventsNode", "event": "viewed dashboard", "math": "p95", "math_property": "refreshAge" },
    { "kind": "EventsNode", "event": "viewed dashboard", "math": "median", "math_property": "refreshAge" }
  ],
  "dateRange": { "date_from": "yStart" },
  "interval": "month",
  "filterTestAccounts": true,
  "trendsFilter": { "display": "ActionsLineGraph", "aggregationAxisFormat": "duration" }
}

Organizations that signed up from Google in the last 30 days (group aggregation)

{
  "kind": "TrendsQuery",
  "series": [
    {
      "kind": "EventsNode",
      "event": "user signed up",
      "math": "unique_group",
      "math_group_type_index": 0,
      "properties": [{ "key": "is_organization_first_user", "operator": "exact", "type": "person", "value": ["true"] }]
    }
  ],
  "dateRange": { "date_from": "-30d" },
  "interval": "day",
  "properties": {
    "type": "AND",
    "values": [
      {
        "type": "OR",
        "values": [{ "key": "$initial_utm_source", "operator": "exact", "type": "person", "value": ["google"] }]
      }
    ]
  },
  "trendsFilter": { "display": "ActionsLineGraph" }
}

Reminders

• Ensure that any properties included are directly relevant to the context and objectives of the user's question. Avoid unnecessary or unrelated details.
• Avoid overcomplicating the response with excessive property filters. Focus on the simplest solution.
• When using group aggregations (unique groups), always set math_group_type_index to the appropriate group type index from the group mapping.
• Visualization settings (display type, axis format, etc.) should only be specified when explicitly requested or when they significantly improve the answer.

Use this tool to explore the user's data schema. The user implements PostHog SDKs to collect events, properties, and property values. They are used by users to create insights with visualizations, SQL queries, watch session recordings, filter data, target particular users or groups by traits or behavior, etc. Each event, action, and entity has its own data schema. You must verify that specific combinations exist before using it anywhere else. Events or properties starting from "$" are system properties automatically captured by SDKs. Do not rely on your training data or PostHog defaults for events or properties. Always use this tool to confirm what actually exists in the user's project before referencing any event, property, or property value.

Use this tool to retrieve the core data warehouse schemas for PostHog tables (events, groups, persons, sessions) and the available data warehouse tables, views, and system tables. Use this to understand the data model before writing HogQL queries.

Get details of a specific role including its name, creation date, and creator.

List all members assigned to a specific role. Shows who has which role in the organization.

List all roles defined in the organization. Roles group members and can be used in approval policies and access control rules.

Schedule a future change to a feature flag. Supported operations: 'update_status' (enable/disable), 'add_release_condition', and 'update_variants'. Provide the flag ID as record_id, model_name as "FeatureFlag", a payload with the operation and value, and a scheduled_at datetime.

Delete a scheduled change by ID. This permanently removes the scheduled change and it will not be executed.

Get a single scheduled change by ID. Returns the full details including the payload, schedule timing, execution status, and any failure reason.

List scheduled changes in the current project. Filter by model_name=FeatureFlag and record_id to see schedules for a specific flag. Returns pending, executed, and failed schedules with their payloads and timing. Use this to check what changes are queued for a feature flag before modifying it.

Update a pending scheduled change by ID. You can modify the payload, scheduled_at time, or recurrence settings. Cannot change the target record (record_id) or model type (model_name).

Returns a pre-digested health report for the PostHog SDKs this project is using. Covers which SDKs are current vs outdated (smart-semver rules with grace periods and traffic-percentage thresholds), per-version breakdowns, and a human-readable reason for each assessment. Use when the user asks about PostHog SDK versions, outdated SDKs, SDK health, version upgrade recommendations, or why events may not be captured due to SDK issues.

Creates a new survey in the project. Use this for both in-app surveys and hosted forms. Prefer draft creation by default and do not set start_date unless the user explicitly asks to launch immediately. For in-app surveys, popover is the default unless the user asks for widget or api. For hosted forms, use external_survey. Keep surveys short unless the user asks for a longer flow.

Delete a survey by ID (soft delete - marks as archived).

Get a specific survey by ID. Returns the survey configuration including questions, targeting, and scheduling details.

Get response statistics for a specific survey. Includes detailed event counts (shown, dismissed, sent), unique respondents, conversion rates, and timing data. Supports optional date filtering.

Update an existing survey by ID. Omitted top-level fields are preserved, but nested objects and arrays you provide may replace existing values. Before changing questions, conditions, appearance, targeting, translations, or hosted-form content, retrieve the survey first and preserve fields that should remain. Do not send null to clear a field unless the user explicitly asked to remove it.

Get all surveys in the project with optional filtering. Can filter by search term or use pagination.