posthog

name

posthog

description

How to use the PostHog connector's tools — running HogQL/SQL queries, reading events and persons, pulling trends, funnels, and retention, and inspecting insights, dashboards, feature flags, and annotations. Use when the user asks about product analytics, usage metrics, conversion, churn, active users, funnels, retention cohorts, event volume, feature-flag rollout, or "what does PostHog say about X".

You are using the PostHog connector (via Composio). Its tools act on the connected PostHog account's analytics data. Apply this guidance whenever you touch PostHog. This is a read-leaning working set — most tools query and inspect; a few can mutate, called out under Care.

Trust the live tool list, not these names

• This connector exposes many tools, all slugged POSTHOG_*. The exact slug names vary and change — look them up in your available tools and read each tool's schema before calling it. Don't invent a slug or a parameter from the shape of a name you remember; match against the real list and confirm the fields the schema asks for.

Resolve the project first

• Almost every tool is scoped to a project and needs a project id. Don't guess it — call the list-projects tool once to resolve the human name ("Production", "the web app") into an id, then pass that id to every subsequent call.

HogQL is the power tool

• For anything ad-hoc or cross-cutting, prefer the query tool with a HogQL query (kind: "HogQLQuery", query: "SELECT ..."). HogQL is PostHog's SQL dialect over ClickHouse: SELECT … FROM events | persons | sessions WHERE … GROUP BY … ORDER BY … LIMIT ….
• Event/person props are nested: properties.$browser, person.properties.email. Auto-joins resolve events.person.properties.* for you.
• Always bound the time range and keep it tight — timestamp > now() - INTERVAL 7 DAY, dateDiff(...), etc. Unbounded scans over events are slow and expensive. Always add a LIMIT.
• Heavy queries may run async: the create-query call returns a status with an id; poll the async-status tool until complete, then read results. Don't re-issue the query while one is pending.

Pre-built analytics vs. raw query

• For standard shapes, prefer the purpose-built trends, funnels, and retention tools over hand-rolled HogQL. They return results in PostHog's native insight shape and match what the user sees in the UI.
• To discover what events/properties even exist, use the event-definitions / property-definitions tools before filtering — event names are case-sensitive and project-specific ($pageview, $autocapture, custom names).

Inspecting saved work

• Insights are saved analyses: list them (with pagination), then fetch one by id for its full config/results. Reuse a saved insight instead of re-deriving its numbers when the user references it.
• Dashboards, feature flags, and annotations each have a list tool and a get-by-id tool — list to resolve a name to an id, then read details.

Care

• This set is read-leaning, but some endpoints can mutate — deleting persons, toggling or deleting feature flags, capturing events, editing annotations or insights. Default to the read path; only delete/modify when the user explicitly asks, and confirm scope first. Deleting a person is irreversible, and toggling a feature flag is immediately live to real users.
• Numbers are only as good as the filters. State your time window, project, and any event/property filters when reporting a figure, so the user can trust it.
• Large result sets: page through (limit/offset or the cursor the tool returns) and summarize rather than dumping every row. Add a LIMIT to every HogQL query as a backstop.
• Don't fabricate an event, property, flag, or insight name. If a lookup returns nothing, say it wasn't found (it may not exist or not be tracked) instead of guessing a plausible name.