PostHog

PostHog

PostHog organizes everything under Organizations → Projects. Most API calls are project-scoped, and the default project is auto-selected. Only switch organization or project if the user explicitly asks.

Data Model

• Events are the atomic unit — every pageview, click, or custom action is an event with properties.
• Event Definitions describe what events exist. Always discover available events before writing queries.
• Properties are metadata on events (event type) or users (person type). Discover them before filtering or breaking down.
• Insights are saved queries — trends, funnels, retention, paths. Query an existing insight rather than rebuilding it from scratch.
• Dashboards are collections of insights arranged as tiles.
• Feature Flags control rollouts with percentage-based or property-based targeting. They can be boolean or multivariate.
• Experiments are A/B tests tied to feature flags. Each experiment has a linked flag, variants, and success metrics.
• Surveys are in-app popover or API-based questionnaires with targeting and scheduling.
• Session Recordings capture user sessions as rrweb replay data. Retrieving snapshot data is a two-step process: first get blob keys, then fetch blob content.

Gotchas

• $pathname vs $current_url: For URL breakdowns, use $pathname (normalized path) instead of $current_url (includes query params) for cleaner results.
• Breakdown limits: Default breakdown limit is 25 values. Set breakdown_limit to 100+ to see more.
• Session snapshots are two-step: First request with only session_id to obtain blob keys, then repeat with source, start_blob_key, and end_blob_key to retrieve snapshot bytes.
• Experiment results vs experiment details: The experiment object doesn't include statistical results. Fetch the dedicated experiment-results payload when you need outcomes.
• Feature flag deletion is permanent: Cannot be undone. Prefer disabling (set inactive) over deleting.
• Insight creation: Always execute an insight query in draft before saving it as an insight. Don't save untested query definitions.