PostHog REST API Reference

Authentication

Two authentication methods:

Type	Key prefix	Used for	Rate limited
Project API key	phc_	Public endpoints (event capture, flag eval)	No
Personal API key	phx_	Private endpoints (CRUD, queries)	Yes

Public endpoints accept the project API key in the request body:

{ "api_key": "phc_your_key", "distinct_id": "user_123" }

Private endpoints use Bearer auth:

Authorization: Bearer phx_your_personal_api_key

---

Base URLs

Deployment	Public (capture/flags)	Private (API)
US Cloud	https://us.i.posthog.com	https://us.posthog.com
EU Cloud	https://eu.i.posthog.com	https://eu.posthog.com
Self-hosted	Your instance domain	Your instance domain

---

Rate limits (private endpoints)

Endpoint type	Limit
Analytics endpoints	240/minute, 1200/hour
Query endpoint	2400/hour
Feature flag local evaluation	600/minute
CRUD operations	480/minute, 4800/hour

Limits apply organization-wide across all users and API keys.

---

Pagination

All list endpoints return paginated results:

{
  "count": 150,
  "next": "https://us.posthog.com/api/projects/1/events/?limit=100&offset=100",
  "previous": null,
  "results": [...]
}

Default page size: 100 items. Follow next URL to get subsequent pages.

---

Key public endpoints

Capture events - POST /i/v0/e

curl -X POST "https://us.i.posthog.com/i/v0/e" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "phc_key",
    "event": "purchase",
    "distinct_id": "user_123",
    "properties": {
      "amount": 49.99,
      "$current_url": "https://example.com/checkout"
    },
    "timestamp": "2026-03-14T10:00:00Z"
  }'

Batch capture - POST /batch

curl -X POST "https://us.i.posthog.com/batch" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "phc_key",
    "batch": [
      {"event": "pageview", "distinct_id": "user_1", "timestamp": "2026-03-14T10:00:00Z"},
      {"event": "click", "distinct_id": "user_2", "timestamp": "2026-03-14T10:00:01Z"}
    ]
  }'

Evaluate feature flags - POST /decide?v=3

curl -X POST "https://us.i.posthog.com/decide?v=3" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "phc_key",
    "distinct_id": "user_123",
    "person_properties": {"plan": "pro"}
  }'

Returns:

{
  "featureFlags": {"new-checkout": true, "experiment": "variant-a"},
  "featureFlagPayloads": {"app-config": "{\"theme\":\"dark\"}"}
}

---

Key private endpoints

All private endpoints follow the pattern:

https://us.posthog.com/api/projects/:project_id/<resource>/

Events

# List events
GET /api/projects/:id/events/
GET /api/projects/:id/events/?event=purchase&person_id=user_123

# Get single event
GET /api/projects/:id/events/:event_id/

Persons

# List persons
GET /api/projects/:id/persons/

# Search persons
GET /api/projects/:id/persons/?search=user@example.com

# Get person by distinct ID
GET /api/projects/:id/persons/?distinct_id=user_123

# Delete a person
DELETE /api/projects/:id/persons/:person_id/

Feature flags

# List flags
GET /api/projects/:id/feature_flags/

# Create a flag
POST /api/projects/:id/feature_flags/
{
  "key": "new-checkout",
  "name": "New checkout flow",
  "active": true,
  "filters": {
    "groups": [{"properties": [], "rollout_percentage": 50}]
  }
}

# Update a flag
PATCH /api/projects/:id/feature_flags/:flag_id/

# Delete a flag
DELETE /api/projects/:id/feature_flags/:flag_id/

Experiments

# List experiments
GET /api/projects/:id/experiments/

# Create an experiment
POST /api/projects/:id/experiments/
{
  "name": "Signup flow test",
  "feature_flag_key": "signup-experiment",
  "filters": {...}
}

Dashboards

# List dashboards
GET /api/projects/:id/dashboards/

