Gentic Analytics — Documentation

Give your AI agent read access to your site analytics — Gentic Ingest, PostHog, and Northbeam — through one MCP endpoint. Analyze sessions, scroll depth, rage clicks, funnel drop-off, ad attribution, and saved insights. Drop into constrained SQL or raw HogQL when you need something custom.

1. Getting Started

Sign Up & Get Your API Key

Before you can use Gentic Analytics, you need an API key to authenticate your requests.

Go to gentic.co/analytics and create an account.
Create an organization from your dashboard. API keys and billing are scoped to the organization.
Generate an API key and use it as a Bearer token in your MCP client.

2. Connecting to the MCP Server

The server is available at https://mcp.gentic.co/analytics. For Claude Code:

claude mcp add gentic-analytics \
  --transport http \
  https://mcp.gentic.co/analytics \
  --header "Authorization: Bearer YOUR_API_KEY"

For Claude Web and ChatGPT you can also connect via OAuth — no API key needed. See the connect section on the landing page for other MCP clients (n8n, OpenClaw).

3. Agent Skill

For the best results, pair the MCP server with the Gentic Analytics agent skill. The MCP server gives your agent tool access; the skill teaches it the optimal workflow order. Both the raw SKILL.md and a ready-to-upload .skill bundle are generated on demand from the live manifest, so they always reflect the current tools and pricing.

Add the skill directly via URL:

https://gentic.co/analytics/SKILL.md

Or upload a .skill bundle to Claude Managed Agents:

https://gentic.co/analytics/gentic-analytics.skill

Download this file and upload it wherever Claude Managed Agents asks for a .skill file. It's a zip bundle generated on demand from the latest SKILL.md.

4. Connecting Your PostHog Project

Gentic Analytics reads analytics from your own PostHog project. Connect it once from the dashboard:

Open the Gentic dashboard and go to the Integrations section.
In PostHog, go to Settings → Personal API Keys and create a read-only key with at minimum query:read, project:read, and insight:read scopes.
Paste the key, your Project ID, and your Host (https://us.i.posthog.com or https://eu.i.posthog.com) into the PostHog connect dialog.
Gentic will validate the key against PostHog and store it encrypted at rest. The key is scoped to your organization.

5. 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.

6. 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).

7. Tool Reference

34 tools, rendered live from the Gentic MCP manifest. Parameter tables come directly from each tool's JSON Schema.

gentic_ingest_avg_engagement_time

5¢ / call

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.

Parameter	Type	Description
`since` required	`string`	Inclusive lower bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-18'.
`until` required	`string`	Exclusive upper bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-25'.
`limit`	`integer`	Max rows returned. Default 50. 1 – 100000
`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.
`domain`	`string`	Optional. The domain of the site within this org to query (e.g. 'gosolo.ghost.io'). If the org has only one connected site, omit. If the org has multiple, you MUST pass this — otherwise queries silently return data for the oldest-connected site, which is rarely what's intended. Call gentic_ingest_list_sites to enumerate available domains.

gentic_ingest_bounce_rate

5¢ / call

Returns the bounce rate for the site over the given window — total sessions (containing at least one pageview), bounces (sessions with exactly ONE pageview), and the bounce rate percentage. THE most-requested operator metric: 'how many of our visitors leave immediately?' Pair with gentic_ingest_top_entry_pages to see WHICH landing pages drive the bounces. Denominator semantics matter: bounce = exactly-one-pageview session, NOT 'session where the user disengaged' — engagement-only sessions without a pageview aren't in the denominator at all. Aligns with GA4's definition. Aggregate session model (30-min idle threshold over subject_id, no DOM state captured or reconstructed) — answers 'what fraction of sessions bounced', not 'what did this visitor do.'

Parameter	Type	Description
`since` required	`string`	Inclusive lower bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-18'.
`until` required	`string`	Exclusive upper bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-25'.
`domain`	`string`	Optional. The domain of the site within this org to query (e.g. 'gosolo.ghost.io'). If the org has only one connected site, omit. If the org has multiple, you MUST pass this — otherwise queries silently return data for the oldest-connected site, which is rarely what's intended. Call gentic_ingest_list_sites to enumerate available domains.

gentic_ingest_checkout_dropoff

5¢ / call

Returns checkout-stage drop-off rates over the given window — unique-subject counts at each of (add_to_cart → checkout_started → checkout_completed → purchase), plus the step-to-step conversion percentage computed against the previous stage. Use this for 'where exactly is the checkout losing buyers' insights. Same data-availability caveat as funnel_completion: empty rows = 'tracker not emitting checkout events yet', not 'no one checked out.'

Parameter	Type	Description
`since` required	`string`	Inclusive lower bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-18'.
`until` required	`string`	Exclusive upper bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-25'.
`domain`	`string`	Optional. The domain of the site within this org to query (e.g. 'gosolo.ghost.io'). If the org has only one connected site, omit. If the org has multiple, you MUST pass this — otherwise queries silently return data for the oldest-connected site, which is rarely what's intended. Call gentic_ingest_list_sites to enumerate available domains.

gentic_ingest_click_counts

5¢ / call

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.

Parameter	Type	Description
`since` required	`string`	Inclusive lower bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-18'.
`until` required	`string`	Exclusive upper bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-25'.
`limit`	`integer`	Max rows returned. Default 50. 1 – 100000
`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.
`domain`	`string`	Optional. The domain of the site within this org to query (e.g. 'gosolo.ghost.io'). If the org has only one connected site, omit. If the org has multiple, you MUST pass this — otherwise queries silently return data for the oldest-connected site, which is rarely what's intended. Call gentic_ingest_list_sites to enumerate available domains.

