A clean-up review of the saved queries a project publishes for outside callers — which nobody calls any more, which have broken, and which are being kept pre-computed at a cost for no one. It changes nothing itself; what you get is a ranked list and an order to work through it.
WHEN TO USE
SCOPE
USE FOR
Find out which endpoints in a project are safe to disable or delete.
Check whether an endpoint's materialisation is currently failing and why.
Spot materialised versions that nobody queries any more so they can be unmaterialised.
Get a one-shot cleanup review of endpoint sprawl after inheriting a project.
This is a saved copy of the skill's SKILL.md instructions. It may differ from the upstream file or the version you install.
Auditing endpoints
This skill produces a project-wide audit of the Endpoints product. Use it when the user wants to
find what to clean up — unused endpoints, failing materialisations, materialised versions that
nobody calls any more. It does not modify anything; it reports.
The deeper investigation per endpoint is diagnosing-endpoint-performance. The audit's job is to
find candidates and hand off.
When to use this skill
"Audit my endpoints" / "What endpoints can I clean up?"
The user is taking over a project and wants to know what they've inherited
A periodic review (monthly / quarterly) of endpoint sprawl
The user is over a materialisation cost budget and wants to know what to disable
The dedicated tools give a fast endpoint-level view. For call frequency, recency, and cost over
time, query the query_log table with execute-sql (endpoint-level). Per-version recency comes
from endpoint-versions — each version carries its own last_executed_at.
Available tools
Tool
What it's for
execute-sql (HogQL)
Primary read path. Query system.data_modeling_endpoints for metadata (name, is_active, current_version, derived_from_insight, last_executed_at) and query_log for endpoint-level usage (call counts, recency, duration, bytes)
endpoint-materialization-status
Per endpoint: is materialisation eligible, current status, last run, last error (not in the system tables — use this tool)
endpoint-versions
All versions for one endpoint, latest first, with each version's query, materialisation state, and last_executed_at
endpoint-update
Write path — disable (is_active: false) or unmaterialise (is_materialized: false) after the user confirms
agent-feedback
Tell the PostHog team what's missing or confusing in this flow so the product and skill improve
Prefer reading from the system tables over the endpoints-get-all / endpoint-get tools — one
SQL query returns the whole inventory and lets you join metadata to usage in query_log.
What counts as an issue
Category
Trigger
Typical action
Never called
No rows in query_log for the endpoint (personal-API-key calls only)
Confirm with the user, then disable
Stale
query_log shows the last call more than 30 days ago
Confirm with the user; often safe to disable
Inactive
is_active = 0 in system.data_modeling_endpoints
Verify intent; if abandoned, delete
Failing materialisation
endpoint-materialization-status returns Failed with an error
Hand off to diagnosing-endpoint-performance
Unused materialised version
A materialised version whose last_executed_at (from endpoint-versions) is null or long stale
Unmaterialise that version, or roll to a newer one
Drifted versions
Many versions exist (query changed repeatedly)
History noise — not an issue, but worth noting
Usage counts only personal-API-key calls — an endpoint exercised solely from the Playground
tab or the app will look unused. Per-version last_executed_at is recorded only for runs since
that tracking was added, so a version can read null while still being used; always confirm before
removing.
Workflow
1. List endpoints and their metadata
One execute-sql query gets the whole inventory from system.data_modeling_endpoints:
SELECT name, is_active, current_version, derived_from_insight, last_executed_at
FROM system.data_modeling_endpoints
ORDER BY name
No rows → the project has no endpoints; say so and stop. Don't invent issues. (The
last_executed_at column here is a convenience endpoint-level timestamp; for call frequency and
cost, use query_log in the next step.)
2. Pull usage from query_log
query_log records every personal-API-key call, tagged with the endpoint name. One query gives
recency and call counts across all endpoints:
SELECT name, count() AS calls, max(query_start_time) AS last_called
FROM query_log
WHERE endpoint LIKE '%/endpoints/%' AND is_personal_api_key_request
GROUP BY name
ORDER BY name
Cross-reference with step 1:
In metadata, absent from query_log → never called via API key
Last call more than 30 days ago → stale
query_log also exposes query_duration_ms, read_rows, and read_bytes per call — useful to
flag expensive endpoints in the same pass. This is endpoint-level; per-version recency comes from
endpoint-versions (step 3).
3. Check materialisation health and unused versions
For each materialised endpoint, call endpoint-materialization-status (this isn't in the system
tables). Surface any with status: "Failed" separately — these are active failures, not staleness.
Then call endpoint-versions and read each version's last_executed_at: a materialised
version that's null or long stale is an unused-materialised-version candidate. Treat this as a
lead, not proof — per-version recency only counts API-key runs since tracking was added, so confirm
with the user before unmaterialising.
4. Present the audit
Render a prioritised report grouped by category. Don't dump raw JSON; use a readable table per
section:
## Endpoints audit — 9 issues
### 🔴 Failing materialisations (1)
- weekly_revenue (v3) — Failed 2h ago, "Column 'event_date' does not exist"
→ hand off to diagnosing-endpoint-performance
### 🟠 Never called via API key (3)
- internal_admin_query — created 5 months ago
- legacy_signup_funnel — created 1 year ago, materialised
- experiment_arm_lookup — created 9 months ago
### 🟠 Unused materialised versions (2) [from endpoint-versions]
- monthly_active_users — v3 materialised, last_executed_at null (currently on v4 — unmaterialise v3)
- order_summary — v1 materialised, last_executed_at null
### 🟡 Stale (3)
- holiday_promo_2024 — last called 4 months ago
- ab_test_phase_1 — last called 2 months ago
- daily_revenue_cohort — last called 45 days ago
Recommended order:
1. Investigate the failing materialisation (blocks fresh data)
2. Unmaterialise the unused versions (free storage + compute)
3. Disable the never-called endpoints (if user confirms)
4. Review stale endpoints with the user
The exact format is less important than: prioritised, grouped, actionable, and hand-off
clear.
5. Offer the next step
End with a clear question, not a decision:
"Want me to unmaterialise the unused versions?" — needs endpoint-update with
is_materialized: false per version
"Want me to disable the never-called endpoints?" — needs endpoint-update with is_active: false
"Want me to dig into the failing materialisation?" — hands off to
diagnosing-endpoint-performance
Never act from the audit alone. Disabling or unmaterialising affects external API consumers;
always confirm before modifying.
Example interaction
User: "Audit my endpoints"
Agent steps:
- execute-sql on system.data_modeling_endpoints → 12 endpoints (4 materialised)
- execute-sql on query_log grouped by name → 8 endpoints have calls
- endpoint-materialization-status on each materialised endpoint → 1 failing
- endpoint-versions on the materialised ones → order_summary v2's last_executed_at is null
- Report:
"Found 6 things worth looking at across 12 endpoints:
🔴 Failing materialisations (1)
- monthly_active_users (v2) — materialisation failed yesterday with
'memory limit exceeded'. The endpoint is still callable inline but
responses will be slower.
🟠 Never called via API key (3)
- legacy_funnel_v1 — created 11 months ago
- test_export — created 3 months ago
- admin_dump — created 8 months ago, materialised (wasteful)
🟠 Unused materialised versions (1) [from endpoint-versions]
- order_summary v2 — materialised but its last_executed_at is null
while v3 is current. Likely safe to unmaterialise v2.
🟡 Stale (1)
- holiday_2024 — last called 5 months ago
Caveat: usage only counts personal-API-key calls; playground and
dashboard runs aren't counted. Per-version recency comes from
endpoint-versions and is sparse. Confirm before disabling.
Want me to start with the failing materialisation, or clean up the
unused version first?"
Important notes
The audit is read-only. Never call destructive tools from this flow. Hand off or confirm
before any modification.
Empty = healthy. Don't pad an empty report with theoretical issues. "Nothing to clean up"
is a good answer.
Read with SQL, drill in with the version tool.system.data_modeling_endpoints (metadata)
and query_log (endpoint-level call counts, recency, cost) via execute-sql answer most of the
audit. Per-version recency comes from endpoint-versions (each version's last_executed_at).
API-key-only scope. Usage only counts personal-API-key calls. An endpoint exercised only from
the Playground tab or the app will look unused. Always confirm before acting.
Materialisation costs storage and compute. When an endpoint no longer needs materialisation,
the cheapest fix is endpoint-update with is_materialized: false — not deleting the endpoint.
Inactive ≠ stale. An endpoint with is_active: false was deliberately turned off. Don't
recommend deletion unless the user confirms it's truly abandoned.
MCP connection required
1 FOR YOU
01
Connect the PostHog MCP
Connect the PostHog MCP server to a project that uses the Endpoints product so the skill can call execute-sql, endpoint-materialization-status, and endpoint-versions.
🔌 This skill ships inside the PostHog AI Plugin. Listed package contents include 3 slash commands, 1 agent, hooks and an MCP server. Installed components and skill versions may vary by AI tool.
Install just this skill
Run this outside your AI tool, using Node.js 22.20.0 or newer. Skills CLI 1.7.2 skips skill selection; prompts cancel installation without an interactive terminal. If choosing Project when asked about installation scope, open your project's folder before running this.
Install checklist
Check selected tools if a picker appears; Claude Code may be unchecked under Additional agents. ↑/↓ moves, Space toggles selections, Enter confirms.
Without a tool picker, check Installing to: for your intended tool. Stop if it names a different tool.
If asked, choose Symlink (Recommended) for shared files or Copy to all agents for separate copies; review the summary before confirming installation.
Install the find-skills skill? defaults to Yes, adding another skill for all projects. Choose No if you don't want that extra installation.
Skills CLI 1.7.2 sends install data to skills.sh by default, including the source, skill names, target tools and file details; GitHub sources are reported only when GitHub confirms the repository is public, while other remote sources can also be reported. Confirmed-public GitHub sources also trigger a security-audit request. Before installing, set the environment variable DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 to disable both.
After installing for Claude Code, open it in the installation project if you chose Project; Global makes the skill available across projects on this computer. Once Claude Code loads the skill, its description helps Claude decide when to use it.
If installation created a top-level skills folder that did not exist when your Claude Code session started, run /reload-skills in that session. Run it again after later changes in that folder.
MCP server required
The skill's steps call for tools from the PostHog MCP server. Installing just this skill doesn't add that connection; set it up in your AI tool if it isn't there yet: PostHog MCP setup. Installing the whole plugin instead includes the connection settings.
Requirements for the PostHog MCP server
Connecting is free; sign in with your PostHog account.
Some tools use AI internally and may incur PostHog AI charges. Those tools require AI data processing to be enabled in your organization settings.
Install the whole plugin
This route installs the posthog plugin package selected for your AI tool.
Claude Code
Add PostHog's marketplace, then install the plugin
Run both lines in a terminal. They install PostHog's posthog plugin: this skill, PostHog's other skills, and a connection to PostHog's hosted MCP server.
01
claude plugin marketplace add PostHog/ai-plugin
02
claude plugin install posthog@posthog
Installation and loading
The plugin installs for you in every project and loads the next time you start Claude Code, or after /reload-plugins in an open session.
To connect your PostHog account, start claude, type /mcp, select plugin:posthog:posthog and follow the browser prompts.
Good to know
The plugin includes PostHog's session-capture hook; PostHog's README says it sends sessions to LLM Analytics only when POSTHOG_LLMA_CC_ENABLED=true and POSTHOG_API_KEY are both set.
If you use the separate posthog-telemetry plugin, PostHog says to keep only one of the two, because both register the same hook.
On a self-hosted PostHog, this route's MCP connection won't reach your instance: the plugin's config is fixed to https://mcp.posthog.com/mcp, which routes to PostHog's US or EU region. POSTHOG_MCP_URL works only for the Gemini CLI extension.
Sync columns from a synced data warehouse table onto PostHog person or group properties, so warehouse data becomes usable anywhere person and group properties already work: feature flag targeting, cohorts, insight filters and breakdowns, surveys, session replay filters, workflows, and the person profile. Use when the user wants to "add a person property from my warehouse", "enrich people with Stripe/Postgres/Salesforce data", "put ARR or plan tier on my persons", "target a feature flag by a warehouse column", "sync warehouse columns onto groups or organizations", or wants to inspect, backfill, disable, or debug an existing warehouse-backed person or group property.Read full description
Analyze the most expensive users in AI observability and explain why they cost so much. Use when the user asks about top spenders, expensive users, per-user LLM cost, user-level cost drivers, or patterns behind high AI observability spend.Read full description
Analyze session replay patterns across experiment variants to understand user behavior differences. Use when the user wants to see how users interact with different experiment variants, identify usability issues, compare behavior patterns between control and test groups, or get qualitative insights to complement quantitative experiment results. Also covers pairing the observed behavior with a linked survey when the user wants qualitative feedback beyond what recordings show.Read full description
Assesses what a page's heatmap is telling you and recommends concrete changes. Pulls click / rageclick / scroll-depth data for a URL, names the hot elements by cross-referencing autocapture events on the same page, and can create a saved heatmap the user opens in PostHog, then summarizes the behavior and proposes improvements.
TRIGGER when: user asks what a heatmap shows, why people aren't clicking something, where users rage-click, how far they scroll, what to change on a page based on heatmap/click data, or to 'analyze/assess/review the heatmap' for a URL.
DO NOT TRIGGER when: the user only wants to create a saved heatmap screenshot with no analysis (use heatmaps-saved-create directly), or is asking about session replay in general (use investigating-replay).Read full description
Audit PostHog experiments and feature flags for configuration issues, staleness, and best-practice violations. Read when the user asks to audit, health-check, or review experiments or feature flags, check flag hygiene, or verify experiment setup.Read full description
Audit the health of a PostHog project's data warehouse sources and syncs — find every broken or degraded source connection, sync schema, and webhook channel. Use when the user asks "why are my imports failing?", "what's broken with my sources?", "why is my warehouse data stale?", or wants a one-shot triage of source/sync health before deciding where to dig in. Produces a prioritized report grouped by severity, with recommended next steps. For materialized-view health use auditing-warehouse-view-health; for a single failing sync use diagnosing-failed-warehouse-syncs.Read full description
