> ## Documentation Index
> Fetch the complete documentation index at: https://help.statisfy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# PostHog Integration

> Connect PostHog with Statisfy to sync product usage, custom fields, and custom objects using HogQL queries.

### Connect PostHog with Statisfy

The PostHog integration lets you import product analytics data from your PostHog project into Statisfy using **HogQL** queries. Author queries in the Statisfy settings UI, preview results against your PostHog project, and schedule them to sync on a regular cadence — without writing any code.

The configuration model mirrors the warehouse integrations ([BigQuery](/integrations/bigquery_integration), [Snowflake](/integrations/snowflake_integration), [Postgres](/integrations/postgresql), [Redshift](/integrations/redshift_integration)). The difference is the query language: PostHog uses HogQL, a SQL-like dialect tuned for event analytics.

You can find the shared self-serve concepts — query types, resolvers, transformers, schedules, configuration history — in [Integration Concepts](/integrations/self_serve_configuration). This page focuses on what's specific to PostHog.

**Prerequisites:**

* **Admin access** to both **PostHog** and **Statisfy**
* A PostHog **Personal API key** with read access to your project
* Your PostHog **Project ID** and the **API host** (e.g., `https://us.posthog.com` or `https://eu.posthog.com`)

### What You Can Import

| Data Type          | Description                           | Use Case                                   |
| ------------------ | ------------------------------------- | ------------------------------------------ |
| **Product Usage**  | Time-series usage metrics per account | Track MAU, feature adoption, event counts  |
| **Custom Fields**  | Account-level attributes              | Sync segment, plan tier, engagement scores |
| **Custom Objects** | Domain-specific records               | Sync sessions, funnels, retention cohorts  |

### Generate a PostHog Personal API Key

1. Sign in to PostHog.

2. Open **Settings → Personal API keys** and create a new key with read access (HogQL query execution) for the project you want to connect.

3. Copy the key and note your **Project ID** (visible in the URL or project settings) and **API host**.

<Warning>
  Treat the API key as a credential — anyone with the key can run HogQL queries against your PostHog project. Use a dedicated key for Statisfy so it can be rotated independently.
</Warning>

### Steps to Connect

1. **Log in to Statisfy.**

2. Navigate to **Integrations → PostHog → Connect**.

3. Enter your PostHog credentials:
   * **API Host** — e.g., `https://us.posthog.com` or your self-hosted URL
   * **Project ID** — Your PostHog project identifier
   * **API Key** — The Personal API key you generated

4. Click **Test Connection** to confirm Statisfy can reach PostHog and authenticate.

5. Once connected, PostHog will appear as **Connected** on the Integrations page.

### Configure HogQL Queries

Open **Integrations → PostHog → Settings** to author and manage queries.

1. **Add a query.** Choose the query type — `product_usage`, `custom_field`, or `custom_object`.

2. **Write HogQL.** Use the in-app HogQL editor. The editor supports HogQL syntax and references your PostHog events, persons, and groups.

3. **Preview the results.** Click **Preview** to run the query against your PostHog project and inspect a sample of rows before saving. Because HogQL has no static schema browser, **preview-by-execution is the validation step** — if the preview returns the expected shape, the query is good to save.

4. **Map columns to Statisfy entities.** Use the same mapping editor as the warehouse integrations:
   * Pick the **account resolver** column (Statisfy account ID, CRM ID, organization ID, email domain, account name, or any custom field)
   * For `product_usage`, map the metric value, timestamp, and (optionally) the metric label
   * For `custom_field`, pick the field and value columns
   * For `custom_object`, map each attribute on the custom object

5. **Save and schedule.** Configure the cadence — daily, weekly, monthly, or sub-day — and Statisfy will run the query on schedule.

### Query Types

| Query Type      | Output                          |
| --------------- | ------------------------------- |
| `product_usage` | Time-series metrics per account |
| `custom_field`  | Account-level attribute values  |
| `custom_object` | Records of a custom object type |

### Account Matching

Each query specifies how its rows map to Statisfy accounts via an **account resolver**:

| Resolver                | Description                              |
| ----------------------- | ---------------------------------------- |
| **Statisfy Account ID** | Native Statisfy account identifier       |
| **CRM Account ID**      | Salesforce or HubSpot account identifier |
| **Organization ID**     | External org identifier                  |
| **Email Domain**        | Company website domain                   |
| **Account Name**        | Company name (fuzzy matching)            |
| **Custom Field**        | Any custom field defined on accounts     |

<Warning>
  Rows that don't resolve to an existing Statisfy account are skipped. Make sure the resolver column emits values already present in Statisfy — for example, email domains that match your CRM accounts.
</Warning>

### Sync Behavior

**Scheduled Jobs:**

* Each saved query runs on the cadence you configure.
* Self-serve configuration takes precedence. If a tenant has no saved configuration for PostHog, Statisfy falls back to any built-in computation set up by support.

**Error Handling:**

* Per-query errors are logged but do not block other queries from running.
* Invalid rows within a query are skipped and reported in the job audit log.

### Security

* Credentials are stored encrypted in Google Cloud Secret Manager.
* All connections use HTTPS.
* HogQL queries authored in the Settings page can only read data — PostHog's HogQL endpoint does not allow writes.

### Troubleshooting

<Accordion title="Connection test fails">
  * Verify the **API host** matches your PostHog instance (US Cloud, EU Cloud, or self-hosted URL).
  * Confirm the **Project ID** is correct.
  * Confirm the **Personal API key** is active and has access to the project.
</Accordion>

<Accordion title="Preview returns an error">
  * HogQL has no static schema browser, so syntax errors only surface on execution. Check the editor error message for the offending function or column.
  * Verify the events, persons, or groups referenced in the query exist in your PostHog project.
  * Reduce the time range or row limit if the preview times out — PostHog enforces its own server-side query timeouts.
</Accordion>

<Accordion title="Records not matching to accounts">
  * Verify the resolver column contains values that exist in Statisfy.
  * For CRM ID resolvers, confirm your CRM integration has synced the matching accounts.
  * Try a different resolver (for example, switch from account name to email domain) if matching is unreliable.
</Accordion>

<Accordion title="Schedule isn't running">
  * Confirm a schedule is configured under **Integrations → PostHog → Settings**.
  * Activity tracking must be enabled on the tenant — PostHog initialization is skipped when tracking is disabled.
</Accordion>

### Need Help?

For initial setup, HogQL query design, or troubleshooting, contact [support@statisfy.com](mailto:support@statisfy.com).