gentic_ingest_click_heatmap_grid

5¢ / call

Returns a 100×100 viewport-normalized click heatmap grid for the given window — rows of (url, vx_pct, vy_pct, clicks) where coords are integer 0–100. Aggregate-only by design (raw pixel positions never leave the client; 1%-bucketed at source per Principle X) — do NOT promise replay-like 'show me this user's clicks' behavior. Optionally filtered by URL (exact or prefix). Default limit is 10000 — enough for a full single-URL grid without truncation. Edge cells (vx_pct=0/100 or vy_pct=0/100) may carry synthetic concentrations from elastic-scroll / off-viewport clamps; treat edge hotspots as instrumentation noise unless they match a known fixed-position element.

Parameter	Type	Description
`since` required	`string`	Inclusive lower bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-18'.
`until` required	`string`	Exclusive upper bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-25'.
`limit`	`integer`	Max rows returned. Default 10000 — full grid for one URL. Raise for multi-URL queries, lower for sparse pages. 1 – 100000
`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.
`domain`	`string`	Optional. The domain of the site within this org to query (e.g. 'gosolo.ghost.io'). If the org has only one connected site, omit. If the org has multiple, you MUST pass this — otherwise queries silently return data for the oldest-connected site, which is rarely what's intended. Call gentic_ingest_list_sites to enumerate available domains.

gentic_ingest_daily_visitors

5¢ / call

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.

Parameter	Type	Description
`since` required	`string`	Inclusive lower bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-18'.
`until` required	`string`	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.
`domain`	`string`	Optional. The domain of the site within this org to query (e.g. 'gosolo.ghost.io'). If the org has only one connected site, omit. If the org has multiple, you MUST pass this — otherwise queries silently return data for the oldest-connected site, which is rarely what's intended. Call gentic_ingest_list_sites to enumerate available domains.

gentic_ingest_describe_events

Free

Returns the discovered schema for this site's events: per-event-type total_events / first_seen / last_seen aggregates, plus per-property the JSON type, non-null count, and up to 3 distinct sample values. Call this BEFORE composing a complex filter or writing custom SQL via gentic_ingest_execute_query — without schema knowledge, the LLM will guess property names and fail. Optional since/until scope the schema sampling to a time window (e.g., 'what schemas does this site emit in the last 24h' vs 'historically'); defaults to all-time. Free — call early and often when building ad-hoc queries. Aggregate-only per Principle X — no subject_id or per-user data in the response; sample values are up to 3 distinct property values, not per-user identifiers.

Parameter	Type	Description
`since`	`string`	Optional. Scope the schema sampling to events after this timestamp. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Defaults to all-time.
`until`	`string`	Optional. Scope upper bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Defaults to now.
`domain`	`string`	Optional. The domain of the site within this org to query (e.g. 'gosolo.ghost.io'). If the org has only one connected site, omit. If the org has multiple, you MUST pass this — otherwise queries silently return data for the oldest-connected site, which is rarely what's intended. Call gentic_ingest_list_sites to enumerate available domains.

gentic_ingest_execute_query

25¢ / call

Run a constrained SELECT against the events table within the time window. Use when no predefined gentic_ingest_* tool fits the question (e.g., 'top URLs whose engagement_ms grew >50% week-over-week filtered to mobile only'). Returns up to 10,000 rows. site_id is auto-scoped to your authenticated read_key — site_id literals in your SQL filter on top of the scoped CTE, never selecting other sites. Time-window predicates on occurred_at are auto-injected from since/until — your SQL should NOT add them. Costs 25¢ per call (vs 5¢ for predefined gentic_ingest_* tools): prefer purpose-built tools when one fits; fall back here for ad-hoc questions. Call gentic_ingest_describe_events FIRST to enumerate event_types and per-event-type properties — without that, the LLM guesses property names and fails. Errors are passed through verbatim from the substrate ('keyword X is not allowed', 'unknown function Y', 'sql must reference FROM events') so you can self-correct; SQL-validation failures cost $0, execution-time failures bill normally.

Parameter	Type	Description
`sql` required	`string`	SQL SELECT statement (10-8000 chars). Example: SELECT json_extract_string(properties, '$.url') AS url, COUNT(*) AS views FROM events WHERE event_type = 'pageview' GROUP BY url ORDER BY views DESC LIMIT 10
`since` required	`string`	Inclusive lower bound for the auto-injected occurred_at window. ISO date (YYYY-MM-DD) or full ISO 8601 datetime.
`until` required	`string`	Exclusive upper bound for the auto-injected occurred_at window. ISO date (YYYY-MM-DD) or full ISO 8601 datetime.
`domain`	`string`	Optional. The domain of the site within this org to query (e.g. 'gosolo.ghost.io'). If the org has only one connected site, omit. If the org has multiple, you MUST pass this — otherwise queries silently return data for the oldest-connected site, which is rarely what's intended. Call gentic_ingest_list_sites to enumerate available domains.

gentic_ingest_funnel_completion

5¢ / call

Returns unique-subject counts at each step of the ecommerce funnel (pageview → product_viewed → add_to_cart → checkout_started → purchase) over the given window. Rows arrive in funnel order, with `unique_subjects` per `event_type`. Use this for 'how many visitors made it through to purchase' insights — derived conversion rates are step-to-step ratios in the row order. NOTE: returns empty rows for sites that don't emit purchase/checkout events from their tracker (most non-ecommerce sites). Empty rows = 'tracker not emitting these event types yet', NOT 'no one purchased.'

Parameter	Type	Description
`since` required	`string`	Inclusive lower bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-18'.
`until` required	`string`	Exclusive upper bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-25'.
`domain`	`string`	Optional. The domain of the site within this org to query (e.g. 'gosolo.ghost.io'). If the org has only one connected site, omit. If the org has multiple, you MUST pass this — otherwise queries silently return data for the oldest-connected site, which is rarely what's intended. Call gentic_ingest_list_sites to enumerate available domains.

gentic_ingest_list_available_queries

Free

Returns the catalog of all gentic_ingest_* analytics tools available on this MCP endpoint — each entry has tool_name, a one-line description, category, and the underlying gentic-ingest API endpoint (null for the meta-tool itself). Use this BEFORE composing a multi-tool answer to discover what primitives exist (e.g., before answering a vitals question, call this with category='vitals' to see what's available). Free — no upstream call.

Parameter Type Description

Parameter	Type	Description
`category`	`string`	Optional. Filter to one category. Omit to return the full catalog (23 tools today: 14 substrate-query primitives + 5 session-aware + 1 referrer-source + 2 ad-hoc escape hatches — describe_events + execute_query — + 2 discovery — list_available_queries + list_sites — give or take the version of the family at time of read). enum: engagement, navigation, clicks, forms, vitals, commerce, sessions, meta

category

string

Optional. Filter to one category. Omit to return the full catalog (23 tools today: 14 substrate-query primitives + 5 session-aware + 1 referrer-source + 2 ad-hoc escape hatches — describe_events + execute_query — + 2 discovery — list_available_queries + list_sites — give or take the version of the family at time of read).

enum: engagement, navigation, clicks, forms, vitals, commerce, sessions, meta

gentic_ingest_list_sites

Free

Lists the gentic-ingest sites (domains) connected for the current organization, with site_id, created_at, and revoked status. Use this BEFORE calling any other gentic_ingest_* tool on a multi-site org you don't know — pass the resulting `domain` back as the `domain` param on subsequent tool calls. Returns active (non-revoked) sites sorted oldest-first. Free — no upstream call.

This tool takes no parameters.

gentic_ingest_pageviews_by_device_class

5¢ / call

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.

Parameter	Type	Description
`since` required	`string`	Inclusive lower bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-18'.
`until` required	`string`	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.
`domain`	`string`	Optional. The domain of the site within this org to query (e.g. 'gosolo.ghost.io'). If the org has only one connected site, omit. If the org has multiple, you MUST pass this — otherwise queries silently return data for the oldest-connected site, which is rarely what's intended. Call gentic_ingest_list_sites to enumerate available domains.

gentic_ingest_sessions_by_day

5¢ / call

Returns daily session counts + bounces + average duration over the window, one row per UTC day. Each session is bucketed by the day of its FIRST event (so a session spanning midnight counts on the start day only). Use for trend tracking — 'are sessions trending up?', 'is bounce rate getting worse?' — and as the per-day delta feed for the analytics-report skill's daily-comparison shape. Aggregate session model — no per-user trajectory, just per-day rollups.

Parameter	Type	Description
`since` required	`string`	Inclusive lower bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-18'.
`until` required	`string`	Exclusive upper bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-25'.
`domain`	`string`	Optional. The domain of the site within this org to query (e.g. 'gosolo.ghost.io'). If the org has only one connected site, omit. If the org has multiple, you MUST pass this — otherwise queries silently return data for the oldest-connected site, which is rarely what's intended. Call gentic_ingest_list_sites to enumerate available domains.

gentic_ingest_sessions_summary

5¢ / call

Returns dashboard-headline session stats over the given window — total_sessions, avg_pages_per_session, avg_duration_seconds, median_duration_seconds. Single-row response. Pair with gentic_ingest_bounce_rate for the canonical 'we got N sessions, X pages avg, Y seconds avg, Z% bounced' summary line. Aggregate session model — 30-min idle threshold over subject_id, no per-user reconstruction (the model gives 'what fraction of sessions did X', not 'what did visitor 47 do').

Parameter	Type	Description
`since` required	`string`	Inclusive lower bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-18'.
`until` required	`string`	Exclusive upper bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-25'.
`domain`	`string`	Optional. The domain of the site within this org to query (e.g. 'gosolo.ghost.io'). If the org has only one connected site, omit. If the org has multiple, you MUST pass this — otherwise queries silently return data for the oldest-connected site, which is rarely what's intended. Call gentic_ingest_list_sites to enumerate available domains.

gentic_ingest_timeseries_purchases

5¢ / call

Returns purchase event counts and summed revenue per HOUR bucket over the given window (rows: { bucket, purchases, revenue }). Use this for 'are purchases trending up/down' or 'when in the day do customers buy' insights — pair with web_vitals_summary or engagement queries to correlate purchase changes with site-health changes. Bucket granularity is hourly only (upstream-fixed today; coarser/finer aggregation must be done at the Mother layer if needed). Same data-availability caveat as funnel/checkout — empty rows mean the tracker doesn't emit purchase events yet, not zero conversions.

Parameter	Type	Description
`since` required	`string`	Inclusive lower bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-18'.
`until` required	`string`	Exclusive upper bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-25'.
`domain`	`string`	Optional. The domain of the site within this org to query (e.g. 'gosolo.ghost.io'). If the org has only one connected site, omit. If the org has multiple, you MUST pass this — otherwise queries silently return data for the oldest-connected site, which is rarely what's intended. Call gentic_ingest_list_sites to enumerate available domains.

gentic_ingest_top_entry_pages

5¢ / call

Returns the URLs where the most sessions BEGAN — top landing pages, ordered by session count, with per-page bounce count and bounce rate. Use for 'where do visitors arrive on the site, and which landing pages cause the most bounces?' First-touch attribution surface: once referrer/UTM capture lands upstream (gentic-ingest#35), this composes with referrer to answer 'which campaign drove this landing experience.' Aggregate session model — counts which pages started sessions over the window, NOT a per-user landing-page history.

Parameter	Type	Description
`since` required	`string`	Inclusive lower bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-18'.
`until` required	`string`	Exclusive upper bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-25'.
`limit`	`integer`	Max rows returned. Default 25. 1 – 100
`domain`	`string`	Optional. The domain of the site within this org to query (e.g. 'gosolo.ghost.io'). If the org has only one connected site, omit. If the org has multiple, you MUST pass this — otherwise queries silently return data for the oldest-connected site, which is rarely what's intended. Call gentic_ingest_list_sites to enumerate available domains.

gentic_ingest_top_exit_pages

5¢ / call

Returns the URLs where the most sessions ENDED — top exit pages, ordered by exit-session count. Use for 'where do visitors leave the site?' — identifying dead-end pages or confusing navigation. NOTE: a single-pageview session has the SAME URL as both entry AND exit, so this query and gentic_ingest_top_entry_pages will share rows for bouncers — use gentic_ingest_bounce_rate to disambiguate the populations. Aggregate session model — counts which pages ended sessions over the window, NOT a per-user exit history.

Parameter	Type	Description
`since` required	`string`	Inclusive lower bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-18'.
`until` required	`string`	Exclusive upper bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-25'.
`limit`	`integer`	Max rows returned. Default 25. 1 – 100
`domain`	`string`	Optional. The domain of the site within this org to query (e.g. 'gosolo.ghost.io'). If the org has only one connected site, omit. If the org has multiple, you MUST pass this — otherwise queries silently return data for the oldest-connected site, which is rarely what's intended. Call gentic_ingest_list_sites to enumerate available domains.

gentic_ingest_top_form_submits

5¢ / call

Returns the most-submitted forms over the given window, grouped by (url, form_id), with submit count and unique-visitor count. Optionally filtered by URL (exact or prefix). Use this for 'which forms are getting traction vs which are dead' insights. Unnamed forms collapse to form_id=''. Privacy: upstream payload contains form_id + form_name + field_count ONLY — NO field values, names, or labels. Login forms and newsletter signups are payload-indistinguishable by design; do NOT attempt to infer form purpose from form_id alone.

Parameter	Type	Description
`since` required	`string`	Inclusive lower bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-18'.
`until` required	`string`	Exclusive upper bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-25'.
`limit`	`integer`	Max rows returned. Default 50. 1 – 100000
`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.
`domain`	`string`	Optional. The domain of the site within this org to query (e.g. 'gosolo.ghost.io'). If the org has only one connected site, omit. If the org has multiple, you MUST pass this — otherwise queries silently return data for the oldest-connected site, which is rarely what's intended. Call gentic_ingest_list_sites to enumerate available domains.

