/analyzing-ai-citations

name: analyzing-ai-citations
description: >
  Answer AI citation and answer engine optimization (AEO) questions in PostHog: whether
  AI answer engines (ChatGPT, Claude, and an Exa retrieval baseline) cite the project's
  site for its tracked prompts, which topics and engines cite it least, which domains get
  cited instead, and whether citations line up with Google Search Console rankings and AI
  referral or AI crawler traffic. Use when the user asks "are we cited by AI?", "which
  prompts never cite us?", "citation rate by topic or engine", "who gets cited instead of
  us?", "do AI citations drive traffic?", or wants to cross-reference AI answers, Search
  Console and PostHog web traffic.

Analyzing AI citations

PostHog runs a set of tracked prompts against AI answer engines once a day and records, per prompt and engine, whether the answer cited the project's own domain. Every citation question reduces to an aggregation over that record, optionally joined to two other sources: Google Search Console (a data warehouse source) and the project's own web traffic (the `sessions` and `events` tables).

This skill covers the citation record, the prompt set tools, the joins, and the HogQL papercuts that make the first query fail.

Tools

| Tool | Purpose | | ------------------------------------ | ---------------------------------------------------------------------------------------- | | `posthog:execute-sql` | HogQL over `system.aeo_citation_checks`, Search Console tables, `sessions` and `events` | | `posthog:aeo-prompts-list` | The tracked prompt set with topic, on/off state and the latest result per engine | | `posthog:aeo-prompts-topics-list` | Topics in the prompt set with prompt counts | | `posthog:aeo-prompts-get` | One prompt with its latest check per engine | | `posthog:aeo-prompts-stats-get` | Per-engine citation and mention rates, 30-day daily counts, consensus domains, sentiment | | `posthog:aeo-prompts-checks-list` | A prompt's check history: answers, cited URLs, search queries, failures | | `posthog:aeo-prompts-versions-list` | A prompt's text versions, to compare results before and after a reword | | `posthog:aeo-prompts-import` | Add prompts to the set (write; ask the user first) | | `posthog:aeo-prompts-update` | Turn a prompt on or off, change its topic or text (write; ask the user first) | | `posthog:aeo-prompts-archive` | Archive a prompt (write; ask the user first) | | `posthog:external-data-sources-list` | Find the Search Console source and its table names | | `posthog:read-data-schema` | Discover event and action properties before joining to traffic (not warehouse tables) | | `posthog:generate-app-url` | Links back to the Prompts tab under `/web/content-autopilot` |

Before you start

• **The feature is flag-gated.** Every `aeo-prompts-*` tool and the API behind it require the

`aeo-citation-tracking` feature flag for the user's organization. A 403 with "This feature is not available." means the flag is off, not a scope problem.

• **Scopes.** Reads (`list`, `get`, `topics`, `checks`, `stats`, `versions`) need

`web_analytics:read`; writes (`update`, `archive`, `import`) need `web_analytics:write`. A missing scope surfaces as `Missing PostHog API scope: 'web_analytics:read'` (the API says "API key missing required scope"). Recovery: reauthorize the MCP connection so the new grant includes the scope, or add the scope to the personal API key the connection uses. Do not retry with other tools; the scope is the fix.

• **Is the runner active on this project?** Run

`SELECT count() FROM system.aeo_citation_checks WHERE created_at >= now() - INTERVAL 14 DAY`. Zero rows means no prompts are being checked for this project. The scheduled runner only covers allowlisted projects with the flag on; it runs once a day at 07:30 UTC.

Data sources

`system.aeo_citation_checks` (the citation record)

One row per prompt x engine x run, read-only in HogQL. Written only by the runner.

| Column | Meaning | | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | `created_at`, `run_id` | When the check ran; `run_id` groups one runner pass | | `prompt_id`, `prompt_text`, `prompt_topic`, `prompt_source`, `prompt_version` | The prompt as it ran. Topic is empty when the prompt had none. Group by `prompt_topic` for topic rates | | `engine`, `model` | `claude-web-search`, `openai-web-search`, or `exa-answer` | | `cited` (Boolean) | A target-domain URL appears in the answer's citations | | `check_failed` (Boolean), `error` | The engine did not answer. Not evidence that a citation was lost | | `num_citations`, `target_best_position` | How many URLs were cited; 1-based position of the first target-domain URL