Skip to main content

PostHog Integration

Connect PostHog to let the AI agent query your product analytics during investigations. The agent runs the PostHog CLI (posthog-cli api) in its sandbox to run HogQL/SQL over your events, persons, and sessions, and to read session replays, error-tracking issues, feature flags, and deploy annotations — so it can correlate user impact and releases with an incident.

You can connect in one of two ways:

  • OAuth (recommended) — authorize Autoheal with a few clicks; nothing to create or rotate. The region (US/EU) is detected automatically. PostHog Cloud only.
  • Personal API key — paste a read-only key; works for PostHog Cloud and self-hosted, and is the method to use if you self-host.

Capabilities​

Once connected, the AI agent can:

CapabilityHow
Query data (HogQL/SQL)posthog-cli api call execute-sql over events, persons, sessions, and $exception events — the primary way to correlate errors, sessions, and metrics with a release/time window
Session replayList recordings and read metadata / replay links; pivot from an error's $session_id straight to the replay
Error trackingRead error-tracking issues, exception events, and stack traces
Feature flagsRead feature flags and their state (flag flips are a common incident cause)
AnnotationsRead deploy/incident markers to line up an incident with a release
Insights & dashboardsRead saved insights and dashboards
1
Open the integration

Go to Integrations in Autoheal, click PostHog, and keep the default OAuth method selected.

2
Authorize

Click Connect with PostHog. You'll be redirected to PostHog to approve read-only access. Approve, and you'll be sent back to Autoheal with the integration connected.

3
Done

Autoheal stores the OAuth token (encrypted) and auto-refreshes it — there's nothing to rotate. The region your PostHog account lives in (US or EU) is detected automatically.

note

OAuth requests read-only access across all PostHog resource types (every :read scope, plus identity) so investigations can read whatever they need — but never any write scope. You review and approve the grant on PostHog's consent screen, where you can also narrow it if you prefer.

Connect with a Personal API Key​

1
Create a read-only key

In PostHog, go to Settings → Personal API keys and create a key with read-only scopes. The simplest safe choice is the "Read-only access" preset (all :read, no writes). If you prefer least-privilege, use the "MCP Server" preset (query, session_recording, error_tracking, insight, dashboard, feature_flag) and additionally enable user:read and annotation:read — see Required Permissions for the full list. Restrict the key to the project(s) the agent should read.

warning

user:read is required — the PostHog CLI resolves the current user before every call and fails without it. The "MCP Server" preset does not include it, so add it explicitly (or use "Read-only access").

2
Add it in Autoheal

In Integrations → PostHog, switch the method to Personal API Key, then enter:

  • Personal API Key — the phx_... key
  • Host — us.posthog.com, eu.posthog.com, or your self-hosted domain (no scheme)
  • Default Project ID — optional; set it for single-project setups
3
Save

Enter a name (e.g., "PostHog Production") and click Save.

warning

PostHog US and EU are separate data planes and a personal API key is region-bound — it only works on the region it was created in. Make sure Host matches that region, and do not use an ingestion host (us.i.posthog.com / eu.i.posthog.com); reads use the app host. (OAuth avoids this — the region is detected for you.)

Correlating with deploys​

PostHog does not enforce a single way to tag releases, so tell Autoheal how you do it (via the integration's context form). The agent can correlate incidents to deploys using any of:

  • Annotations — deploy markers pinned to a timestamp
  • Error-tracking Releases — created by posthog-cli sourcemap upload with git metadata (commit-level linkage)
  • Event properties — a version property (commonly $app_version, but often a custom name) and an environment property or PostHog's Environments feature
tip

There is no guaranteed property name for version/environment — capture yours in the integration context so the agent filters on the right property instead of guessing. If you don't tag a version at all, the agent correlates errors to deploys by time window + stack trace + the linked session replay.

Example Queries​

Once connected, you can ask the AI agent questions like:

Did errors spike in production after the last deploy? Break exceptions down by release.
Show session replays for users who hit the checkout error in the last hour.
Which feature flags changed in the 24h before this incident?
What deploy annotations are near this incident window?

Required Permissions​

Read-only access only. With OAuth, Autoheal requests these read scopes automatically. With a personal API key, create it with only these :read scopes:

ScopeWhy It's Needed
user:readRequired — the PostHog CLI resolves the current user (/api/users/@me/) before every call and aborts without it. Not part of the "MCP Server" preset, so enable it explicitly.
query:readRun HogQL/SQL queries (the primary read path)
session_recording:readList and read session recordings
error_tracking:readRead error-tracking issues and exceptions
feature_flag:readRead feature flags and their state
insight:read / dashboard:readRead saved insights and dashboards
annotation:readRead deploy/incident annotations
warning

PostHog API rate limits are applied org-wide across all keys. For the API-key method, provision a dedicated key (ideally under a bot user) so Autoheal's reads don't compete with your team's dashboards.

Troubleshooting​

The 'Connect with PostHog' button isn't shown

OAuth isn't enabled on your Autoheal instance. Use the Personal API Key method instead (it offers the same capabilities), or ask your Autoheal administrator to enable PostHog OAuth.

401 / Authentication failed (API key)
  • Verify the personal API key is correct and not revoked.
  • Confirm Host matches the region the key was created in — a US key does not work on eu.posthog.com and vice versa.
403 / Missing scope
  • The key (or OAuth grant) is missing a required :read scope, or is restricted to a different project. The most common cause is a missing user:read (the "MCP Server" preset omits it). Re-create the key with the scopes above — or use the "Read-only access" preset — and access to the target project. For OAuth, reconnect so the new grant includes user:read.
Empty results
  • Check you're querying the right project ID.
  • If filtering by version/environment, confirm the property name — PostHog enforces no standard, so the property may not be $app_version.
  • Confirm the data exists for the time window (events may be sampled or retained for a limited period).
429 / Rate limited
  • PostHog rate limits are org-wide. Prefer fewer, bounded HogQL queries over many small calls, and use a dedicated key.

Additional Resources​