gentic_ingest_top_outbound_destinations

5¢ / call

Returns the most-clicked outbound destination hosts over the given window, with click count and unique-visitor count per destination. Optionally filtered by URL (exact or prefix). Use this for 'where is the brand's audience going when they leave' insights — useful for finding accidental referral traffic patterns or competing-destination drain. Upstream correctly excludes pseudo-protocols (mailto:, tel:, javascript:) and in-page anchors — returned destinations are true off-host navigations only.

Parameter	Type	Description
`since` required	`string`	Inclusive lower bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-18'.
`until` required	`string`	Exclusive upper bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-25'.
`limit`	`integer`	Max rows returned. Default 50. 1 – 100000
`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.
`domain`	`string`	Optional. The domain of the site within this org to query (e.g. 'gosolo.ghost.io'). If the org has only one connected site, omit. If the org has multiple, you MUST pass this — otherwise queries silently return data for the oldest-connected site, which is rarely what's intended. Call gentic_ingest_list_sites to enumerate available domains.

gentic_ingest_top_pages

5¢ / call

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.

Parameter	Type	Description
`since` required	`string`	Inclusive lower bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-18'.
`until` required	`string`	Exclusive upper bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-25'.
`limit`	`integer`	Max rows returned. Default 50. 1 – 100000
`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.
`domain`	`string`	Optional. The domain of the site within this org to query (e.g. 'gosolo.ghost.io'). If the org has only one connected site, omit. If the org has multiple, you MUST pass this — otherwise queries silently return data for the oldest-connected site, which is rarely what's intended. Call gentic_ingest_list_sites to enumerate available domains.