# Create a dashboard
POST /api/projects/:id/dashboards/
{ "name": "Product metrics", "description": "Key KPIs" }

Insights (saved queries)

# List insights
GET /api/projects/:id/insights/

# Create a trend insight
POST /api/projects/:id/insights/
{
  "name": "Daily active users",
  "filters": {
    "insight": "TRENDS",
    "events": [{"id": "$pageview", "math": "dau"}],
    "date_from": "-30d"
  }
}

Cohorts

# List cohorts
GET /api/projects/:id/cohorts/

# Create a cohort
POST /api/projects/:id/cohorts/
{
  "name": "Power users",
  "groups": [{"properties": [{"key": "plan", "value": "pro", "type": "person"}]}]
}

Annotations

# Create an annotation (e.g. deployment marker)
POST /api/projects/:id/annotations/
{
  "content": "Deployed v2.0",
  "date_marker": "2026-03-14T00:00:00Z",
  "scope": "project"
}

---

Response codes

Code	Meaning
200	Success (for capture: payload received, not guaranteed ingested)
400	Bad request - invalid payload or project ID
401	Unauthorized - invalid API key
404	Resource not found
429	Rate limited - back off and retry
503	Database unavailable (self-hosted only)

---

Query API (HogQL)

PostHog supports HogQL for custom queries:

POST /api/projects/:id/query/
{
  "query": {
    "kind": "HogQLQuery",
    "query": "SELECT count() FROM events WHERE event = 'purchase' AND timestamp > now() - interval 7 day"
  }
}

HogQL is a SQL-like language that queries PostHog's ClickHouse backend. It supports standard SQL functions plus PostHog-specific functions for working with properties.

PostHog Feature Flags & Experiments

Feature flag types

Boolean (release toggle)

Returns true when enabled and conditions match, false when disabled, or undefined/null when conditions don't match.

if (posthog.isFeatureEnabled('new-checkout')) {
  renderNewCheckout()
}

Multivariate

Returns a variant key string (e.g. control, test, variant-a). Each variant has a configurable rollout percentage that must total 100%.

const variant = posthog.getFeatureFlag('checkout-experiment')
if (variant === 'test') {
  renderTestCheckout()
} else {
  renderControlCheckout()
}

Remote config

Delivers a static configuration value consistently to all matching users. Does not support percentage-based rollouts. Used for dynamic configuration without deploys.

const config = posthog.getFeatureFlagPayload('app-config')
// Returns the JSON payload attached to the flag

---

Release conditions

Conditions evaluate top-to-bottom, first match wins. Options:

• Match by user (default) - target individual persons by properties
• Match by device - target by device properties
• Match by group - target by group properties (requires group analytics)

Filters available:

• Person properties (exact, contains, regex, is set/not set)
• Cohort membership
• Geographic location (country, city)
• Semantic version comparisons (for app version targeting)
• Percentage rollout (0-100%)

---

Local evaluation (server-side)

Local evaluation avoids a network call per flag check by polling flag definitions and evaluating them locally. Requires a personal API key.

// Node.js
const client = new PostHog('phc_key', {
  host: 'https://us.i.posthog.com',
  personalApiKey: 'phx_personal_key',
  featureFlagsPollingInterval: 30000, // poll every 30s (default: 300000ms / 5min)
})

// This evaluates locally - no network call
const flag = await client.getFeatureFlag('my-flag', 'user_123', {
  personProperties: { plan: 'pro', country: 'US' },
  groupProperties: { company: { name: 'Acme' } },
})

# Python
posthog = Posthog('phc_key',
    host='https://us.i.posthog.com',
    personal_api_key='phx_personal_key',
    poll_interval=30)  # seconds

flag = posthog.get_feature_flag('my-flag', 'user_123',
    person_properties={'plan': 'pro'},
    group_properties={'company': {'name': 'Acme'}})

