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

# PostHog

> Connect PostHog with OAuth or an API key, map events to customers, and pull product usage metrics into Quivly on a schedule.

The PostHog integration pulls product usage out of PostHog and into each customer's [Usage tab](/customer-views/usage-tab) and [health score](/health-scores/introduction).

## Connecting

Go to **Settings → Integrations → PostHog**. Two options:

* **Connect with OAuth** — sign in to PostHog and approve.
* **Connect with an API key** — paste a Personal API key (`phx_...`) with `query:read` and `endpoint:read` scopes, choose your region (US Cloud, EU Cloud, or Self-hosted), and enter your instance URL if self-hosted.

## Configuring the sync

The sync itself is configured under **Product Usage** settings:

| Setting             | What it does                                                                        |
| ------------------- | ----------------------------------------------------------------------------------- |
| Project             | Which PostHog project to pull from                                                  |
| Customer identifier | How PostHog events map to your customers — a group type or an event/person property |
| Events              | Optional allowlist of events to include                                             |
| Schedule            | Daily, weekly, or manual only                                                       |
| Backfill            | How many days of history to pull (1–365, default 90)                                |

Before publishing, click **Run test sync** — it dry-runs the last 7 days and shows which customers matched and which didn't, so you can fix the identifier mapping before any data lands. Once verified, **Publish** turns the scheduled sync on.

## FAQ

<AccordionGroup>
  <Accordion title="What does Quivly store from PostHog?">
    Daily metric values per customer (date, customer, metric, value) — not raw event streams.
  </Accordion>

  <Accordion title="Why are some customers unmatched in the test sync?">
    Their identifier in PostHog doesn't resolve to a Quivly customer. Adjust the customer identifier setting or the external IDs on your customers.
  </Accordion>

  <Accordion title="Can I sync more often than daily?">
    Schedules are daily, weekly, or manual — daily is the fastest cadence.
  </Accordion>
</AccordionGroup>