How to migrate from PostHog to Tracwell
· 5 min read
You can move from PostHog to Tracwell in an afternoon and keep your traffic history. Tracwell reads your past pageviews from PostHog's Query API, turns them into daily reports, and shows them in the same dashboard as your new visits. Then you switch your events over and remove PostHog.
This guide covers every step, in order.
What comes over, and what doesn't
The import brings over web traffic, counted per UTC day:
- Pageviews and unique visitors for every day
- Pages, referrers, countries, devices, browsers and operating systems, with the top 10 values per day
It does not bring over custom events, sessions, person profiles, event properties, session replays, feature flags or experiments. Tracwell imports summaries, not individual events. Your custom events start fresh in Tracwell from the day you send them.
Before you start
You need:
- A Tracwell website, which you create when you sign up
- Owner or admin access to that website in Tracwell
- Access to the PostHog project you are leaving
- Your PostHog region: US Cloud (
us.posthog.com) or EU Cloud (eu.posthog.com)
Self-hosted PostHog is not supported.
Step 1: Add Tracwell next to PostHog
Install Tracwell first and leave PostHog running. Open Settings → Website → Tracking setup in Tracwell and copy the snippet. Paste it inside <head> on every page:
<script
defer
src="https://collect.tracwell.app/script.js"
data-project-key="tw_live_..."
data-collection-mode="private"
></script>Or install the package:
pnpm add tracwellimport { createTracwell } from "tracwell";
export const analytics = createTracwell({
collectionMode: "private",
projectKey: "tw_live_...",
});Pageviews are tracked automatically. Write down the date Tracwell starts collecting. You need it in step 4.
Private mode keeps nothing on the visitor's device. If you used posthog.identify() and want returning visitors or revenue attribution, choose Product mode instead. The docs explain the difference.
Step 2: Create a PostHog personal API key
The import needs a personal API key, not your project token.
- The project token starts with
phc_. It is the public key in your PostHog snippet and can only send events. - A personal API key starts with
phx_. It can read data, which is what the import needs.
To create one:
- In PostHog, open Settings → Personal API keys and click Create personal API key.
- Give it a label, such as "Tracwell import".
- Set Expiration to 7 days. You only need the key for the import.
- Under Organization & project access, choose Projects and select only the project you are leaving.
- Under Scopes, search for
queryand set Query to Read. Leave everything else at No access. - Create the key and copy it. PostHog shows it once.
Tracwell uses the key only while it previews and saves the import. It is never stored.
Step 3: Find your project ID and region
Your project ID is the number in your PostHog URL, for example us.posthog.com/project/12345. It is also listed under Settings → Project.
Your region is the first part of that URL: us or eu.
Step 4: Choose your dates
Tracwell imports completed UTC days, up to 366 days per import.
Make the import end the day before Tracwell started collecting. For days covered by an import, the dashboard shows the imported numbers instead of Tracwell's own, so ending the import before your first day of Tracwell data keeps both.
For more than a year of history, run several imports with ranges that don't overlap. Tracwell rejects an import that overlaps one you already saved.
Step 5: Preview and import
- In Tracwell, open Settings → Import data.
- Click Import next to PostHog.
- Choose the destination website.
- Paste your personal API key, enter the project ID, pick the region and set your dates.
- Click Preview history.
The preview shows daily pageviews and visitors, and every breakdown, before anything is saved. Check that the totals look like PostHog's for the same days.
When it looks right, click Import data. Tracwell reads PostHog again, saves the import, and the history appears on your dashboard once it is stored. Nothing changes in PostHog. If you imported the wrong range, click Undo all imports on the same page and run it again. Undo switches the dashboard back to Tracwell's own data and deletes nothing.
Step 6: Move your custom events
PostHog's tracking calls map directly:
| PostHog | Tracwell |
|---|---|
Automatic $pageview | Automatic page views |
posthog.capture("signup_completed", { plan: "pro" }) | analytics.track("signup_completed", { plan: "pro" }) |
posthog.identify("customer_123") | analytics.identify("customer_123") (Product mode) |
posthog.reset() | analytics.reset() |
With the script tag, use window.tracwell?.track(...).
Keep the same event names. Your funnels and goals in Tracwell can then match the ones you had in PostHog. Use opaque internal IDs in identify(), never email addresses.
If you sent revenue to PostHog as event properties, send payments to Tracwell from your server instead. Revenue by traffic source shows how to tie each payment to the visit it came from.
Step 7: Remove PostHog
Run both tools side by side for a few days and compare daily visitors. When the numbers line up, remove the PostHog snippet or package from your site, then delete the personal API key in PostHog.
Why the numbers can differ
Some differences are expected:
- Days are UTC. PostHog's dashboard uses your project's timezone. Tracwell imports whole UTC days, so traffic near midnight can move to the next or previous day.
- Visitors are PostHog persons. A visitor is a distinct PostHog person on that day. Visitors added up across several days are an estimate.
- Breakdowns keep the top 10 per day. On busy days, a breakdown can add up to less than the day's total.
- Browser and OS names are matched to Tracwell's. For example,
Chrome iOSbecomes Chrome,Mobile Safaribecomes Safari, andMac OS Xbecomes macOS, so imported and new traffic group together.
Troubleshooting
- "PostHog denied access." The key is a project token, has expired, lacks Query Read, or belongs to the other region. Check the key prefix (
phx_) and the region. - "PostHog could not find this project." The project ID is wrong for that region.
- "No pageviews were found in these dates." PostHog has no
$pageviewevents in that range. Check your dates. - "PostHog could not run this query." Very large projects can hit PostHog's query time limit. Import a shorter range, then import the rest in further ranges.
- "Choose a shorter date range for this import." The import is too large for one save. Split it into shorter ranges.
The import docs cover every provider Tracwell can import from.
See where your customers come from
Free up to 10K events a month · No card required