gentic_ingest_top_rage_clicks

5¢ / call

Returns elements receiving the most rage-click incidents (3+ rapid clicks within 1500ms on the same element) over the given window, grouped by (url, tag, element_id, class_chain), with incident count, total-click count, and unique-visitor count. Includes non-interactive elements — most useful when surfacing 'users are repeatedly clicking what they think is a button but isn't.' Optionally filtered by URL (exact or prefix). For the highest-signal frustration signal, compose with gentic_ingest_click_counts on the same element: high rage:normal-click ratio + non-interactive element = clearest 'broken UX' finding.

Parameter	Type	Description
`since` required	`string`	Inclusive lower bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-18'.
`until` required	`string`	Exclusive upper bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-25'.
`limit`	`integer`	Max rows returned. Default 50. 1 – 100000
`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.
`domain`	`string`	Optional. The domain of the site within this org to query (e.g. 'gosolo.ghost.io'). If the org has only one connected site, omit. If the org has multiple, you MUST pass this — otherwise queries silently return data for the oldest-connected site, which is rarely what's intended. Call gentic_ingest_list_sites to enumerate available domains.

gentic_ingest_top_sources

5¢ / call

Returns the top referring pages (document.referrer) driving traffic to the site over the given window, with pageview count and unique-visitor count per source URL. Direct loads (no referring page) bucket as '(direct)'. Use this for 'where do visitors come from?' — pair with gentic_ingest_top_entry_pages to see which referrers feed which landing pages. Aggregate-only: COUNT(*) and COUNT(DISTINCT subject_id) per source URL — no subject_id in the response, cannot be joined back to individual sessions (answers 'how many came from each source', not 'where did visitor 47 come from'). The referrer URL itself is the browser-set HTTP Referer header (not PII per common definitions). LEGACY CAVEAT: events captured before 2026-05-25 (when the tracker's referrer capture rolled out) bucket as '(direct)' even if they were actually referred — the upstream COALESCE chain treats missing-property legacy events and empty-string post-launch direct hits the same way. Historical reports spanning the launch boundary will show inflated '(direct)' counts for the pre-launch portion; tail rolls off as new traffic flows. This tool does NOT return UTM data (utm_source / utm_medium / utm_campaign) — UTM-aware breakdown is a future tool once upstream tracker captures those fields.

Parameter	Type	Description
`since` required	`string`	Inclusive lower bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-18'.
`until` required	`string`	Exclusive upper bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-25'.
`limit`	`integer`	Max rows returned. Default 20. 1 – 100
`domain`	`string`	Optional. The domain of the site within this org to query (e.g. 'gosolo.ghost.io'). If the org has only one connected site, omit. If the org has multiple, you MUST pass this — otherwise queries silently return data for the oldest-connected site, which is rarely what's intended. Call gentic_ingest_list_sites to enumerate available domains.

gentic_ingest_web_vitals_summary

5¢ / call

Returns Google Core Web Vitals per URL — LCP and CLS averages plus p75 — over the given window. Pageloads count is the denominator (rows: { url, pageloads, avg_lcp_ms, p75_lcp_ms, avg_cls, p75_cls }). p75 is the Google 'passing' criterion: a page passes CWV if ≥75% of pageloads are under the threshold. Google's 'Good' thresholds: LCP ≤2500ms, CLS ≤0.1. Optionally filtered by URL (exact or prefix). Caveats: (1) v1 of the tracker captures LCP + CLS ONLY — no INP / FCP / TTFB / FID; if asked about those, respond honestly that they're not yet captured rather than presenting null/zero. (2) Legacy events from before gentic-ingest #69 don't carry web_vitals; upstream filters them out, so the aggregate is over post-#69 pageviews only — reference the window start date when interpreting results that span the launch boundary. (3) avg_lcp_ms = 0 means PerformanceObserver never fired (very old browsers / non-page contexts), currently indistinguishable from 'page loaded instantly' — treat suspiciously.

Parameter	Type	Description
`since` required	`string`	Inclusive lower bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-18'.
`until` required	`string`	Exclusive upper bound. ISO date (YYYY-MM-DD) or full ISO 8601 datetime. Example: '2026-05-25'.
`limit`	`integer`	Max rows returned. Default 50. 1 – 100000
`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.
`domain`	`string`	Optional. The domain of the site within this org to query (e.g. 'gosolo.ghost.io'). If the org has only one connected site, omit. If the org has multiple, you MUST pass this — otherwise queries silently return data for the oldest-connected site, which is rarely what's intended. Call gentic_ingest_list_sites to enumerate available domains.

