PostHog integration

Overview

PostHog is open-source product analytics + feature flags + session replay. The Automize connector covers event capture, cohorts, feature flags (CRUD + decide), persons, insights, projects, and the HogQL query engine.

• Regions: Cloud: us.posthog.com and eu.posthog.com – pick at project creation, can't change later. Self-hosted: any host you point the connector at.
• Plans: Free tier covers 1M events/month, 1M flag decisions/month, 5k session recordings. Paid tiers raise limits and unlock enterprise SSO, advanced permissions, and SLA.

Setting up the connection

Auth type: Bearer Token.

1. Personal API key for admin operations (cohorts, flags, insights): Profile → Settings → Personal API Keys → Create. Pick scopes (e.g. 'projects:read', 'feature_flag:write').
2. Project API key for ingest (capture / decide / batch): Project Settings → Project Variables → Project API Key (phc_...). Different from the personal key.
3. Paste the personal API key as the API token here. The connector uses it for management calls and accepts a separate project API key for ingest where required.

Find your credentials at https://app.posthog.com/me/settings#personal-api-keys.

Rate limits

Capture: 1000 events/batch, ~10k req/sec/team. Management endpoints: ~480 req/min per personal API key. HogQL queries: 60s execution timeout, longer windows return 'query took too long'. Connector backs off on 429.

Data model

PostHog's analytics graph:

    Organization
      └─ Projects                (ingest is project-scoped)
           ├─ Events             (timestamped, properties dict)
           │    └─ Persons       (distinct_id → person record)
           ├─ Cohorts            (static or dynamic group of persons)
           ├─ Feature Flags
           │    ├─ Boolean       (on / off)
           │    └─ Multivariate  (named variants + rollouts)
           ├─ Insights           (saved chart definitions)
           ├─ Dashboards
           ├─ Experiments        (A/B tests built on feature flags)
           └─ Session Recordings

Two key/credential types:

    Project API Key (phc_...)   public, ingest only (capture/decide)
    Personal API Key            server-side, scoped, for management

Person identity model:

    Events arrive with a distinct_id (user identifier). PostHog
    resolves multiple distinct_ids to the same Person via $identify
    events. Properties on the Person persist across all of their
    distinct_ids; properties on Events are point-in-time.

HogQL is PostHog's SQL dialect over the events/persons tables –
Postgres-flavoured but with ClickHouse semantics underneath.
Queries time out at 60s; pre-aggregate via Insights for hot paths.

Available operations

14 operations available. Click any row to jump to its detail.

Operations

Capture Event

Ingest a single event (uses project_api_key, no auth header)

Tips

• Single event ingest. body: api_key (project key) + event + distinct_id + properties + timestamp (ISO 8601 / unix).
• If your event ingest is high-volume (>10 events/run), use Capture Batch instead.

Capture Batch

Ingest a batch of events

Tips

• Up to 1000 events / 20 MB. Each event needs distinct_id + event. Server-side ingest does NOT auto-populate $browser/$os – set them if you need them in funnels.

Create Cohort

Create a new cohort

Tips

• Dynamic cohort via filters: { properties: [{ key, value, operator, type }] } or behavioural: { events: [{ id, type, order, ... }], time_value, time_interval }.
• Static cohort via csv import – POST multipart with csv= file containing distinct_ids.
• Cohorts calculate async; poll List Cohorts → cohort.is_calculating until false before depending on count.

Create Feature Flag

Create a feature flag

Tips

• key + name + filters.groups[] (rollout rules). Multivariate flags need filters.multivariate.variants=[{key, name, rollout_percentage}].
• active=false creates the flag without serving it – useful for staged rollouts.

Evaluate Feature Flags

Evaluate flags for a distinct_id (server-side)

Tips

• POST /decide – server-side flag evaluation given a distinct_id + groups + person_properties. Returns the full {flag_key: value} map for the user.
• Cache responses by distinct_id (TTL ~60s) – calling decide() per request is fine but adds latency on hot paths.

Get Person

Get a single person

Tips

• GET /api/projects/{id}/persons/{person_id} – full person record. person_id is PostHog's internal UUID, NOT distinct_id.
• To look up by distinct_id, use List Persons with distinct_id=<id> filter.

List Cohorts

List cohorts in a project

Tips

• Returns saved cohorts. Pass cohort.is_calculating=false to filter only completed cohorts (calculation runs async after creation/update).

List Events

Query recent events for a project

Tips

• GET /api/projects/{id}/events – paginated. Filter by event=<name>, distinct_id=<id>, after=<iso>, before=<iso>.
• Cursor-based pagination via 'next' URL. Default 100/page. Heavy queries – for analytics, use Run Query (HogQL) instead.

List Feature Flags

List feature flags in a project

Tips

• Returns all flags in the project. active=true|false filter. Each flag includes its filters (rollout groups), variants (for multivariate), and current rollout_percentage.

List Insights

List saved insights / queries

Tips

• Saved chart/funnel/retention definitions. Filter by saved=true, dashboards=<id>, insight=TRENDS|FUNNELS|RETENTION|PATHS|HOG.
• Each insight has a 'filters' dict you can re-use as the basis for a HogQL query – Run Query against the same filters for fresh data.

List Persons

Query persons (users) in a project

Tips

• Filter by distinct_id, search (matches name/email properties), cohort (cohort ID), properties_filter.
• Each person record exposes all distinct_ids merged into them via $identify.

List Projects

List projects on the account

No input parameters.

Tips

• Returns projects in the organisation. api_token field IS the project API key (phc_...) – useful for cross-project automation.
• Personal API key needs 'project:read' scope to see this.

Run HogQL Query

Run an ad-hoc HogQL query against the project

Tips

• HogQL – Postgres-flavoured SQL over events / persons. SELECT count() FROM events WHERE event='$pageview' AND timestamp > now() - INTERVAL 7 DAY.
• Heavy queries time out at 60s – pre-filter aggressively, use Cohorts for repeat queries.

Update Feature Flag

Update a feature flag

Tips

• PATCH /api/projects/{id}/feature_flags/{flag_id}. Pass only the fields that change. Toggle rollout via filters.groups[0].rollout_percentage.

FAQ

Personal vs Project key – when to use which?

Project key (phc_...) is for ingest only (capture, decide). Public-safe – embedded in client SDKs. Personal API key is for management/read (insights, cohorts, flags CRUD) – keep server-side, scope to the minimum permissions needed.

Why are some flag decisions returning false unexpectedly?

Three causes: (1) cohort dependencies haven't recalculated yet (is_calculating=true); (2) person_properties weren't sent on decide (server-side decisions need them passed in); (3) flag is set to active=false.

EU vs US – switchable?

No – pick at project creation. To migrate, export from one project and ingest into a new one in the other region. Event timestamps are preserved; person profiles are NOT linked across regions.

Self-host costs?

ClickHouse is the heavy bit – plan 16-32 GB RAM + fast disk for >10M events/month. PostHog ships Helm charts for k8s and Docker Compose for single-node. Postgres + Kafka + ClickHouse + Redis is the stack.

Related connectors

• Amplitude
• Mixpanel
• Google-analytics