--- name: kunanonj/cursor-plugin-posthog-querying-posthog-data source: https://app.decimal.ai/s/kunanonj-cursor-plugin-posthog-querying-posthog-data@1/SKILL.md source_sha256: f735749f66ef --- # Querying data in PostHog The [guidelines](./references/guidelines.md) 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. ## Data Schema Schema reference for PostHog's core system models, organized by domain: - [Activity logs](./references/models-activity-logs.md) - [Actions](./references/models-actions.md) - [Alerts](./references/models-alerts.md) - [Annotations](./references/models-annotations.md) - [APM / tracing (`posthog.trace_spans`)](./references/models-apm-spans.md) - [Batch exports](./references/models-batch-exports.md) - [Early Access Features](./references/models-early-access-features.md) - [Cohorts & Persons](./references/models-cohorts.md) - [Dashboards, Tiles & Insights](./references/models-dashboards-insights.md) - [Data Warehouse](./references/models-data-warehouse.md) - [Data Modeling Endpoints](./references/models-endpoints.md) - [Error Tracking](./references/models-error-tracking.md) - [Flags & Experiments](./references/models-flags-experiments.md) - [Heatmaps (`heatmaps` data + `system.heatmaps_saved`)](./references/models-heatmaps.md) - [Hog Flows](./references/models-hog-flows.md) - [Hog Functions](./references/models-hog-functions.md) - [Integrations](./references/models-integrations.md) - [AI observability events (`posthog.ai_events`)](./references/models-ai-observability-events.md) - [AI observability reviews](./references/models-ai-observability-reviews.md) - [Logs (`logs` data plane + saved views and alerts)](./references/models-logs.md) - [Metrics (`posthog.metrics`)](./references/models-metrics.md) - [Notebooks](./references/models-notebooks.md) - [Session Recording Playlists](./references/models-session-recording-playlists.md) - [Session Recordings](./references/models-session-recordings.md) - [Support Tickets](./references/models-support-tickets.md) - [Surveys](./references/models-surveys.md) - [Usage Metrics](./references/models-usage-metrics.md) - [SQL Variables](./references/models-variables.md) - [Skipped events in the read-data-schema tool](./references/taxonomy-skipped-events.md) - [Dynamic person and event properties](./references/taxonomy-dynamic-properties.md) — patterns like `$survey_dismissed/{id}`, `$feature/{key}` that don't appear in tool results ## HogQL References - [Person property modes (event-time vs query-time)](./references/person-property-modes.md). Read when working with `person.properties.*` to understand if values are historical or current. - [Sparkline, SemVer, Session replays, Actions, Translation, HTML tags and links, Text effects, and more](./references/hogql-extensions.md) - [SQL variables](./references/models-variables.md). - [Available functions in HogQL](./references/available-functions.md). IMPORTANT: the list is long, so read data using bash commands like grep. ## Analytics Query Examples Use the examples below to create optimized analytical queries. - [Trends (unique users, specific time range, single series)](./references/example-trends-unique-users.md) - [Trends (total count with multiple breakdowns)](./references/example-trends-breakdowns.md) - [Funnel (two steps, aggregated by unique users, broken down by the person's role, sequential, 14-day conversion window)](./references/example-funnel-breakdown.md) - [Conversion trends (funnel, two steps, aggregated by unique groups, 1-day conversion window)](./references/example-funnel-trends.md) - [Retention (unique users, returned to perform an event in the next 12 weeks, recurring)](./references/example-retention.md) - [User paths (pageviews, three steps, applied path cleaning and filters, maximum 50 paths)](./references/example-paths.md) - [Lifecycle (unique users by pageviews)](./references/example-lifecycle.md) - [Stickiness (counted by pageviews from unique users, defined by at least one event for the interval, non-cumulative)](./references/example-stickiness.md) - [LLM trace (generations, spans, embeddings, human feedback, captured AI metrics)](./references/example-llm-trace.md) - [LLM traces list (searching and listing traces with property filters, two-phase query)](./references/example-llm-traces-list.md) - [Web path stats (paths, visitors, views, bounce rate)](./references/example-web-path-stats.md) - [Web traffic channels (direct, organic search, etc)](./references/example-web-traffic-channels.md) - [Web views by devices](./references/example-web-traffic-by-device-type.md) - [Web overview](./references/example-web-overview.md) - [Error tracking (search for a value in an error and filtering by custom properties)](./references/example-error-tracking.md) - [Logs (filtering by severity and searching for a term)](./references/example-logs.md) - [Cross-signal correlation (metric exemplar → trace → logs)](./references/example-observability-correlation.md) - [Sessions (listing sessions with duration, pageviews, and bounce rate)](./references/example-sessions.md) - [Session replay (listing recordings with activity filters)](./references/example-session-replay.md) - [Team taxonomy (top events by count, paginated)](./references/example-team-taxonomy.md) - [Event taxonomy (properties of an event, with sample values)](./references/example-event-taxonomy.md) - [Person property taxonomy (sample values for person properties)](./references/example-person-property-taxonomy.md)