--- name: gentic-analytics description: "Give your AI agent read-only access to your PostHog project. Analyze sessions, scroll depth, button clicks, and saved insights — or run custom HogQL — all through the Model Context Protocol." license: MIT metadata: author: gentic version: "1.0.0" --- # Gentic Analytics Give your AI agent read access to your PostHog project. Analyze sessions, scroll depth, button clicks, and saved insights — or drop into raw HogQL when you need something custom. All through the Model Context Protocol, connected to your own PostHog workspace. ## When to apply - User is debugging a funnel, a landing page, or a campaign and wants to know what's actually happening on the site. - User wants to compare a recent period against a previous one — traffic, engagement, scroll, clicks. - User asks about a specific entry URL or pathname. - User wants to pull a saved PostHog insight or run a custom HogQL query against events / sessions / persons. ## Tools | Tool | Description | Cost | |------|-------------|------| | `gentic_ingest_avg_engagement_time` | Returns per-URL engagement metrics — average wallclock dwell time (avg_ms), average active-engagement time (avg_active_ms, NULL for pre-#68 legacy events), and average max scroll depth (0–100) — over the given window. Optionally filtered by URL (exact or prefix). Use this for 'are users actually reading this page' insights — wallclock ≥ active by definition; long wallclock + low active = backgrounded tab. | 5¢ / call | | `gentic_ingest_click_counts` | Returns aggregate click counts grouped by element tag + class_chain over the given window. Optionally filtered by URL (exact or prefix). Use this for 'which CTA is getting clicked vs ignored' insights — this surface counts ALL clicks (interactive and non-interactive); for rage-click incidents specifically use gentic_ingest_top_rage_clicks. | 5¢ / call | | `gentic_ingest_daily_visitors` | Returns unique-visitor count per UTC day for the given window. Optionally filtered by URL (exact or prefix). Use this for 'how many distinct visitors did the brand get this week vs last week' style insights. Returns one row per day. | 5¢ / call | | `gentic_ingest_pageviews_by_device_class` | Returns pageview count and unique-visitor count grouped by device_class (mobile, desktop, or 'unknown' for pre-tracker-v1 legacy data) over the given window. Optionally filtered to a specific URL or URL prefix. Use this for 'what's the mobile-vs-desktop split for this brand's site this week' insights. Returns ≤3 rows. | 5¢ / call | | `gentic_ingest_top_pages` | Returns the most-viewed URLs over the given window, with pageview count per URL. Optionally filtered by URL (exact or prefix). Use this for 'what's resonating' or 'where are users landing' style insights. | 5¢ / call | | `northbeam_create_export` | Kick off a Northbeam Data Export job. Returns an export_id immediately; use northbeam_get_export to poll for the CSV download URL once ready (typically 30s-3min). Call northbeam_list_metrics / list_attribution_models / list_breakdowns first to discover valid IDs. For period_type, use one of Northbeam's presets (e.g. 'YESTERDAY', 'LAST_30_DAYS', 'MONTH_TO_DATE') or 'FIXED' with explicit period_starting_at / period_ending_at — see the period_type field description for the full list. If you pass breakdowns, every entry must include a non-empty `values` array. Costs $0.50. | 50¢ / call | | `northbeam_get_export` | Fetch the result of a Northbeam Data Export submitted via northbeam_create_export. Returns status, the CSV download URL when ready, and a parsed preview of the top rows. If still processing, the tool polls (2s interval) up to wait_seconds before returning the IN_PROGRESS state so the agent doesn't have to re-poll. Free. | Free | | `northbeam_list_attribution_models` | List the attribution models available in your Northbeam account (e.g. northbeam_custom, last_touch, first_touch, linear). Use this before calling northbeam_create_export to pick a valid model. Free. | Free | | `northbeam_list_breakdowns` | List the breakdown dimensions available in your Northbeam account (e.g. platform, category, targeting, influencer_by_platform). Use this before calling northbeam_create_export to pick valid breakdown groupings. Free. | Free | | `northbeam_list_metrics` | List the metrics available in your Northbeam account (e.g. attributed_revenue, cac, roas, spend, transactions). Use this before calling northbeam_create_export to pick valid metric IDs. Free. | Free | | `posthog_analyze_button_clicks` | Analyze button click breakdown for sessions that entered through a specific page. Returns click counts, unique users, and share-of-clicks per button text. Useful for identifying which CTAs on a landing page are driving engagement. | 8¢ / call | | `posthog_analyze_sessions` | Analyze session metrics for a specific entry page, comparing recent vs previous period. Returns volume, engagement, quality, performance, and traffic-source breakdowns. Useful for spotting regressions or lifts after page/campaign changes. | 10¢ / call | | `posthog_execute_hogql_query` | Execute a raw HogQL query against PostHog. Use for custom analytics queries on events, sessions, persons — e.g. "SELECT properties.$current_url, count() FROM events WHERE event = '$pageview' GROUP BY properties.$current_url LIMIT 50". Returns query results as JSON. | 10¢ / call | | `posthog_get_insights` | List saved PostHog insights (dashboards, funnels, trends) for the connected project. Supports pagination. Free. | Free | | `posthog_scroll_depth_analysis` | Analyze scroll depth for sessions entering through a specific pathname. Returns avg/max scroll percent, time on page, and reader distribution (deep/medium/light). Useful for diagnosing which sections of a landing page users actually reach. | 8¢ / call | ## Workflow ### 1. Start with the entry pathname If the user mentions a page, ad, or campaign, resolve it to a PostHog entry pathname (e.g. `/pages/qure-microinfusion-offer`). Almost every tool keys off this. If the user is vague, ask. ### 2. Use posthog_analyze_sessions first For any 'how is this page doing' question, start with `posthog_analyze_sessions`. It gives you recent-vs-previous period volume, engagement, quality, performance, and traffic-source breakdowns in one call. This is almost always the right first move. ### 3. Drill down with scroll depth and button clicks If sessions look thin or engagement drops, call `posthog_scroll_depth_analysis` to see where readers are dropping off, and `posthog_analyze_button_clicks` to see which CTAs are pulling. Run both in parallel — they're independent. ### 4. Pull saved insights Use `posthog_get_insights` (free) to surface saved funnels and dashboards the team has already built. Prefer existing insights over ad-hoc HogQL when the answer already lives in one. ### 5. Drop into HogQL for custom questions When the pre-built tools don't cover it — cross-event joins, custom aggregations, specific user segments — use `posthog_execute_hogql_query`. HogQL is PostHog's SQL dialect; syntax docs at https://posthog.com/docs/hogql. Keep queries bounded (LIMIT clauses) and read-only (this integration is scoped read-only anyway). ## Notes - All tools are organization-scoped and talk to the PostHog project connected in the Gentic dashboard. - The stored PostHog key is read-only — write/mutate queries will fail at the PostHog side, not Gentic's side. - Scroll depth, button clicks, and session analysis all default to a 7-14 day window. Pass `days_back` to widen it up to 180 days. ## Tool details - `gentic_ingest_avg_engagement_time` — Returns per-URL engagement metrics — average wallclock dwell time (avg_ms), average active-engagement time (avg_active_ms, NULL for pre-#68 legacy events), and average max scroll depth (0–100) — over the given window. Optionally filtered by URL (exact or prefix). Use this for 'are users actually reading this page' insights — wallclock ≥ active by definition; long wallclock + low active = backgrounded tab. - `since` (string, required) — Inclusive lower bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-18'. - `until` (string, required) — Exclusive upper bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-25'. - `limit` (integer) — Max rows returned. Default 50. - `url` (string) — Optional. Filter to a specific URL (exact match). Wins over url_prefix if both provided. - `url_prefix` (string) — Optional. Filter to URLs starting with this prefix. LIKE wildcards are escaped — only literal prefixes match. - `gentic_ingest_click_counts` — Returns aggregate click counts grouped by element tag + class_chain over the given window. Optionally filtered by URL (exact or prefix). Use this for 'which CTA is getting clicked vs ignored' insights — this surface counts ALL clicks (interactive and non-interactive); for rage-click incidents specifically use gentic_ingest_top_rage_clicks. - `since` (string, required) — Inclusive lower bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-18'. - `until` (string, required) — Exclusive upper bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-25'. - `limit` (integer) — Max rows returned. Default 50. - `url` (string) — Optional. Filter to a specific URL (exact match). Wins over url_prefix if both provided. - `url_prefix` (string) — Optional. Filter to URLs starting with this prefix. LIKE wildcards are escaped — only literal prefixes match. - `gentic_ingest_daily_visitors` — Returns unique-visitor count per UTC day for the given window. Optionally filtered by URL (exact or prefix). Use this for 'how many distinct visitors did the brand get this week vs last week' style insights. Returns one row per day. - `since` (string, required) — Inclusive lower bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-18'. - `until` (string, required) — Exclusive upper bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-25'. - `url` (string) — Optional. Filter to a specific URL (exact match). Wins over url_prefix if both provided. - `url_prefix` (string) — Optional. Filter to URLs starting with this prefix (e.g., 'https://example.com/blog/'). LIKE wildcards are escaped — only literal prefixes match. - `gentic_ingest_pageviews_by_device_class` — Returns pageview count and unique-visitor count grouped by device_class (mobile, desktop, or 'unknown' for pre-tracker-v1 legacy data) over the given window. Optionally filtered to a specific URL or URL prefix. Use this for 'what's the mobile-vs-desktop split for this brand's site this week' insights. Returns ≤3 rows. - `since` (string, required) — Inclusive lower bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-18'. - `until` (string, required) — Exclusive upper bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-25'. - `url` (string) — Optional. Filter to a specific URL (exact match). Wins over url_prefix if both provided. - `url_prefix` (string) — Optional. Filter to URLs starting with this prefix (e.g., 'https://example.com/blog/'). LIKE wildcards are escaped — only literal prefixes match. - `gentic_ingest_top_pages` — Returns the most-viewed URLs over the given window, with pageview count per URL. Optionally filtered by URL (exact or prefix). Use this for 'what's resonating' or 'where are users landing' style insights. - `since` (string, required) — Inclusive lower bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-18'. - `until` (string, required) — Exclusive upper bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-25'. - `limit` (integer) — Max rows returned. Default 50. - `url` (string) — Optional. Filter to a specific URL (exact match). Wins over url_prefix if both provided. - `url_prefix` (string) — Optional. Filter to URLs starting with this prefix. LIKE wildcards are escaped — only literal prefixes match. - `northbeam_create_export` — Kick off a Northbeam Data Export job. Returns an export_id immediately; use northbeam_get_export to poll for the CSV download URL once ready (typically 30s-3min). Call northbeam_list_metrics / list_attribution_models / list_breakdowns first to discover valid IDs. For period_type, use one of Northbeam's presets (e.g. 'YESTERDAY', 'LAST_30_DAYS', 'MONTH_TO_DATE') or 'FIXED' with explicit period_starting_at / period_ending_at — see the period_type field description for the full list. If you pass breakdowns, every entry must include a non-empty `values` array. Costs $0.50. - `metrics` (array of string, required) — Metric IDs (from northbeam_list_metrics), e.g. ['attributed_revenue', 'spend', 'roas']. - `attribution_models` (array of string, required) — Attribution model IDs (from northbeam_list_attribution_models), e.g. ['northbeam_custom']. Pass multiple to compare models in one report. - `accounting_modes` (array of string) — Accounting modes: 'cash' (revenue when transaction occurs) or 'accrual' (revenue when touchpoint occurs). Defaults to ['accrual']. - `attribution_windows` (array of string) — Attribution windows in days, e.g. ['7'] or ['1','7','30']. Defaults to ['7']. - `level` (string, enum: `ad` | `adset` | `campaign` | `account`) — Granularity of the export. Defaults to Northbeam's API default. - `time_granularity` (string, enum: `DAILY` | `WEEKLY` | `MONTHLY`) — Row time granularity. Defaults to DAILY. - `period_type` (string) — Reporting period. Defaults to 'YESTERDAY'. Use 'FIXED' for a custom date range (then set period_starting_at + period_ending_at). Common preset values: TODAY, YESTERDAY, YESTERDAY_AND_TODAY, TODAY_AND_YESTERDAY, LAST_3_DAYS, LAST_7_DAYS, LAST_14_DAYS, LAST_28_DAYS, LAST_30_DAYS, LAST_60_DAYS, LAST_90_DAYS, LAST_180_DAYS, MONTH_TO_DATE, LAST_MONTH, THIS_MONTH, THIS_MONTH_AND_LAST_MONTH, THIS_WEEK, LAST_WEEK, THIS_WEEK_AND_LAST_WEEK, LAST_3_WEEKS, LAST_4_WEEKS, LAST_7_WEEKS, LAST_12_WEEKS, LAST_14_WEEKS, LAST_26_WEEKS, LAST_28_WEEKS, LAST_52_WEEKS. Northbeam may add more — invalid values come back as a clear 422 from the API. - `period_starting_at` (string) — ISO date (YYYY-MM-DD). Required when period_type='FIXED' (custom date range). - `period_ending_at` (string) — ISO date (YYYY-MM-DD). Required when period_type='FIXED' (custom date range). - `breakdowns` (array of object) — Optional breakdown groupings. Each item is {key, values}. Discover valid keys via northbeam_list_breakdowns. NOTE: every breakdown must include at least one value — Northbeam rejects breakdowns with missing/empty values arrays. - `remove_zero_spend` (boolean) — Filter out zero-spend rows. Defaults to true. - `aggregate_data` (boolean) — Aggregate across the period instead of returning per-period rows. Defaults to false. - `include_ids` (boolean) — Include platform-side IDs in output rows. Defaults to true. - `include_kind_and_platform` (boolean) — Include kind/platform columns. Defaults to false. - `export_aggregation` (string, enum: `BREAKDOWN` | `TOTAL`) — BREAKDOWN: per-row data. TOTAL: a single aggregate row. Defaults to BREAKDOWN. - `northbeam_get_export` — Fetch the result of a Northbeam Data Export submitted via northbeam_create_export. Returns status, the CSV download URL when ready, and a parsed preview of the top rows. If still processing, the tool polls (2s interval) up to wait_seconds before returning the IN_PROGRESS state so the agent doesn't have to re-poll. Free. - `export_id` (string, required) — The export_id returned by northbeam_create_export. - `wait_seconds` (integer) — Max seconds to wait for SUCCESS before returning IN_PROGRESS. Default 60. Set to 0 for a single check. - `preview_rows` (integer) — How many rows of the CSV to fetch (via Range header) and parse into JSON. Default 20. Set to 0 to skip the preview fetch entirely (useful for very large exports). - `northbeam_list_attribution_models` — List the attribution models available in your Northbeam account (e.g. northbeam_custom, last_touch, first_touch, linear). Use this before calling northbeam_create_export to pick a valid model. Free. - `northbeam_list_breakdowns` — List the breakdown dimensions available in your Northbeam account (e.g. platform, category, targeting, influencer_by_platform). Use this before calling northbeam_create_export to pick valid breakdown groupings. Free. - `northbeam_list_metrics` — List the metrics available in your Northbeam account (e.g. attributed_revenue, cac, roas, spend, transactions). Use this before calling northbeam_create_export to pick valid metric IDs. Free. - `platform` (string) — Optional platform filter (e.g. 'meta', 'google', 'tiktok'). If omitted, returns metrics for all connected platforms. - `posthog_analyze_button_clicks` — Analyze button click breakdown for sessions that entered through a specific page. Returns click counts, unique users, and share-of-clicks per button text. Useful for identifying which CTAs on a landing page are driving engagement. - `entry_pathname` (string, required) — The entry pathname to analyze, e.g. '/pages/qure-microinfusion-offer' - `days_back` (number) — Days to look back. Defaults to 7. - `posthog_analyze_sessions` — Analyze session metrics for a specific entry page, comparing recent vs previous period. Returns volume, engagement, quality, performance, and traffic-source breakdowns. Useful for spotting regressions or lifts after page/campaign changes. - `entry_pathname` (string, required) — The entry pathname to analyze, e.g. '/pages/qure-microinfusion-offer' - `days_back` (number) — Total days to analyze (2-180). Split in half for comparison (e.g. 14 = last 7 vs previous 7). Defaults to 14. - `posthog_execute_hogql_query` — Execute a raw HogQL query against PostHog. Use for custom analytics queries on events, sessions, persons — e.g. "SELECT properties.$current_url, count() FROM events WHERE event = '$pageview' GROUP BY properties.$current_url LIMIT 50". Returns query results as JSON. - `hogql_query` (string, required) — The HogQL query to execute. HogQL is PostHog's SQL dialect — see https://posthog.com/docs/hogql - `posthog_get_insights` — List saved PostHog insights (dashboards, funnels, trends) for the connected project. Supports pagination. Free. - `limit` (number) — Max insights to return (1-100). Defaults to 100. - `offset` (number) — Number of insights to skip for pagination. Defaults to 0. - `posthog_scroll_depth_analysis` — Analyze scroll depth for sessions entering through a specific pathname. Returns avg/max scroll percent, time on page, and reader distribution (deep/medium/light). Useful for diagnosing which sections of a landing page users actually reach. - `entry_pathname` (string, required) — The entry pathname to analyze, e.g. '/pages/qure-microinfusion-offer' - `days_back` (number) — Days to look back. Defaults to 7. --- _This SKILL.md is generated from the live Gentic MCP manifest. Tool names, descriptions, and pricing are always current. Connect Gentic Analytics at https://gentic.co/analytics._