Important: When using local evaluation, you must provide personProperties and groupProperties that match the conditions. If a flag condition uses a property you didn't provide, it falls back to a remote API call.

Rate limit for local evaluation polling: 600 requests/minute.

---

Bootstrapping (client-side)

Bootstrap flags on page load to avoid flickering. Pass flag values from server-side rendering.

posthog.init('phc_key', {
  api_host: 'https://us.i.posthog.com',
  bootstrap: {
    distinctID: 'user_123',
    featureFlags: {
      'new-checkout': true,
      'checkout-experiment': 'test',
    },
    featureFlagPayloads: {
      'app-config': { theme: 'dark' },
    },
  },
})

The distinctID in bootstrap must match the user's actual distinct ID. If it doesn't, flags will be re-fetched from the server, causing a flash.

---

Experiments / A/B testing

Experiments are built on top of feature flags with statistical analysis.

Creating an experiment

1. Create a multivariate feature flag with control and test variants
2. Create an experiment linked to that flag
3. Define a goal metric (trend, funnel, or secondary metrics)
4. Set minimum sample size and run duration
5. Launch the experiment (activates the linked flag)

Evaluating in code

Experiments use the same flag evaluation methods:

const variant = posthog.getFeatureFlag('signup-experiment')
if (variant === 'test') {
  renderNewSignupFlow()
}
// PostHog automatically tracks exposure via $feature_flag_called event

Statistical significance

PostHog uses a Bayesian approach to calculate statistical significance. Results show win probability and credible intervals. The experiment dashboard indicates when significance is reached.

---

Feature flag best practices

1. Use descriptive keys - new-checkout-flow not flag-1
2. Clean up stale flags - remove flags after full rollout to reduce evaluation overhead
3. Use local evaluation server-side - avoids latency and API dependency for critical paths
4. Bootstrap client-side - prevents UI flickering on page load
5. Provide person properties for local eval - missing properties trigger remote fallback
6. Use payloads for configuration - attach JSON payloads to flags instead of hardcoding values

---

Feature Flags API

# List all flags
curl -H "Authorization: Bearer phx_key" \
  "https://us.posthog.com/api/projects/:project_id/feature_flags/"

# Get a specific flag
curl -H "Authorization: Bearer phx_key" \
  "https://us.posthog.com/api/projects/:project_id/feature_flags/:id/"

# Evaluate flags for a user (public endpoint)
curl -X POST "https://us.i.posthog.com/decide?v=3" \
  -H "Content-Type: application/json" \
  -d '{"api_key": "phc_key", "distinct_id": "user_123"}'

The /decide endpoint returns all active flags and their values for a given user. This is what the SDKs call internally.

PostHog Surveys, Session Replay, Web Analytics & More

Surveys

Survey types

• Popover - prebuilt UI in the bottom corner of the screen
• API - custom UI, PostHog handles targeting logic and analytics
• Feedback button - persistent tab for collecting feedback
• Hosted - external URL or iframe-embedded, anonymous by default

Question types

1. Freeform text
2. Link/notification (display-only)
3. Rating - emoji scale
4. Rating - number scale
5. Single choice select
6. Multiple choice select

Display conditions

• Feature flag targeting
• URL matching
• Device type filtering
• CSS selector matching
• Wait periods between viewings
• Person/group property targeting
• Event-based triggers

Creating surveys via API

POST /api/projects/:id/surveys/
{
  "name": "NPS Survey",
  "type": "popover",
  "questions": [
    {
      "type": "rating",
      "question": "How likely are you to recommend us?",
      "scale": 10,
      "lowerBoundLabel": "Not likely",
      "upperBoundLabel": "Very likely"
    }
  ],
  "conditions": {
    "url": "https://example.com/dashboard"
  },
  "start_date": "2026-03-14T00:00:00Z"
}

Handling surveys in code (API mode)

