Skip to main content
Zenovaydocs
6 min read

PostHog Importer

Available on Pro and above. The PostHog importer is a one-shot tool that brings your historical PostHog pageview traffic into Zenovay, so you keep your history when you switch. It is not an ongoing sync.

What this does

  • Imports pageview traffic only — PostHog's $pageview event — aggregated per day.
  • Brings across daily visitors and pageviews, plus top pages, referrers, countries, devices, browsers and operating systems.
  • Runs in the background. Progress appears in the import history list on the same page.

What this does NOT do

The importer reads pageview traffic and nothing else. It does not import:

  • PostHog custom product events
  • Feature flags
  • Experiments
  • Surveys
  • Session recordings

It is also a one-shot historical migration, not an ongoing sync. Once the import finishes, Zenovay does not talk to PostHog again — new traffic comes from the Zenovay tracking script on your site.

Prerequisites

  • A Zenovay account on Pro tier or higher.
  • Your PostHog project ID — the numeric ID of the project you want to import.
  • A PostHog personal API key (starts with phx_).
  • Your PostHog region or self-hosted host.

A project API key does not work. The importer needs a personal API key. A project API key (the one embedded in your website snippet) is write-only for ingestion and the PostHog query endpoint answers it with 403.

Step-by-step

1. Create a personal API key in PostHog

In PostHog, go to Settings → Personal API keys and create a new key. The value starts with phx_. Copy it — PostHog only shows it once.

You can create the key read-only and scope it to the single project you are importing. That is all the importer needs.

2. Find your project ID

Your PostHog project ID is numeric. It appears in Settings → Project and in your PostHog dashboard URLs, for example the 2 in /project/2/dashboard.

3. Note your region

The importer needs to know which PostHog host to query:

  • US Cloud — https://us.posthog.com
  • EU Cloud — https://eu.posthog.com
  • Self-hosted — the host where your PostHog instance runs

Do not use app.posthog.com. That address redirects to the regional host, and the importer reports the redirect as a host misconfiguration. Pick the region that matches your project, or enter your self-hosted host directly.

4. Open the Import tab in Zenovay

Go to your site, then Data → Import, and choose PostHog.

5. Enter your details

Fill in:

  • Project ID — the numeric ID from step 2.
  • Personal API key — the phx_… key from step 1.
  • Region — US Cloud, EU Cloud, or your self-hosted host.
  • Date range (optional) — leave it empty and the importer takes the last 365 days ending yesterday.

6. Start the import and watch progress

Start the import. It runs in the background — you do not need to keep the page open. The import history list on the same page shows the status of each run.

7. Revoke the key when you are done

Because this is a one-shot migration, you can delete or revoke the personal API key in PostHog as soon as the import has finished. Zenovay does not need it again.

Rate limits and the "partial" status

PostHog rate-limits its query API: 120 queries per hour on legacy projects and 2,400 per hour on newer ones. A large import can hit that ceiling.

When it does, the import finishes with status partial. This is expected behaviour, and it does not mean the import failed:

  • The daily visitor and pageview series is fetched first, so it survives a rate limit. Your core traffic history is intact.
  • What gets skipped are some of the breakdown dimensions — top pages, referrers, countries, devices, browsers, operating systems — for part of the range.

If you want the missing breakdowns, wait for the rate-limit window to reset and run the import again for the affected period.

Why Zenovay reads through the query API

PostHog's own documentation deprecates their events API and steers bulk extraction towards batch exports that land in your own S3, BigQuery or Snowflake. That path requires you to own and operate a data warehouse, which is not a reasonable prerequisite for a migration. Zenovay therefore reads your history through PostHog's HogQL query endpoint instead, which returns the daily aggregates directly — at the cost of the query rate limits described above.

Troubleshooting

403 Forbidden

You are almost certainly using a project API key instead of a personal API key. Create one under Settings → Personal API keys in PostHog; it starts with phx_. If you scoped the key, confirm the scope includes the project you are importing.

"Host misconfiguration" or an unexpected redirect

You entered app.posthog.com. Replace it with your actual region — https://us.posthog.com or https://eu.posthog.com — or your self-hosted host.

"Project not found"

The project ID must be the numeric ID, not the project name and not the project API key. Check it under Settings → Project in PostHog.

The import finished as "partial"

That is the rate limit, not a failure. See the section on rate limits above — your daily visitor and pageview series is complete; some breakdown dimensions were skipped.

Numbers differ slightly from PostHog

PostHog and Zenovay count visitors and filter bots differently, so expect small deltas. Zenovay imports only $pageview events, so any PostHog figure that includes custom events will be higher.

Related Resources

Need help? Contact support@zenovay.com or visit our Help Center.

Was this page helpful?