Connect PostHog

Previous Next

Connect PostHog

Connect PostHog to calibrate your AI shoppers using recorded pageview traffic. Squoosh reads device, geography, and traffic-source mix. An optional conversion event provides a conversion rate based on distinct sessions.

Beta

This connector uses PostHog's Query API. Provider restrictions and the completeness limit below can affect availability.

What the connection does

Squoosh reads aggregate query results from your PostHog project to shape the AI shopper pool. Device, geography, and traffic source are weighted by pageview events, so a visit with multiple pageviews contributes multiple times. The conversion calculation uses distinct session IDs instead.

A connection is optional. See AI shoppers for how calibration works.

Connect PostHog

You need a personal API key with Query Read (query:read) permission, your project's host, and its ID. See PostHog's query prerequisites.

  1. In PostHog, create a personal API key in your user settings, with Query Read permission for the intended project. Get the project ID from project settings.
  2. In Squoosh, open Integrations, find PostHog, and click Connect.
  3. Enter:
  4. Personal API key: the key you created. Squoosh keeps it private after saving.
  5. Host: https://us.posthog.com for US Cloud, https://eu.posthog.com for EU Cloud, or your public HTTPS self-hosted instance. There is no default.
  6. Project ID: the project to read.
  7. Conversion event (optional): the exact event name for a purchase or signup, such as order_completed. Leave it blank to omit conversion calibration.
  8. Click Connect. Squoosh checks the key and project before saving and starting the first calibration read.

What Squoosh reads

Dimension Source Counting basis
Device $device_type Pageview events
Geography $geoip_country_code Pageview events
Traffic source $referring_domain, utm_medium, utm_source Pageview events, grouped into Squoosh categories
Conversion rate $session_id and your conversion event Distinct converting sessions divided by distinct sessions with a pageview or conversion event

The adapter requests aggregate counts. It does not request session recordings, person profiles, or individual event exports. A small sample does not become a guessed distribution: the shared calibration rules omit dimensions below the sample floor.

Limits and caveats

  • Missing session IDs: events without $session_id are excluded from both conversion counts. PostHog's server SDKs do not send this property by default. The resulting rate describes sessions with IDs; the missing data does not establish whether it overstates or understates your overall rate. See PostHog sessions.
  • No conversion event means no conversion signal. Squoosh does not invent one.
  • Completeness ceiling: each grouped query requests up to 50,000 rows. Raw HogQL query responses do not reliably populate hasMore, so the current adapter cannot establish completeness at that ceiling. High-cardinality traffic-source mixes can therefore be incomplete. See PostHog's query executor.
  • Caching and quotas: a read uses three queries, plus one when a conversion event is configured. PostHog documents 2,400 requests per hour, 240 per minute, and three concurrent queries. Legacy deployments may apply a 120-per-hour HogQL throttle. Default query execution can reuse cached results, so an immediate recheck may return the same numbers. See Query API limits and caching and legacy throttle source.
  • Provider restrictions: PostHog directs third-party connectors to batch or file download exports and states that Query API connectors can be rate-limited or rejected. This connector currently uses the Query API. Waiting can help with temporary throttling; it does not guarantee recovery from a policy rejection. See PostHog's Query API policy. A change to the integration's data path remains a follow-up.

Troubleshooting

Problem What to do
Authentication error (401 or 403) Confirm you used a personal API key and that it has not been revoked. Check the host and region.
Permission error (403) Enable Query Read for the intended project and check the key's project access.
Project not found (404) Correct the host or project ID. Repeating the same request will not fix a missing project.
Query rejected (400) Contact Squoosh support. Query validation errors require investigation rather than automatic retries.
Query execution cap reached The query exceeded PostHog's execution limit. Contact support to review the supported read window.
Billing or quota limit (402) Check PostHog Billing settings with an organization admin. Automatic retries are disabled for this response.
Rate limited (429) Wait before retrying. If rejection persists, ask support to investigate project quotas and provider restrictions.
No conversion rate Configure the exact conversion event name and confirm those events carry session IDs.
Connect Microsoft Clarity Connect Mixpanel