querying-posthog-data

Querying data in PostHog

The guidelines contain the same instructions as posthog:execute-sql. If you've already read posthog:execute-sql, you don't need to read them again.

When to use this skill

Finding a specific PostHog entity

When the user wants to find a specific entity created in PostHog (insights, dashboards, cohorts, feature flags, experiments, surveys, hog flows, data warehouse items, etc.), or when a list/search tool returns too many results to narrow down:

1. Read the appropriate schema reference under Data Schema to understand the entity's table and columns.
2. Use posthog:execute-sql to query the system table and find the matching entity (typically returning its ID).
3. Use the dedicated read tool for that entity type (e.g. posthog:insight-get, posthog:dashboard-get) to retrieve the full entity by ID.

Don't try to reconstruct the entity from SQL — execute-sql is for discovery, the read tool is for retrieval.

Querying analytics data

When the user wants analytics data (trends, funnels, retention, paths, sessions, LLM traces, web analytics, errors, logs, etc.) and the existing insight schemas don't fit the request:

1. Look for a matching example under Analytics Query Examples. The list is not exhaustive — there may not be an example for every scenario. If one is a close fit (same domain, similar aggregation), read it; otherwise skip this step.
2. Adapt the example query (if one was found) to the user's request and run it via posthog:execute-sql. If no example fit, compose the query from scratch using the Data Schema and HogQL References.

Answering a headline business or telemetry measure (semantic layer)

When the user asks for a governed business or telemetry measure (MRR, activation rate, billable usage, active organizations, failure rates, ...), or asks how such a measure is defined ("what is our definition of an active org?"), check the data catalog's semantic layer before deriving it from raw data or calling a typed domain tool — the project may have a canonical, human-approved definition to reuse instead of guessing.