// Get active surveys for the current user
posthog.getActiveMatchingSurveys((surveys) => {
  surveys.forEach(survey => {
    // Render custom survey UI
    renderSurvey(survey)
  })
})

// Send survey response
posthog.capture('survey sent', {
  $survey_id: 'survey_uuid',
  $survey_response: 'Great product!',
  $survey_response_1: 9, // for multi-question surveys
})

Repeating surveys

Surveys can repeat via event triggers, scheduled intervals, or when display conditions are met again. Partial responses are tracked by default with a unique submission ID per attempt.

---

Session replay

Session replay records user sessions as replayable videos. It captures DOM changes, mouse movements, clicks, console logs, and network requests.

Setup (browser)

Session replay is enabled by default with posthog-js. Configure it during init:

posthog.init('phc_key', {
  api_host: 'https://us.i.posthog.com',
  session_recording: {
    maskAllInputs: true,        // mask input values
    maskTextContent: false,      // mask text content
    recordCrossOriginIframes: false,
  },
})

Conditional recording

Record only specific sessions to reduce volume:

posthog.init('phc_key', {
  api_host: 'https://us.i.posthog.com',
  disable_session_recording: true, // disable by default
})

// Start recording programmatically
posthog.startSessionRecording()

Replay triggers

PostHog can automatically start recording when specific events are queued, capturing a buffer of activity before the trigger event.

Privacy controls

• maskAllInputs: true - replaces input values with asterisks
• maskTextContent: true - masks all text content
• Add ph-no-capture class to any element to exclude it from recording
• Add ph-mask class to mask specific elements

---

Web analytics

PostHog web analytics provides a Google Analytics-like dashboard with:

• Pageviews, unique visitors, sessions
• Bounce rate, session duration
• Traffic sources, UTM parameters
• Device, browser, OS, and location breakdowns
• Entry/exit pages

Web analytics uses autocaptured $pageview events and requires no additional setup beyond the standard JS SDK installation. The dashboard is available at /web in your PostHog instance.

Key autocaptured events

• $pageview - page loads
• $pageleave - page exits (captures time on page)
• $autocapture - clicks, form submissions, input changes
• $rageclick - repeated rapid clicks (frustration signal)

UTM tracking

PostHog automatically captures UTM parameters from URLs:

• utm_source, utm_medium, utm_campaign, utm_term, utm_content
• Stored as properties on the $pageview event

---

Error tracking

PostHog captures JavaScript errors and unhandled exceptions automatically.

Browser setup

Error tracking is enabled by default in posthog-js. It captures:

• Unhandled exceptions
• Unhandled promise rejections
• Console errors (optional)

Python setup

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

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

Node.js setup

// Errors are captured via the SDK's error tracking module
// Manual capture
client.captureException(error, 'user_123')

---

LLM observability

PostHog provides observability for LLM-powered applications via the @posthog/ai package (Node.js) or built-in Python SDK support.

What it tracks

• LLM API calls (model, tokens, latency, cost)
• Prompt/completion content (optional, can be masked)
• Error rates and failure modes
• Token usage over time

Node.js setup

import { PostHogAI } from '@posthog/ai'
import OpenAI from 'openai'

const openai = new PostHogAI(new OpenAI(), posthogClient)
// Use openai as normal - PostHog wraps and tracks all calls

Python setup

LLM analytics are built into the Python SDK with context managers and decorators for tracking LLM calls.

---

Data warehouse

PostHog includes a built-in data warehouse that can:

• Import data from external sources (Stripe, Hubspot, Postgres, S3, etc.)
• Join external data with PostHog events and persons
• Query everything with HogQL

External data sources

POST /api/projects/:id/external_data_sources/
{
  "source_type": "Stripe",
  "job_inputs": {
    "stripe_secret_key": "sk_..."
  }
}

This syncs Stripe data (charges, customers, invoices) into PostHog's warehouse for cross-referencing with product analytics.