posthog

When this skill is activated, always start your first response with the 🧢 emoji.

PostHog

PostHog is an open-source product analytics platform that combines product analytics, web analytics, session replay, feature flags, A/B testing, error tracking, surveys, and LLM observability into a single platform. It can be self-hosted or used as a cloud service (US or EU). Agents interact with PostHog primarily through its JavaScript, Node.js, or Python SDKs for client/server-side instrumentation, and through its REST API for querying data and managing resources.

When to use this skill

Trigger this skill when the user:

• Wants to capture custom events or identify users with PostHog
• Needs to set up or evaluate feature flags (boolean, multivariate, or remote config)
• Wants to create or manage A/B tests and experiments
• Asks about session replay setup or configuration
• Needs to create or customize in-app surveys
• Wants to set up error tracking or exception autocapture
• Needs to query analytics data via the PostHog API
• Asks about group analytics, cohorts, or person properties

Do NOT trigger this skill for:

• General analytics strategy that doesn't involve PostHog specifically
• Competing tools like Amplitude, Mixpanel, or LaunchDarkly unless comparing

Setup & authentication

Environment variables

# Required for all SDKs
POSTHOG_API_KEY=phc_your_project_api_key

# Required for server-side private API access
POSTHOG_PERSONAL_API_KEY=phx_your_personal_api_key

# Host (defaults to US cloud)
POSTHOG_HOST=https://us.i.posthog.com

PostHog has two API types:

• Public endpoints (/e, /flags) - use project API key (starts with phc_), no rate limits
• Private endpoints (CRUD) - use personal API key (starts with phx_), rate-limited

Cloud hosts:

• US: https://us.i.posthog.com (public) / https://us.posthog.com (private)
• EU: https://eu.i.posthog.com (public) / https://eu.posthog.com (private)

Installation

# JavaScript (browser)
npm install posthog-js

# Node.js (server)
npm install posthog-node

# Python
pip install posthog

Basic initialization

// Browser - posthog-js
import posthog from 'posthog-js'
posthog.init('phc_your_project_api_key', {
  api_host: 'https://us.i.posthog.com',
  person_profiles: 'identified_only',
})

// Node.js - posthog-node
import { PostHog } from 'posthog-node'
const client = new PostHog('phc_your_project_api_key', {
  host: 'https://us.i.posthog.com',
})
// Flush before process exit
await client.shutdown()

# Python
from posthog import Posthog
posthog = Posthog('phc_your_project_api_key', host='https://us.i.posthog.com')

Core concepts

PostHog's data model centers on events, persons, and properties:

• Events are actions users take (page views, clicks, custom events). Each event

has a distinct_id (user identifier), event name, timestamp, and optional properties. PostHog autocaptures pageviews, clicks, and form submissions by default in the JS SDK.

• Persons are user profiles built from events. Use posthog.identify() to link

anonymous and authenticated sessions. Person properties ($set, $set_once) store user attributes for segmentation and targeting.

• Groups let you associate events with entities like companies or teams, enabling

B2B analytics. Groups require a group type (e.g., company) and a group key.

• Feature flags control feature rollout with boolean, multivariate, or remote config

types. Flags evaluate against release conditions (user properties, cohorts, percentages). Local evaluation on the server avoids network round-trips.

• Insights are analytics queries: Trends, Funnels, Retention, Paths, Lifecycle,

and Stickiness. They power dashboards for product analytics and web analytics.

Common tasks

Capture a custom event

// Browser
posthog.capture('purchase_completed', {
  item_id: 'sku_123',
  amount: 49.99,
  currency: 'USD',
})

// Node.js
client.capture({
  distinctId: 'user_123',
  event: 'purchase_completed',
  properties: { item_id: 'sku_123', amount: 49.99 },
})

# Python
posthog.capture('user_123', 'purchase_completed', {
    'item_id': 'sku_123',
    'amount': 49.99,
})

Identify a user and set properties

// Browser - link anonymous ID to authenticated user
posthog.identify('user_123', {
  email: 'user@example.com',
  plan: 'pro',
})

// Set properties later without an event
posthog.people.set({ company: 'Acme Corp' })

# Python
posthog.identify('user_123', {
    '$set': {'email': 'user@example.com', 'plan': 'pro'},
    '$set_once': {'first_seen': '2026-03-14'},
})

Evaluate a feature flag

// Browser - async check
posthog.onFeatureFlags(() => {
  if (posthog.isFeatureEnabled('new-checkout')) {
    showNewCheckout()
  }
})

// Get multivariate value
const variant = posthog.getFeatureFlag('checkout-experiment')

// Node.js - with local evaluation (requires personal API key)
const client = new PostHog('phc_key', {
  host: 'https://us.i.posthog.com',
  personalApiKey: 'phx_your_personal_api_key',
})

const enabled = await client.isFeatureEnabled('new-checkout', 'user_123')
const variant = await client.getFeatureFlag('checkout-experiment', 'user_123')

# Python - with local evaluation
posthog = Posthog('phc_key', host='https://us.i.posthog.com',
                   personal_api_key='phx_your_personal_api_key')
enabled = posthog.get_feature_flag('new-checkout', 'user_123')

Feature flag local evaluation polls every 5 minutes by default. Configure with

featureFlagsPollingInterval (Node) or poll_interval (Python).

Get feature flag payload

// Browser
const payload = posthog.getFeatureFlagPayload('my-flag')

// Node.js
const payload = await client.getFeatureFlagPayload('my-flag', 'user_123')

Capture events with group analytics

// Browser - associate event with a company group
posthog.group('company', 'company_id_123', {
  name: 'Acme Corp',
  plan: 'enterprise',
})
posthog.capture('feature_used', { feature: 'dashboard' })

# Python
posthog.capture('user_123', 'feature_used',
    properties={'feature': 'dashboard'},
    groups={'company': 'company_id_123'})

posthog.group_identify('company', 'company_id_123', {
    'name': 'Acme Corp',
    'plan': 'enterprise',
})

Query data via the private API

# List events for a person
curl -H "Authorization: Bearer phx_your_personal_api_key" \
  "https://us.posthog.com/api/projects/:project_id/events/?person_id=user_123"

# Get feature flag details
curl -H "Authorization: Bearer phx_your_personal_api_key" \
  "https://us.posthog.com/api/projects/:project_id/feature_flags/"

# Create an annotation
curl -X POST -H "Authorization: Bearer phx_your_personal_api_key" \
  -H "Content-Type: application/json" \
  -d '{"content": "Deployed v2.0", "date_marker": "2026-03-14T00:00:00Z"}' \
  "https://us.posthog.com/api/projects/:project_id/annotations/"

Private API rate limits: 240/min for analytics, 480/min for CRUD, 2400/hr for

queries. Limits are organization-wide across all keys.

Set up error tracking (Python)

from posthog import Posthog

posthog = Posthog('phc_key',
    host='https://us.i.posthog.com',
    enable_exception_autocapture=True)

# Manual exception capture
try:
    risky_operation()
except Exception as e:
    posthog.capture_exception(e)

Serverless environment setup

// Node.js Lambda - flush immediately
const client = new PostHog('phc_key', {
  host: 'https://us.i.posthog.com',
  flushAt: 1,
  flushInterval: 0,
})

export async function handler(event) {
  client.capture({ distinctId: 'user', event: 'lambda_invoked' })
  await client.shutdown()
  return { statusCode: 200 }
}

Error handling

| Error | Cause | Re