northbeam_create_export

50¢ / call

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.

Parameter	Type	Description
`metrics` required	`string[]`	Metric IDs (from northbeam_list_metrics), e.g. ['attributed_revenue', 'spend', 'roas'].
`attribution_models` required	`string[]`	Attribution model IDs (from northbeam_list_attribution_models), e.g. ['northbeam_custom']. Pass multiple to compare models in one report.
`accounting_modes`	`string[]`	Accounting modes: 'cash' (revenue when transaction occurs) or 'accrual' (revenue when touchpoint occurs). Defaults to ['accrual'].
`attribution_windows`	`string[]`	Attribution windows in days, e.g. ['7'] or ['1','7','30']. Defaults to ['7'].
`level`	`string`	Granularity of the export. Defaults to Northbeam's API default. enum: ad, adset, campaign, account
`time_granularity`	`string`	Row time granularity. Defaults to DAILY. enum: DAILY, WEEKLY, MONTHLY
`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`	`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`	BREAKDOWN: per-row data. TOTAL: a single aggregate row. Defaults to BREAKDOWN. enum: BREAKDOWN, TOTAL

northbeam_get_export

Free

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.

Parameter Type Description

Parameter	Type	Description
`export_id` required	`string`	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. 0 – 180
`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). 0 – 100

export_id

required

string

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.

0 – 180

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).

0 – 100

northbeam_list_attribution_models

Free

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.

This tool takes no parameters.

northbeam_list_breakdowns

Free

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.

This tool takes no parameters.

northbeam_list_metrics

Free

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.

Parameter	Type	Description
`platform`	`string`	Optional platform filter (e.g. 'meta', 'google', 'tiktok'). If omitted, returns metrics for all connected platforms.

northbeam_upsert_spend

Free

Push ad spend records to Northbeam for non-integrated channels (influencer, podcast, newsletter, affiliate, etc.) — the API-equivalent of Northbeam's spreadsheet spend import. Send 1–1000 daily records per call, each keyed on (date, platform_name, campaign_id, adset_id, ad_id). Re-POSTing the same key overwrites the prior value (upsert). For a single influencer payment spread across N days, generate the N daily records client-side and pass them in one call. Free.

Parameter	Type	Description
`records` required	`object[]`	Array of spend records, 1–1000 per call. Northbeam's API caps batch size at 1000 (https://docs.northbeam.io/docs/spend-api-best-practices-and-limits).

posthog_analyze_button_clicks

8¢ / call

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.

Parameter Type Description

Parameter	Type	Description
`entry_pathname` required	`string`	The entry pathname to analyze, e.g. '/pages/qure-microinfusion-offer'
`days_back`	`number`	Days to look back. Defaults to 7. 1 – 180

entry_pathname

required

string

The entry pathname to analyze, e.g. '/pages/qure-microinfusion-offer'

days_back

number

Days to look back. Defaults to 7.

1 – 180

posthog_analyze_sessions

10¢ / call

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.

Parameter Type Description

Parameter	Type	Description
`entry_pathname` required	`string`	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. 2 – 180

entry_pathname

required

string

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.

2 – 180

posthog_execute_hogql_query

10¢ / call

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.

Parameter	Type	Description
`hogql_query` required	`string`	The HogQL query to execute. HogQL is PostHog's SQL dialect — see https://posthog.com/docs/hogql

posthog_get_insights

Free

List saved PostHog insights (dashboards, funnels, trends) for the connected project. Supports pagination. Free.

Parameter Type Description

Parameter	Type	Description
`limit`	`number`	Max insights to return (1-100). Defaults to 100. 1 – 100
`offset`	`number`	Number of insights to skip for pagination. Defaults to 0. min 0

limit

number

Max insights to return (1-100). Defaults to 100.

1 – 100

offset

number

Number of insights to skip for pagination. Defaults to 0.

min 0

posthog_scroll_depth_analysis

8¢ / call

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.

Parameter Type Description

Parameter	Type	Description
`entry_pathname` required	`string`	The entry pathname to analyze, e.g. '/pages/qure-microinfusion-offer'
`days_back`	`number`	Days to look back. Defaults to 7. 1 – 180

entry_pathname

required

string

The entry pathname to analyze, e.g. '/pages/qure-microinfusion-offer'

days_back

number

Days to look back. Defaults to 7.

1 – 180

8. Pricing

Pricing is pulled live from the Gentic MCP manifest. All prices are per call and deducted from your Gentic credits.

Tool	Cost
gentic_ingest_avg_engagement_time	5¢ / call
gentic_ingest_bounce_rate	5¢ / call
gentic_ingest_checkout_dropoff	5¢ / call
gentic_ingest_click_counts	5¢ / call
gentic_ingest_click_heatmap_grid	5¢ / call
gentic_ingest_daily_visitors	5¢ / call
gentic_ingest_describe_events	Free
gentic_ingest_execute_query	25¢ / call
gentic_ingest_funnel_completion	5¢ / call
gentic_ingest_list_available_queries	Free
gentic_ingest_list_sites	Free
gentic_ingest_pageviews_by_device_class	5¢ / call
gentic_ingest_sessions_by_day	5¢ / call
gentic_ingest_sessions_summary	5¢ / call
gentic_ingest_timeseries_purchases	5¢ / call
gentic_ingest_top_entry_pages	5¢ / call
gentic_ingest_top_exit_pages	5¢ / call
gentic_ingest_top_form_submits	5¢ / call
gentic_ingest_top_outbound_destinations	5¢ / call
gentic_ingest_top_pages	5¢ / call
gentic_ingest_top_rage_clicks	5¢ / call
gentic_ingest_top_sources	5¢ / call
gentic_ingest_web_vitals_summary	5¢ / call
northbeam_create_export	50¢ / call
northbeam_get_export	Free
northbeam_list_attribution_models	Free
northbeam_list_breakdowns	Free
northbeam_list_metrics	Free
northbeam_upsert_spend	Free
posthog_analyze_button_clicks	8¢ / call
posthog_analyze_sessions	10¢ / call
posthog_execute_hogql_query	10¢ / call
posthog_get_insights	Free
posthog_scroll_depth_analysis	8¢ / call

9. 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.

Gentic Analytics — Documentation

1. Getting Started

Sign Up & Get Your API Key

2. Connecting to the MCP Server

3. Agent Skill

4. Connecting Your PostHog Project

5. When to Apply

6. Workflow

1. Start with the entry pathname

2. Use posthog_analyze_sessions first

3. Drill down with scroll depth and button clicks

4. Pull saved insights

5. Drop into HogQL for custom questions

7. Tool Reference

gentic_ingest_avg_engagement_time

gentic_ingest_bounce_rate

gentic_ingest_checkout_dropoff

gentic_ingest_click_counts

gentic_ingest_click_heatmap_grid

gentic_ingest_daily_visitors

gentic_ingest_describe_events

gentic_ingest_execute_query

gentic_ingest_funnel_completion

gentic_ingest_list_available_queries

gentic_ingest_list_sites

gentic_ingest_pageviews_by_device_class

gentic_ingest_sessions_by_day

gentic_ingest_sessions_summary

gentic_ingest_timeseries_purchases

gentic_ingest_top_entry_pages

gentic_ingest_top_exit_pages

gentic_ingest_top_form_submits

gentic_ingest_top_outbound_destinations

gentic_ingest_top_pages

gentic_ingest_top_rage_clicks

gentic_ingest_top_sources

gentic_ingest_web_vitals_summary

northbeam_create_export

northbeam_get_export

northbeam_list_attribution_models

northbeam_list_breakdowns

northbeam_list_metrics

northbeam_upsert_spend

posthog_analyze_button_clicks

posthog_analyze_sessions

posthog_execute_hogql_query

posthog_get_insights

posthog_scroll_depth_analysis

8. Pricing

9. Notes